ADR-002: Stable Identity And Supersession

• Status: Conditional; accepted only when F2-002-W01 is accepted and landed on main
• Date: 2026-08-18
• Roadmap task: F2-002
• Decision owners: corpus architecture and schema governance maintainers

Context

Munderecat entities will be cited, curated and connected across corpus releases, languages and annotation domains. Database sequence values or IDs regenerated from current text would make those references unstable. Keeping an incorrect row forever as the current truth would be equally harmful: compound boundaries, lexical decisions and even source text may need correction.

ADR-001 separates immutable accepted core releases, reusable domain authority, release-anchored occurrence annotations, control evidence and caches. Each layer now needs an identity lifecycle that preserves historical addressability without letting old identity dictate current truth.

This ADR decides public identity and supersession semantics. It does not choose the physical entity registry, foreign-key layout, span coordinates, corpus package encoding or compatibility-review workflow owned by later F2 tasks.

Decision

Identity principles

Every public referenceable entity has one globally unique, opaque UUID and one declared entity kind. Identity is a durable handle to a historical referent, not a hash of its current display text and not a claim that the entity remains current.

The following rules apply to core, annotation-layer and future reference entities:

• an issued public ID is never changed, reassigned or reused;
• equal text at different corpus occurrences has different occurrence identity;
• one semantic definition and each of its corpus occurrences have different IDs;
• database insertion order, sequence values, timestamps, normalized text and mutable labels are never identity inputs;
• an ID remains resolvable after rejection, retirement or supersession;
• current/recommended status is separate from identity; and
• APIs return entity kind with the opaque UUID rather than asking clients to infer kind from the UUID or a table name.

Typed domain tables remain authoritative for their entities. Global uniqueness does not authorize unconstrained table_name + record_id polymorphism; F2-013 will list which entity kinds are referenceable and how typed endpoints are enforced.

Two creation contracts

Munderecat uses two non-overlapping public ID creation contracts. Before an entity kind or curated dataset can issue its first public ID, its governing contract fixes one issuance channel: package_deterministic or curation_generated. That choice is immutable for existing entities.

An unpublished interactive contribution that enters a deterministic package receives its first public ID from that package. An entity that already received a UUIDv7 through curation keeps that UUID in every later package; packaging does not remint it as UUIDv5. Likewise, a package-owned entity is never recreated through the interactive channel. Mixed datasets carry each entity’s declared issuance channel instead of choosing a rule from the current import path.

Deterministic bootstrap identity

Entities emitted by a canonical, reproducible import package use UUIDv5. The fixed Munderecat root namespace is:

da8a3026-eca7-56e9-ba87-c4b5080271a8

It is UUIDv5 of the DNS namespace and munderecat.org. Changing this value or the identity-name schema is a breaking identity event, not a refactor.

The UUIDv5 name bytes are RFC 8785 canonical JSON encoded as UTF-8 after every input string is normalized to Unicode NFC:

{"identity_schema":"munderecat-id-v1","kind":"sentence_occurrence","path":["tr-2026-v1","sozler/001",12,3]}

The keys therefore appear in the shown lexical order, and path is an ordered array of string or integer segments. Integer segments are restricted to the interoperable non-negative safe-integer range 0..9007199254740991. Larger coordinates are lowercase ASCII decimal strings matching 0|[1-9][0-9]*; leading zeroes and signs are forbidden. The identity payload has exactly identity_schema, kind and path; adding a field or changing pre-canonicalization normalization requires a new identity schema version.

Each canonical package declares an immutable identity_release_key before IDs are generated. The key is unique in the project and is permanently bound by control evidence to one source-input manifest, one identity schema and one entity-path manifest. Reusing the key with different inputs or paths is forbidden. It is not computed from generated package bytes, avoiding a digest/ID cycle.

Every UUIDv5 path issued by a package begins with that package’s identity_release_key. Core occurrence paths continue with stable source locator and structural occurrence coordinates declared by the package compiler. Domain authority and other package-owned paths continue with their versioned domain coordinates. They never use database IDs or mutable human labels. Rebuilding the same accepted package therefore produces identical UUIDs regardless of row insertion order.

Deterministic UUIDv5 is also permitted for version-controlled curated datasets only when their pre-publication contract declares package_deterministic, a permanent identity release key and stable identity paths. A later package preserves any already issued UUID, regardless of version. An ad hoc runtime matcher cannot mint deterministic public IDs from normalized text.

The exact path grammar for each entity kind belongs to its package/schema contract. Before a kind can issue IDs, that grammar must be versioned, collision-tested and listed by the F2-013 entity catalog.

Generated-once curation identity

Entities created interactively or after a package release use RFC 9562 UUIDv7. The approved application or database boundary generates the UUID once, persists it in the same transaction as the entity and never recomputes it from entity values.

UUIDv7 ordering is an operational property, not semantic chronology or authority. Clock values, creation order and UUID byte order cannot decide which curation record is correct or current. If the platform lacks native UUIDv7 generation, a tested standards-conforming generator must be used. A release that cannot generate or validate UUIDv7 fails before issuing public identities; it does not silently fall back to another UUID version.

No entity may switch between UUIDv5 and UUIDv7 after its first public identity is issued. Importing a generated-once curated entity into another database preserves its stored ID.

Identity-bearing facts

Each entity kind must publish an identity contract before schema implementation. The contract lists facts that define the referent and facts that may change without changing it. The generic rules are:

Change	Identity effect
Add provenance, review evidence, confidence or an editorial note	Preserve ID and append a curation/control event
Change lifecycle status or choose a recommended record	Preserve ID; status is not identity
Correct a non-semantic display label without changing the represented value	Preserve ID and record the correction
Change an accepted core release’s exact text, hierarchy, parent, boundary or order	New core release and new affected occurrence IDs
Change an occurrence annotation’s core release, selected span, parent or ordered member occurrences	New occurrence annotation ID
Change what a compound, lexeme, sense, orthographic form or relation kind denotes	New domain-authority ID
Add another occurrence of an existing definition	Preserve definition ID; issue a new occurrence ID
Recompute a cache or denormalized projection	No public identity; cache IDs carry no authority

When a proposed edit is not clearly identity-preserving under the kind’s contract, it is identity-changing. Maintainers create a successor rather than mutate the referent in place. F2-018 will classify the public compatibility impact; it cannot redefine the identity-bearing facts without superseding this ADR.

Definition, variant and occurrence

Identity is not shared merely because records are related:

• a compound definition such as lisan-i hal has a domain-authority ID;
• a recognized surface variant such as lisan-i haliyle has its own variant ID if the domain model exposes variants as entities;
• every matched span in a sentence has an occurrence-annotation ID; and
• the token occurrences covered by that span retain their independent core IDs.

The same separation applies to lexemes and analyses, Ottoman forms and renderings, dictionary senses and sense selections, repetition clusters and passage occurrences, and translation units and alignment edges. ADR-004 will decide the token form/occurrence representation, but cannot collapse these identity classes.

Changing one definition does not rewrite occurrence IDs. A curation operation may supersede the definition and separately migrate selected occurrence assertions with explicit events. Existing references continue to identify the historical records.

Supersession event model

Supersession is an append-only, evidence-bearing event with typed predecessor and successor sets. It never overwrites a foreign key on historical references. Accepted events support these cardinalities:

Event	Predecessors	Successors	Meaning
replacement	1	1	One corrected referent replaces one historical referent
split	1	2 or more	One referent is replaced by several distinct referents
merge	2 or more	1	Several referents are replaced by one referent
restructure	2 or more	2 or more	A reviewed many-to-many remodelling with no lossless redirect
retirement	1 or more	0	Referents are withdrawn with no replacement

All participants in one event have the same entity kind and authority domain. Cross-kind evolution is represented by an explicit typed relation, not supersession. Each event records reason, evidence, actor, decision time and the curation or release context selected by later provenance contracts.

The project-canonical accepted supersession graph must be acyclic, contain no self edge and move from older accepted state to newly issued identity. One predecessor can participate in at most one accepted outgoing event globally. One successor can appear in at most one accepted incoming event; converging predecessors must be members of the same merge or restructure event rather than separate replacement events. Every successor is issued after all predecessors in its event. Competing interpretations remain proposals or typed non-supersession relations until review selects one canonical event.

A mistaken supersession event is not edited away. It is invalidated by a later curation decision that preserves the event as history and establishes the corrected path. The concrete event-state model belongs to the production curation lifecycle.

Resolution behavior

Historical lookup and current resolution are separate operations:

• get exact ID returns that entity, lifecycle state and supersession summary even when it is no longer recommended;
• resolve current requires an explicit, versioned resolution policy ID, follows only events accepted by that policy and returns the policy ID plus the complete traversed event chain; the project reader may name one default policy in its API contract but storage never chooses from context implicitly;
• a 1-to-1 replacement may expose one recommended successor, but APIs do not silently rewrite the requested ID;
• split, merge, restructure and retirement return explicit set or terminal results; they never guess one redirect target; and
• references continue to target the ID originally authored. Propagation to a successor, translation or canonical repeat is a later explicit policy decision.

Permanent public URLs therefore do not become 404 merely because an entity was superseded. Authorization and visibility policy may still conceal an entity, but absence is not used as a synonym for retirement.

Every participant of an accepted supersession event must resolve to an issued, typed entity when the event is published. Successors and the accepted event are published atomically in one curation or release transaction. A successor that is later retired remains historically resolvable and its own lifecycle is returned. If storage corruption or an incomplete import leaves a participant unresolved, the resolver returns an explicit integrity_error with the event ID and stops; it does not skip the event, guess a target or reinterpret the predecessor as current.

Core release correction

An accepted core release is never repaired in place. A source correction creates a new text-release identity and new IDs for affected release-scoped occurrences. The compiler emits an exact crosswalk and candidate supersession events between old and new entities. Unchanged-looking text does not authorize ID reuse across release boundaries; explicit cross-release equivalence or supersession carries continuity.

Logical work or edition entities may persist across releases only when their own identity contracts define them independently of release-scoped text. A book, chapter, paragraph, sentence or token occurrence cannot keep an ID if doing so would make one ID denote two different accepted reconstruction facts.

Legacy and external identifiers

Legacy integers, source-local keys, external dictionary IDs, URLs and aliases are typed crosswalk records with at least source system, source release, entity kind and external value. They are not canonical public IDs and are not UUIDv5 path inputs unless a future accepted package contract explicitly promotes an immutable source locator distinct from the legacy database identity.

The same external value may occur in different source systems or entity kinds. Unqualified alias lookup is therefore invalid. Crosswalk correction uses curation history and uniqueness constraints; it never changes the canonical entity UUID.

Required enforcement properties

Later schemas, compilers and APIs must enforce:

1. UUID uniqueness across every public entity kind, one immutable issuance channel per issued entity and uniqueness of each declared deterministic (identity_schema, kind, path) input.
2. Exact reproduction of all UUIDv5 IDs in two fresh builds of the same package, including RFC 8785/NFC and safe-integer fixtures and the release key as every package path’s first segment.
3. Permanent binding of every identity release key to its input and path manifests, and preservation of already issued IDs in later packages.
4. Immutable entity UUIDs and prohibition of physical deletion after publication.
5. Typed, same-kind supersession participants; valid cardinality, no self edge and no accepted cycle.
6. At most one accepted outgoing event per predecessor and one accepted incoming event per successor; convergence is represented by one merge/restructure event.
7. Atomic publication and resolvability of every accepted event participant; incomplete state returns integrity_error and no successor result.
8. Retained tombstone/resolution responses for rejected, retired and superseded IDs.
9. Explicit set-valued results for split, merge and restructure; no silent redirect.
10. Namespaced uniqueness for legacy/external crosswalks and no unqualified alias resolution.
11. Separate exact-ID and policy-qualified current-resolution API operations with bounded traversal and cycle detection.
12. No cache, normalized value or current recommendation can become identity authority.

Consequences

Benefits

• Canonical imports reproduce the same IDs while production curation can add records without rebuilding or renumbering existing entities.
• Citations retain their original targets and can still discover reviewed successors.
• Compound, token, segment and future reference occurrences remain distinguishable even when they share surface text or semantic definitions.
• Split and merge corrections preserve ambiguity honestly instead of manufacturing one misleading redirect.
• Legacy traceability survives without leaking old database identity into the public contract.

Costs

• Corrected core releases may need large crosswalk and supersession artifacts even when most visible text is unchanged.
• APIs and clients must represent lifecycle state and successor sets rather than assuming every ID resolves to one current row.
• Every public entity kind needs a reviewed identity contract and deterministic path fixture before release.
• UUIDv5 payload canonicalization and UUIDv7 generation require dedicated contract tests instead of relying on database defaults.

Alternatives Considered

Database sequences as public IDs

Sequences depend on insertion order and environment and cannot survive deterministic rebuilds. They may remain internal surrogate keys but are not public identity.

Content hashes as entity IDs

Equal text can denote different occurrences, and small corrections would replace every reference. Content hashes remain integrity evidence, not identity.

Reuse IDs when text looks unchanged across releases

This makes identity depend on fuzzy equivalence and can attach one ID to different parent or boundary facts. Explicit crosswalks and supersession are safer.

Mutable rows with a current flag only

In-place mutation loses the state originally referenced by citations. Current state is a projection over immutable identity and curation history, not a replacement for that history.

One successor column

A scalar cannot represent split, merge, restructure or contested correction. A typed event with predecessor and successor sets is required.

Deferred Decisions

• ADR-003: package serialization of identity paths, crosswalks and manifests.
• ADR-004: token form and token occurrence entities.
• ADR-005: span identity-bearing coordinates and containment.
• ADR-006 and F2-019: physical provenance, curation and evidence records.
• F2-013: complete referenceable entity catalog and typed endpoint representation.
• F2-018: compatibility impact classes and approval matrix.
• Production curation ADR: event states, moderation and invalidation procedure.

Revisit Conditions

• An accepted entity kind cannot define stable identity-bearing facts without mutable normalized text.
• A supported database or runtime cannot generate standards-conforming UUIDv7.
• Reference resolution requires cross-kind replacement rather than an explicit typed relation.
• A corpus release cannot preserve historical addressability with versioned crosswalk and supersession artifacts.