gnomonlearn
Docs/Graph document API version before first release

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

  1. Module and Template schemas accept the chosen version and reject both old values; compiler output, loaders, fixtures, and checked-in .graph.yaml files agree.
  2. The authored RFCs, Lean grammars, RDF source and regenerated outputs use the chosen value; source-bound reviews are refreshed and semantic drift checks pass.
  3. 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.
  4. Keep the document identity separate from Kubernetes CRD versions and record the first-release choice in gnomon/DOMAIN_DECISIONS.md.