Graph document API version before first release
Versioned draft snapshot
RFCs, reference catalogs, and evidence reflect Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. Counts and pending/status notes belong to that snapshot. Read the dated project update for later progress.
Source repositories are private during staging. Links marked “repository access required” need access to the linked repository.
This is a trace and gap record from the pinned draft specification. It does not establish proof or implementation conformance.
Implementation choice recorded October 18, 2026: graph.gnomon.sh/v1 is
selected under the owner’s standing gnomon.sh instruction and no-deployment
decision. The recommendation below resolves the initial identity choice;
source adoption, owning generation and consumer/projection verification remain
pending. Domain decision (Gnomon source: gnomon/DOMAIN_DECISIONS.md#graph-document-envelope; public source link pending).
The owner selected gnomon.sh for new Gnomon API identities and confirmed
that nothing is deployed. Kubernetes Graph CRDs now use graph.gnomon.sh;
this document version is a separate identity and is not a CRD group.
The active shared Zod schema in
gnomon/core/packages/common-schemas/document.ts still requires
apiVersion: graph.savvi.io/v1. Graph module and template source files and
tests use that value. RFC-0039 and RFC-0040 instead show gnomon/v1 in their
authored envelopes and Lean/RDF projections. These legacy values are
superseded by the selected first-release identity above. A historical local scan found 135 files across the framework and
spec containing either of those two values, including generated catalogs and
the framework’s temporary spec copy. The count is an inventory, not a list
of files to replace blindly.
Recommendation
Use graph.gnomon.sh/v1 for the graph document envelope shared by Module and
Template. It follows the selected domain and the Graph API family while
keeping the document version distinct from graph.gnomon.sh/v1alpha1 CRDs.
Because no Gnomon document has been deployed, make one source-level switch
before release without a compatibility alias. Update the Zod constant, module
and template producers, checked-in documents and fixtures, JSON Schema,
authored RFC-0039/0040 text, Lean grammars, protobuf RDF sources, generated
Turtle/reference, and consumer checks together. Keep historical migration
records and source snapshots as evidence rather than rewriting them.
Using gnomon.sh/v1 would also satisfy the domain choice but obscure the
Graph-specific document family. Retaining gnomon/v1 or
graph.savvi.io/v1 would conflict with the stated first-release domain
preference and with each other.
Acceptance criteria
- Module and Template schemas accept the chosen version and reject both old
values; compiler output, loaders, fixtures, and checked-in
.graph.yamlfiles agree. - The authored RFCs, Lean grammars, RDF source and regenerated outputs use the chosen value; source-bound reviews are refreshed and semantic drift checks pass.
- Build and run the graph module/template model, compiler, and executor tests, plus the published graph dependency closure. Verify the JSON Schema and representative bundled documents against the runtime parser.
- Keep the document identity separate from Kubernetes CRD versions and
record the first-release choice in
gnomon/DOMAIN_DECISIONS.md.