[pdlug]

The ontology and semantics release: ontology change classification, typed subsumption, edge-kind integrity (target-side cardinality and acyclic relations), a real composition relation, a replayable identity history with identity-aware graph merge, and the removal of dead ontology surface. The changesets under .changeset/ are the user-facing changelog and carry every ### Breaking section; this description records what ships and why.

What changed

Ontology changes are classified by their data consequences. isStructuralSubtype(child, parent) decides, over TypeGraph's projected JSON Schema, whether every value of one node schema satisfies another, and answers incomparable rather than guessing when a construct cannot be judged. A field the projection cannot express, such as embedding() or z.date(), is left unjudged on its own while every other field is still compared (Zod 4.5 or later; older Zod skips the pair), and the schema-diff preflight (getSchemaChanges, requiresMigration) runs the same check as the commit. The ontology change classifier names each relation change safe, warning or breaking, and a warning is a tightening probed against live data inside the schema-commit transaction: adding disjointWith, subClassOf, equivalentTo or partOf/hasPart, narrowing an edge kind's endpoints, or declaring a stricter cardinality or acyclic: true refuses the commit with MigrationError (ontology-tightening-violated) when existing rows violate it. details.violations has exactly the shape store.verifyConstraintFences() returns, so the offending rows can be listed, fixed, and the migration retried. Store.evolve(), withEvolvedTransaction() and rollbackSchema() run the same preflight, in one fixed order with the structural gates. The same preflight refuses two commits that used to succeed and silently leave a unique constraint unenforced, because a schema commit validates no existing row against a unique constraint and rebuilds no claim: adding or reshaping a unique constraint on a kind that holds rows (a kind re-added over rows a discarded drop left behind included), and removing a subClassOf/equivalentTo relation or a kind so that a kindWithSubClasses constraint's subclass component loses a member sorting before a populated kind, which is where that kind's claims may sit. Both refuse with MigrationError (unique-constraint-requires-empty-kind) from an existence probe inside the schema-commit transaction, and a backend that cannot run the probe atomically refuses with ConfigurationError (UNIQUE_CONSTRAINT_CHANGE_REQUIRES_ATOMIC_BACKEND).

One same-class owner, and typed subsumption. subClassOf and equivalentTo carry a structural contract checked at compile time and again at registry build. equivalentTo between registered kinds is mutual subsumption, and assignability, subclass expansion, endpoint admission, uniqueness scope, merge reconciliation and search all read the same answer; external IRIs stay inert references. Supertype queries are polymorphic by default, and one option, expansion: "exact" | "subclasses" | "narrower", replaces includeSubClasses on from()/to()/fromDynamic()/toDynamic() and on search(). A kind list in from([...]) takes the same option and store default as a single kind. When an extension adds a subclass at runtime (through evolve() or a later createStoreWithSchema reload) under a kind the compile-time graph types exactly, an alias over that kind with no stated expansion is refused with ConfigurationError (QUERY_ALIAS_EXPANSION_UNTYPED_SUBCLASSES) instead of returning rows its type does not admit. queryDefaults.expansion: "exact" restores the previous behavior in one place. Every meta-edge factory returns a relation typed with its name and endpoint kinds, so an alias the ontology can affect widens its kind and NodeId to string while one it cannot keeps its literal type. Typed edge collections type their endpoints through the same rule, accept subclass nodes, subclass references and polymorphic query rows as endpoints (and bulkFindEdgesFrom/To type the reference each bucket echoes as the same widened input), and getNodeByRef({ kind, id }) on the store, transactions and views resolves a reference to its typed node. A search hit stated expansion: "subclasses" widens the same way, and store.search accepts an options value typed by its own exported option types.

Edge-kind integrity. targetCardinality bounds the edges pointing at one node independently of cardinality, enforced atomically through the same claim machinery as the source side on every write path. acyclic: true declares an edge kind a DAG: every write that can add an edge to the relation is refused with EdgeAcyclicityError when the new edge's to already reaches its from, a batch is probed whole before its first write, and graph merge reports a cycle a plan would close as a plan-time AcyclicityMergeConflictError. defineGraph refuses an integrity option stated outside its domain. On PostgreSQL the acyclicity and composition fences hold at every supported isolation level and between writers at different levels: a write that makes a decision only the per-graph write fence protects (a write into an acyclic or composition relation, a delete of a composition whole, a match-key convergence) advances the graph's row in typegraph_fences behind the advisory lock, so a REPEATABLE READ or SERIALIZABLE session whose snapshot predates another such writer's commit fails on that row with SQLSTATE 40001 instead of checking a relation it can no longer see. TypeGraph replays the transactions it opened (a constrained collection write, an import chunk, a merge commit) and surfaces TransactionConflictError to the owner of a caller-owned one. Every other holder of the fence takes the lock alone and issues the statements it issued before. tx.sql is the only raw SQL handle a transaction context carries, so caller SQL cannot roll a savepoint back over the fence a session keeps reusing. A schema write runs at READ COMMITTED under the advisory schema fence, so its tightening preflight reads every writer it waited on; a caller-owned REPEATABLE READ or SERIALIZABLE transaction handed to a schema write (adoptSchemaWriteTransaction, or a transaction-scoped PostgreSQL backend) is refused with SCHEMA_WRITE_REQUIRES_READ_COMMITTED before its first statement.

Composition. partOf(Part, Whole, { via }) and hasPart declare a whole-part relation realized by an existing edge kind, with orientation inferred from the edge's endpoints and partSide where both are legal. One whole per part is fenced by a reserved claim axis across every realizing edge kind and both orientations, with a pre-write probe for batches and backends without claim relations. A part states its attachment as partOf: { whole: { kind, id }, via?, props?, validFrom?, validTo? } on create, bulkCreate and both get-or-create entries, written in the same transaction as the node; on get-or-create it is a postcondition, so two racing calls naming different wholes end with one attachment and one refusal. bulkGetOrCreateByConstraint decides its composition attachments as a set before its first write: every verdict a read can reach for a matched item, counting the attachments of the rows the batch is about to create, precedes the first row, so a refused batch attaches, updates and resurrects nothing even when the refusal is caught inside an enclosing store.transaction(...). nodes.<Kind>.reparent(id, { whole, via?, props?, at? }) and bulkReparent move a part to another whole at one instant, retiring the old attachment by the incumbent's population (one deletes it, oneActive ends its window) so no coordinate shows zero wholes or two. A composition edge write refuses a validFrom or validTo later than now on every path, and reparent refuses a later at (CompositionError, one code per situation); a move with no at after the clock steps back moves at the incumbent's validFrom instead of inverting its window, and a stated at earlier than that start is refused (COMPOSITION_MOVE_BEFORE_INCUMBENT), so an open-ended composition row is a member and an ended one is history for good: one predicate decides membership for the claims, the audit, the cascade, the acyclicity relation and every row a write proposes, resurrects or reopens. A schema commit that makes ended rows count, such as redeclaring a oneActive realizing edge one, probes the whole composition relation for a cycle and audits each part for a second whole, and a commit that adds a pair over an edge kind whose stored rows start or end later than now is refused; store.verifyConstraintFences() reports such rows as compositionFutureWindow. On a graph with any oneActive cardinality, exportGraph always carries validFrom/validTo, as identity graphs already do, and refuses includeTemporal: false, because an ended row exported without its end would import as current. existence: "required" refuses a bare create and a detach of a live part. Deleting a whole cascades leaf-first through its parts in a deterministic order, with every verdict reached before the first row is deleted, and reports the parts, each with its immediate whole and realizing edge kind, as cascadedParts on the onOperationEnd context and on receipts. nodes.<Kind>.planDelete(id) returns what that delete would remove, computed by the delete's own planner, and delete(id, { expect: plan }) turns that preview into a guard: the delete compares its own plan, computed in its transaction (under the per-graph lock for a composition whole), and refuses with NodeDeletePlanMismatchError before any write if the parts or removed edges differ or the node is gone, so a "delete this and these parts" confirmation can span two requests. hardDelete and bulkDelete refuse an options argument. Restoring a whole does not restore its parts; the composition docs give a tested recipe for undoing a cascade from the delete's receipt. parts() and wholes() navigate the closure, by default exhaustively with no hop ceiling so a chain of any depth returns whole, while a stated maxHops bounds the walk exactly as given, and maxHops: 1 with no depth or path is a single step that pages and streams like any traversal; subgraph({ composition: true }) returns the complete owned unit at the read's coordinate, and provenance treats a required part as support-dependent on its whole, so a belief-status close of a fact whole closes its required parts and a reopen brings back the ones still supported. Import, the constraint-fence audit and graph merge all see composition: merge plans report and refuse composition orphans, and a branch's composition writes apply as a unit.

Identity history and identity-aware merge. An identity-enabled graph with history capture keeps an append-only transition log: store.identity.transitionsOf(ref) and replay(ref) return every change to a node's identity class with its cause, both temporal coordinates and, for a merge, the branch, plan and review that produced it. Both page through limit, cursor and nextCursor, report a completeness result naming each reason a page is not the whole answer (more pages, retention, restored transitions, members captured before history began, pending notes inside a transaction), discover lineage past the requested window, and reconstruct membership through the same historical reader as store.asOfRecorded, so a replay can never disagree with a read. A transition is reported only while the reference was a member of the class it names, so a class the reference left keeps its later merges and splits to itself. Archival interchange (format 3.0) carries transitions and the retention watermark, and pruneIdentityTransitions advances the watermark monotonically. Graph merge carries identity truth with fixed, reported rules: a three-way classification of every staged assertion and retraction, duplicate reduction to one survivor, a hard conflict when branches assert opposing relations for one pair, and a plan-time separation veto that drops a scored match between entities a different assertion holds apart, counting the same assertions the merge stages, and reports it on MergeReport.identityConflicts. A branch that only retracts a pair another branch retracts and re-asserts is refused as a race rather than silently overruled. A plan that deletes a part the target has meanwhile moved under another live whole reports it as a composition orphan with cause: "moved" and refuses at apply. When one branch attaches a part, by a move, a new edge or a reopened row, and another branch deletes that part or its whole, planning refuses with the same finding, naming the attaching branch in branchId, instead of dropping the attachment as an edge to a deleted endpoint. A merge option MergeOptions does not declare is refused with InvalidMergeOptionsError. Merge plans move to format 2 and merge reviews to formats 3 (whole target) and 4 (candidate-scoped); MERGE_REVIEW_FORMAT_VERSION_V1, MERGE_REVIEW_FORMAT_VERSION_V2 and MergePlanArtifactV1 are removed, and earlier artifacts are refused as unsupported rather than malformed. On a graph with target-side cardinality, an acyclic edge or a composition pair, the sparse base a candidate-scoped read uses never sees the rows those constraints depend on, so candidate write-set planning falls back to planning against the whole target. planCandidateWriteSet returns the scope it chose and the reason for a fallback beside the plan, planningScope: "candidate" refuses instead of falling back (CandidatePlanningScopeError), and an explicitly requested reviewScope: "candidate" is refused with MergeReviewError (candidate-scope-ineligible) carrying the same reason.

Removed surface. Custom metaEdge(), the public InferenceType union and the deprecated sameAs/differentFrom factories are gone, since none drove behavior beyond serialized metadata. Free-form vocabulary moves to defineGraph({ annotations }), with one migration guide. A stored schema that still holds a custom-meta-edge relation the code no longer declares diffs as breaking, with a migration action naming each relation, and evolve(), planEvolution() and removeKinds() refuse to drop it, so the stored copy is discarded only by an explicit migrateSchema().

Behavior fixes that ride along. paginate(), page() and stream() no longer skip or repeat rows of a traversal query, and a multi-hop traversal returns each matched path once. Cursor pagination over a recursive traversal (recursive(), and parts() / wholes() beyond a single step) is refused with ConfigurationError (RECURSIVE_PAGINATION_UNSUPPORTED) before any statement runs, because a recursive row has nothing to extend the start-node keyset with and pages could silently drop rows. store.subgraph() fires the query hooks it documented. subgraph() and the graph algorithms refuse an unregistered kind, and StoreView reads refuse a coordinate their caller states. store.clear({ preserveContributionMaterializations: true }) is refused on a backend that cannot honor it instead of deleting the markers. A stored schema no longer diffs as breaking because Zod's projection respelled a nullable union or a closed tuple. A node create, a tombstone restore (upsertById, get-or-create resurrection, their bulk forms) and a provenance revive on an identity graph decide the identity fold before writing the row, so a caught IdentityContradictionError no longer leaves the row behind. Merge apply counts the plan's own edge deletions when it judges a node delete's restrict policy, so a branch that deletes an edge and then its restrict endpoint merges. search() refuses a kind its index cannot cover, exact or expanded, exactly where $fulltext.matches() refuses the same alias, instead of returning fewer rows.

Design rationale

One owner per decision, per the contract discipline in AGENTS.md: the composition claim key, the pair a live row realizes, the edge-write fence reason, the in-frame node delete that every delete path and the cascade run, the acyclicity predicate, the opposing-relation detector, the post-retraction aftermath and the schema-commit preflight each have a single spelling that every caller reaches. Reads precede writes on every fused frame that can run inside a caller's enclosing transaction, because the operations layer has no savepoints and sequencing is its only atomicity, so a refusal caught inside store.transaction(...) leaves nothing of the refused write. Bulk writes hold to the same rule: bulkGetOrCreateByConstraint, edge bulkUpsertById and bulk getOrCreateByEndpoints decide every item, judged against the counts the earlier items leave, before the first row is written, and a convergence retry re-runs only an attempt that wrote nothing.

The composition relation is a real relation, not a new traversal flavor: it fixes the cardinality of the realizing edge, derives orientation from the declared pair, and is judged as one oriented union for acyclicity. That is what lets one claim axis hold "one whole per part" across realizing edges, lets the cascade and subgraph({ composition: true }) know exactly what an owned unit is, and keeps composition distinct from the looser broader/narrower taxonomy and from instance-level edges that merely happen to describe containment.

Identity merge carries truth rather than arbitrating it. A same assertion is ledger truth the merge carries across and never fuses the rows it names, and the separation veto only ever removes a candidate match, so the merge never invents or overrides an identity decision. Every transition a merge causes records the branch, plan and review that caused it.

The atomic edge-claim statements are driven by one VALUES relation grouped by claim shape, with composition scope riding the group key. A batch of partOf creates reads each whole once per kind, never re-reads a part row it just inserted, and probes acyclicity once over every composition edge the batch will write, which also makes a cycle running through two of the batch's own items visible. The cascade carries the rows it already read into the delete instead of reading them again. Merge's required-existence orphan candidates derive from one normalized write view, and the identity retraction aftermath has one implementation reached from every caller.

The build emits declarations once with tsc and rolls every entrypoint from that emit. The previous per-entrypoint rollup rooted at source held per-module emit state for all 449 modules and peaked at 9.9 GiB wherever it was rooted, so no public type family drove it; a whole-program emit costs 1.53 GiB and 7 seconds and the rollup from that emit 0.46 GiB and 1 second. The complete build peaks at about 1.5 GiB, the CI heap ceiling is back at 8 GiB, and 40 of 40 emitted chunks and 37 of 38 entry declarations are byte-identical to the old output apart from a cosmetic chunk-name suffix.

Measurements

Single-writer insert latency on a relation of 10^5 edges, median / p95, with fresh planner statistics, on an 8-core laptop under concurrent load, so the ratios matter more than the absolute numbers.

shape	SQLite cardinality: "one"	SQLite acyclic: true	PostgreSQL cardinality: "one"	PostgreSQL acyclic: true
forest	0.2 / 0.3 ms	0.2 / 0.2 ms	4.1 / 6.0 ms	3.8 / 8.6 ms
chain-append	0.4 / 1.0 ms	0.1 / 0.3 ms	2.6 / 2.8 ms	7.3 / 14.3 ms
chain-prepend	0.3 / 0.5 ms	220.5 / 229.1 ms	2.8 / 3.1 ms	467.9 / 475.4 ms

The forest p95 is 0.7 times the cardinality-one baseline on SQLite and 1.4 times on PostgreSQL, inside the 3 times criterion fixed before measuring. Chain-prepend is the documented worst case: the new edge points at the head of the chain, so the exhaustive walk visits every reachable edge at roughly 2 µs (SQLite) to 5 µs (PostgreSQL) per hop, linear in the reachable set rather than in the relation. The PostgreSQL chain-append p95 was measured while autovacuum processed the freshly seeded rows; its 10^4-edge counterpart is 2.2 ms against a 2.6 ms baseline.

PostgreSQL contention, W connections appending to one shared 10^5-edge relation for 30 seconds each, throughput and p99.

writers	cardinality: "one"	acyclic: true
2	390/s, 13.5 ms	529/s, 13.1 ms
4	391/s, 59.3 ms	361/s, 40.1 ms
8	412/s, 119.7 ms	487/s, 70.3 ms
16	692/s, 153.3 ms	654/s, 136.1 ms

Eight-writer acyclic throughput is 118 percent of the cardinality-one run against a 70 percent criterion fixed before measuring. Both fences serialize on the same per-graph advisory lock, so the probe adds only its own sub-millisecond index seek to the contended path; both engines seek the edge table's endpoint index per hop.

Both tables were measured before the acyclic write also advanced the graph's fence row. That cost was measured separately on PostgreSQL 18 with one client, running the fence statement alone inside BEGIN/COMMIT: 0.11 ms for the lock alone against 0.17 ms for the lock plus the row. The update is HOT while no older snapshot is open. With one REPEATABLE READ snapshot held open, the lock-plus-row statement rose to 0.24 ms after 20,000 deciding transactions and 0.63 ms after 80,000 as dead row versions accumulated, while the lock-only statement stayed at 0.11 ms.

Deployment and upgrade shape

The identity transition log adds two relations to every database, typegraph_identity_transitions and typegraph_identity_transition_retention, as base-schema release 6. The bump is one-way: a privileged open (createStoreWithSchema, createAdapterStoreWithSchema) or backend.adoptBaseSchema() catches a database up in place, DML-only runtimes refuse with BaseSchemaMigrationError until it has run, and a release that knows only version 5 refuses a database stamped 6. A custom engine profile's two DDL members for the new relations are optional, and adoption refuses with a typed error naming whichever is missing. Supertype queries, kind lists included, return subtype rows by default, deleting a composition whole deletes its parts, and stored merge plans and reviews must be planned again. A database whose stored schema holds a custom-meta-edge relation needs one explicit migrateSchema() after the relations move to annotations. A schema version an earlier release committed keeps its document and schema_hash column, and every comparison against it hashes the stored document in this release's serialization, so an unchanged graph with ontology relations reopens, registers templates, re-instantiates template targets and plans merges without a rewrite. A durable PostgreSQL working copy whose allocation was sealed at base-schema version 5 is adopted in place on reopen. On PostgreSQL, a role that writes into an acyclic or composition relation, deletes a composition whole, or converges on an edge match key needs INSERT and UPDATE on typegraph_fences, a relation the base schema already holds.

Deferred

Identity-driven pairing and conflict-arbitration policies for graph merge are not part of this PR. Pairing candidates by identity assertions, and policy options that choose how a merge resolves assertion, edge, uniqueness or provenance conflicts, were built and then removed for lack of a consumer scenario; what ships is the fixed, reported rule set above, the separation veto, the three-way ledger reconciliation and decision provenance on every transition. The request for the removed policies is tracked in #657, which is rescoped to wait for a concrete scenario and acceptance criteria and is not closed by this PR.

Closes #610
Closes #653
Closes #673
Closes #674
Closes #675