refactor(storage): add bounded managed mutation capabilities

[Jurij89]

Summary

• Add one closed, discriminated TripleStore.structuredMutation() capability whose six bounded variants cover subject-set deletion, ranked-subject retention, linked-record closure retention, predicate replacement, staged projection replacement, and byte-stable subject projection copy.
• Keep domain policy at callers: storage receives graph-explicit generic descriptors, validates dense unique operands, absolute IRIs, closed RDF payload scopes, bounded counts, a 4 MiB operand cap, and an exact 4 MiB serialized-update cap before dispatch.
• Forward the single capability across embedded Oxigraph, the worker adapter, SPARQL HTTP, Blazegraph, graph-set indexing, changelog accounting, large-literal storage, and the Agent cache wrapper without multiplying adapter/decorator APIs.
• Migrate catalog persistence, join moderation/retention, agents metadata retention, curator refresh, RS repair, and KA Merkle-root metadata away from caller-authored mutating SPARQL. This is the expand/migrate phase; a follow-up PR will contract raw update() and mutating query() on ownership-leased stores.

Related

• Related to security(storage): close the raw update() route to reserved system-record state before activation #2162
• Stacked on refactor(storage): migrate exact managed mutations #2185
• Does not close security(storage): close the raw update() route to reserved system-record state before activation #2162: the final leased raw-channel contraction remains a separate follow-up so its security boundary can be reviewed independently.

Diagrams

Managed structured mutation

Before:

sequenceDiagram
    participant Caller
    participant Decorators
    participant Store as TripleStore adapter
    participant Backend
    Caller->>Caller: Build raw SPARQL program
    Caller->>Decorators: update(program, touchedGraphs hint)
    Decorators->>Store: Forward opaque program
    Store->>Backend: Dispatch caller-authored mutation
    Backend-->>Caller: Result

Loading

After:

sequenceDiagram
    participant Caller
    participant Capability as structuredMutation union
    participant Decorators
    participant Store as TripleStore adapter
    participant Backend
    Caller->>Capability: Typed variant plus graph-explicit descriptor
    Capability->>Capability: Validate RDF scope, counts, and byte limits
    Capability->>Decorators: One normalized capability call
    Decorators->>Store: Account guarded and touched graphs
    Store->>Store: Build one bounded SPARQL update
    Store->>Backend: Dispatch adapter-authored mutation
    Backend-->>Caller: Result

Loading

RS repair projection copy

Before:

sequenceDiagram
    participant Heal as RS repair
    participant Store
    participant Backend
    loop Every root
        Heal->>Store: Raw INSERT WHERE
        Store->>Backend: One update per root
    end
    Heal->>Store: Raw marker/meta updates

Loading

After:

sequenceDiagram
    participant Heal as RS repair
    participant Store
    participant Backend
    Heal->>Heal: Preflight ordered root chunks under both 4 MiB limits
    Heal->>Store: Clear materialized-version marker
    Store->>Backend: Atomic predicate transition
    loop Every ordered root chunk
        Heal->>Store: structuredMutation(copy-subject-projection)
        Store->>Backend: One bounded server-side copy
    end
    Heal->>Store: Copy metadata
    Store->>Backend: Bounded server-side copy
    Heal->>Store: Stamp materialized version
    Store->>Backend: Atomic predicate transition

Loading

Files changed

File	What
packages/storage/src/triple-store.ts	Defines the single optional structured capability, its closed mutation union, and typed caller helpers.
packages/storage/src/bounded-structured-mutation.ts	Centralizes generic descriptor validation, graph accounting, count/byte limits, ordered projection chunk planning, and adapter-generated updates.
packages/storage/src/atomic-graph-replace.ts	Reuses the bounded predicate-replacement builder for the existing atomic helper.
packages/storage/src/adapters/{oxigraph,oxigraph-worker,sparql-http,blazegraph}.ts	Implements one capability across all first-party backends.
packages/storage/src/{graph-set-index-store,changelog-store,shared-memory-literal-blob-store}.ts	Preserves cache, write-generation, changelog, reserved-graph, and literal-blob behavior through one forwarding hook.
packages/agent/src/{dkg-agent-base,dkg-agent-join,join-request-retention,curator-meta-refresh,dkg-agent-swm-host}.ts	Migrates join, retention, curator refresh, and RS repair callers; removes guessed prune counts.
packages/publisher/src/{catalog-persistence,agent-registry-meta-retention,metadata}.ts	Migrates catalog cleanup, agents retention, and Merkle-root updates.
packages/{storage,agent,publisher}/test/**	Covers bounds, atomicity, reserved source/target refusal, decorator accounting, worker RPC parity, byte-stable copy, retention safety, and migrated callers.

Test plan

• pnpm --filter @origintrail-official/dkg-storage build
• pnpm --filter @origintrail-official/dkg-storage exec vitest run --maxWorkers=1 --no-file-parallelism — 948 passed, 26 skipped integration tests.
• Real OxigraphWorkerStore RPC coverage executes all six mutation variants through the worker boundary.
• pnpm --filter @origintrail-official/dkg-publisher build
• Publisher focused lifecycle/metadata/catalog suite — 65 passed in the current review round, including update-only agents-registry pruning.
• pnpm --filter @origintrail-official/dkg-agent build — includes type and package-root checks.
• Agent changed-file suite (join, retention, curator refresh, and RS repair) — 76 passed in the current review round.
• Multi-root RS repair parity: both root closures relocate and the healed KC reproduces the control Merkle root.
• Over-budget RS repair: ten approximately 500 KB root IRIs split into multiple ordered mutations below the 4 MiB serialized-update cap; the completion marker is cleared before the first chunk and stamped only after the last chunk.
• Canonical chunk sizing and capability compatibility: every non-final projection chunk is maximal under the canonical serializer, and decorated update-only stores report atomic predicate-replacement support through the operation-level probe.
• Rolling-upgrade compatibility: update-only stores complete curator projection replacement and retain bounded RS-heal copy support; an individually unrepresentable RS root fails before any completion-marker reset.
• Blob-backed structured replacement: an over-4 MiB SWM literal is scope-validated, externalized before byte-budget enforcement, forwarded as a content-addressed ref, and hydrated byte-for-byte on read.
• Update-only decorated RS repair: a real stranded KC materializes scoped data, metadata, and its completion marker without structuredMutation support.
• Over-cap retention integration: 10,005 terminal records drain through two bounded Oxigraph mutations and retain the configured tail.
• node scripts/sparql-scale-lint.mjs --diff c28d9a25177b941f09c7122c1825efc44f2d9504 HEAD — 0 new blocking findings; two intentionally bounded shapes acknowledged in source.
• Raw mutation inventory: no Agent/Publisher store.update() caller and no mutating store.query() caller remains.
• git diff --check; no generated deployment output, ignored plan, .gitignore, or local-only files are included.