gnomonlearn
Docs/RFC-0036 graph ID allocation boundary

RFC-0036 graph ID allocation boundary

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.

Status: owner decision required before normative release. Owners: Graph Platform, Storage, spec. No Gnomon deployment needs an ID migration.

Authored contradiction

RFC-0036 §3.1 says every graph ID is backend-allocated and never caller-supplied. The same RFC’s §4.1 ResourceInput contains an optional id: bigint with the comment “usually backend-allocated.” The Lean schema reproduces that optional field while its identity claim says never caller-supplied. §3.1 also permits per-module ID ranges allocated by the install engine. The claim projection currently states the absolute prohibition.

The PostgreSQL graph.create_resource function accepts p_id and documents deterministic IDs used by module manifests. Its batch writer and TypeScript adapter forward explicit IDs. The object-store resource writer also accepts input.id. These are implemented public write shapes, so choosing one sentence as canonical without reviewing callers would silently change the contract.

Recommendation

Define two allocation authorities. Ordinary application create requests omit id and receive one from the backend. A privileged install/import operation may supply an ID only from a range that the backend has already reserved for that module, and the backend validates uniqueness across entity types. Expose the privileged operation as a distinct input or capability so normal callers cannot set id accidentally. Preserve deterministic install identity without contradicting the application-facing rule. The current ResourceInput.id and p_id paths need access control and range validation before publication; no deployed Gnomon state needs conversion.

The simpler alternative is strict backend allocation everywhere: remove optional IDs from the write contract and adapt module installation to stable (kind, externalId) handles. This removes the reserved-range feature and requires checking every installer and historical pin before deleting the current explicit-ID paths.

Acceptance criteria

  1. State the allowed ID supplier and scope in RFC-0036, Lean, RDF claims, backend model, and installer contract. Clarify global uniqueness and monotonicity when reserved ranges exist.
  2. Verify scalar and batch PostgreSQL, object store, memory, and gRPC write behavior; reject unauthorized explicit IDs before mutation. Test cross-type collisions and idempotent reinstall.
  3. Regenerate reference and projection artifacts, rebind affected reviews, run the diagnostic and graph conformance gates, and repin the site.

Owner decision

Choose backend allocation with a separate privileged reserved-ID install path, or strict backend allocation for every create.