gnomonlearn
Docs/External ID scope decision

External ID scope decision

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.

Owner: Gnomon spec and graph. Status: proposed; no normative or formal source changed.

Evidence

  • RFC-0036 §3.3 says (kind, externalId) is unique within a backend, then says an externalId cannot be reassigned after deletion without repeating the kind qualifier. Its diagnostic M36061 explicitly says reuse is forbidden within this kind.
  • The graph substrate has UNIQUE (kind, external_id) in graph/schema/substrate/005_tables_emitted.sql. Its source emitter states that the same external_id may exist under different kinds. The graph proto and service use (kind, external_id) for create, upsert, and lookup.
  • The pinned external fastverk/spec framework at 3725bd9f6d2711aa9bb179deea84f51e4424382a has an opaque ExternalId and an externalIdAllocated : ExternalId → Resource → Time → Prop predicate. AX-010 says two allocations of the same ExternalId at any times imply the same Resource, with no kind premise. Its comment calls that identifier backend-wide unique. This is stricter than the RFC and backend key.
  • The two current RFC-0036 derivation candidates deriv_d47cb6d1a00f and deriv_89cd18bae843 reuse AX-010’s global proposition. Neither is counted as a source-bound semantic match while the identity scope is unresolved.

Keep (kind, externalId) as the identity key. Clarify RFC-0036 §3.3’s no-reassignment sentence to say within the same kind, including after soft deletion. Preserve the existing graph wire contract and unique index. Change the external formal model so allocation and permanence are keyed by kind and external ID, and revise AX-010 and the two derivations to express that scope. A bare external ID can be reused under a different kind.

This follows the published unique-key rule, existing database constraint, proto/API lookup shape, and M36061. The alternative, global external-ID uniqueness, would change the published contract and require a database constraint, migration, stored-data collision audit, and API behavior changes.

Acceptance criteria after the owner decides

  1. State the exact scope in RFC-0036 narrative, Lean catalog, generated references, diagnostic text, and graph contract. Preserve RFC identifiers.
  2. If kind-scoped, replace the external formal AX-010 signature with a kind-scoped allocation relation or explicit same-kind premise. Prove both derivations against that relation and record source-bound semantic reviews. A formal theorem alone does not establish backend enforcement.
  3. Test two Resources with the same external ID under different kinds, reject duplicates within a kind, and reject reassignment within a kind after soft deletion. Verify the generated schema constraint and graph service path.
  4. Audit persisted data and consumers before any identity migration. Run the normative drift, graph, cross-repo, and site gates after source changes.

No backend or formal dependency was changed by this proposal.