Ontology and semantics program (integration)

.changeset/bulk-write-verdicts.md

@@ -0,0 +1,9 @@
+---
+"@nicia-ai/typegraph": patch
+---
+
+`bulkUpsertById` and `bulkReplaceById` on nodes, and `bulkUpsertById` and `bulkGetOrCreateByEndpoints` on edges, now reach every verdict their items can raise by reading before their first write, so a refusal caught inside `store.transaction(...)` leaves none of the batch written. They wrote their creates first and then each update in turn, so a later item refused for a unique key it loses, a validity window that ends before it starts, a cardinality or target-cardinality allowance a resurrection or reopened window would exceed, a restore whose id a disjoint kind holds, an identity fold or window end the identity rules refuse, or a required composition part an edge write would detach left the earlier creates and updates committed when the caller caught it. The update half is now prepared in full before the creates are written and judged as the state the batch produces in write order, so a later item may still take a key or an allowance an earlier one gives up, and is refused one an earlier one takes or a new row of the same batch claims. When a row's stored window moves between the batch's read and its write, the batch converges as a single update does and prepares every remaining item again before writing the next; a refusal that preparation reaches follows the items already written. A concurrent writer the per-graph write fence does not exclude can still claim a key or remove a row between the reads and the writes, and that refusal comes from the write.
+
+`bulkGetOrCreateByEndpoints` re-ran the whole batch once on a `CardinalityError`, also inside a caller's transaction after a create or update of the batch had been written there; it now re-runs only when the refusal left nothing of the batch written (the call opened its own transaction, or no write had run), so a raced batch inside `store.transaction(...)` reports the refusal instead of applying its writes a second time.
+
+A node `create`, `bulkCreate` or `bulkInsert` on an identity graph (`sameIdAcrossKinds: "fold"`) whose caller-chosen id the identity fold refuses now writes nothing: the fold's `IdentityContradictionError` verdict is read before the insert or tombstone resurrection, where it used to follow it, so a refusal caught inside `store.transaction(...)` left the created rows committed. The create half of `bulkUpsertById` and `bulkReplaceById` takes the same path, and so do the single writes that bring a tombstone back, `upsertById` and `getOrCreateByConstraint` on a tombstone and a fact `unRetract` reopens, each of which left the row live when its fold was refused. `importGraph` still folds its nodes after writing them, since a fold can join two rows of the same document, and a refused fold rolls back the import's own transaction.

.changeset/candidate-planning-scope.md

@@ -0,0 +1,11 @@
+---
+"@nicia-ai/typegraph": minor
+---
+
+**Candidate planning reports the scope it planned in.** `planCandidateWriteSet()` stages a candidate from its own rows when the target allows it and from a clone of the whole target otherwise. That choice was a silent boolean; it is now a decision with a reason, returned beside the plan as `planningScope`: `{ scope: "candidate" }`, or `{ scope: "whole-target", reason }` where `reason` is one of `composition`, `acyclic-relation`, `target-side-cardinality`, `missing-active-source-read`, `missing-match-identity-read`, `missing-scoped-identity-reads`, `match-identity-owner-not-clone-visible` or `planned-evolution`. Both scopes produce the same plan, so the scope is not part of the merge plan artifact or its digest and `MERGE_PLAN_FORMAT_VERSION` is unchanged. The new `CandidatePlanningScope`, `CandidatePlanningScopeReason`, `WholeTargetPlanningScope` and `CandidateWriteSetPlan` types are exported from `@nicia-ai/typegraph/graph-merge`.
+
+**`planningScope: "candidate"` makes the candidate scope a requirement.** Passed to `planCandidateWriteSet()`, it refuses with the new `CandidatePlanningScopeError` (`GRAPH_MERGE_CANDIDATE_PLANNING_SCOPE`, `details.planningScope.reason`) instead of planning against the whole target, before any staging backend is created. A candidate the target's schema refuses still reports its own validation error (`CandidateWriteSetError`) under the option, as it does without it; and a target that cannot carry a public merge plan at all (no revision tracking, or no interactive transactions) is refused with `MergePlanCapabilityError` before any staging backend is created, with or without the option. `planCandidateWriteSetForEvolution()` always stages the whole resulting graph, so it reports `planned-evolution` and takes no `planningScope` option. The review entry points forward it to planning. A refused candidate-scoped review (`details.reason: "candidate-scope-ineligible"`) now also carries `details.planningScope` naming the cause.
+
+### Breaking
+
+- `planCandidateWriteSet()` and `planCandidateWriteSetForEvolution()` now resolve to `Result<CandidateWriteSetPlan, MergeError>`, `{ plan, planningScope }`, instead of the bare `MergePlanArtifact`. Read the artifact from `result.data.plan`, for example `const { plan } = unwrap(await planCandidateWriteSet(args))`.

.changeset/clear-preserve-refusal.md

@@ -0,0 +1,9 @@
+---
+"@nicia-ai/typegraph": patch
+---
+
+`store.clear({ preserveContributionMaterializations: true })` is now refused with `UnsupportedBackendCapabilityError` on a custom backend that does not implement `clearGraphPreservingContributionMaterializations`, before anything is deleted. It previously fell back to `clearGraph` and could delete the markers it was asked to keep. `store.clear()` with the option omitted is unchanged: it prefers the preserving member and otherwise clears through the backend's own `clearGraph`. Bundled backends implement the member and are unaffected.
+
+### Breaking
+
+- A custom backend that does not implement `clearGraphPreservingContributionMaterializations` now refuses `store.clear({ preserveContributionMaterializations: true })` with `UnsupportedBackendCapabilityError`. Implement the member, or drop the option.

.changeset/clone-working-copy-query-defaults.md

@@ -0,0 +1,5 @@
+---
+"@nicia-ai/typegraph": patch
+---
+
+`cloneWorkingCopyStrategy` (the default `branch()` strategy) and the ingestion-branch clone now open the working copy with the base store's `queryDefaults`, as the fork, namespace-fork and PostgreSQL table strategies already did. A base opened with `queryDefaults: { expansion: "exact" }` or a non-default `traversalExpansion` previously got a working copy on the library defaults, so the same query returned different rows on the branch than on the store it was branched from. Hooks, `coalesceUnchangedUpserts` and `autoRefreshStatistics` are still not carried to a clone.