fix: sub-graph polish (issue #81 findings 1, 3, 4, 5, 7)

[Jurij89]

Summary

Five targeted fixes from the post-PR-#101 sub-graph review (dkgv10-spec#81). All P1/P2 polish on working code — no P0 changes, no behavior breaks for callers that already follow the documented registration flow.

What's included

1. Stale JSDoc fixed on DKGAgent.createSubGraph. The previous doc claimed "GossipSub broadcasts raw triples without sub-graph context; receivers store replicated data in the root data graph" — this has been false since gossip auto-registration landed in gossip-publish-handler, workspace-handler, and finalization-handler. New doc describes the actual V10.0 replication behavior: subGraphName is carried on the wire, receiving nodes auto-register via ensureSubGraph() + generateSubGraphRegistration(), and replicated data routes to the correct sub-graph named graph.

2. Removed unused ContextGraphManager.listSubGraphs from packages/storage/src/graph-manager.ts. This was a graph-URI walk with divergent semantics from the spec-compliant DKGAgent.listSubGraphs (which queries _meta via SPARQL). Zero callers in the codebase; its reserved-prefix list still contained stale entries post the PR feat: add SKILL.MD agent onboarding and MarkItDown document processor #104 rename. Deletion removes a footgun for future code.

3. Assertion operations now validate sub-graph registration. assertionCreate, assertionWrite, assertionQuery, assertionPromote, and assertionDiscard all call a new private helper ensureSubGraphRegistered that performs the same `ASK` over `_meta` that `publish()` already does at `:710-729`. Previously these operations silently created graphs under unregistered sub-graph URIs, orphaning the triples in graph URIs no `_meta` discovery query would ever return. The guard is opt-in — calls without a `subGraphName` are unchanged. Error: `Sub-graph "{name}" has not been registered in context graph "{contextGraphId}". Call createSubGraph() first.`

   Behavior clarification, not a breaking change: any caller that was relying on the previous silent-orphaning behavior was already broken (the orphaned triples were unreachable via spec-compliant discovery). The new error is actionable and the fix path is one call to `createSubGraph()`. Peer-side replication is unaffected — gossip-received data goes through `store.insert` directly (`gossip-publish-handler.ts:214`), not through the assertion API, so the new guard does not block replication.

   Finding 4 (assertion registration check) does not require a companion spec change: §16.2.2 already implies registration-before-write semantics. The companion spec PR covers only findings 1, 2, 6, 7 (prose), and 8 — the items the current spec omits.

4. Literal stripping bug fixed in `DKGAgent.listSubGraphs`. Replaced three per-field regex strips with calls to the existing in-file `stripLiteral()` helper. The previous `/^"|".*$/g` pattern on `createdAt` was greedy and ate any inner quote; the new version correctly handles `"foo"`, `"foo"^^xsd:dateTime`, and `"foo"@en`.

5. JSDoc `@throws` note added to `DKGPublisher.publishFromSharedMemory` documenting the existing (undocumented) constraint that `subGraphName` cannot be combined with `publishContextGraphId` — the remap flow targets `/context/{id}` URIs which are incompatible with sub-graph URIs.

Spec PR companion

Companion spec updates for the same issue (findings 2, 6, 7 prose, 8 — all spec-catchup items, plus the gossip auto-registration §16.2.6 rewrite) are in a separate dkgv10-spec PR. No spec change is required for finding 4 — §16.2.2 already implies that operations must target a registered sub-graph; this PR brings the assertion ops in line with that implicit contract.

Test plan

• 8 new unit tests in `packages/publisher/test/draft-lifecycle.test.ts` covering the registration check for all 5 assertion ops plus the opt-in and name-validation behaviors
• Publisher test suite: 616 / 616 pass (was 608; +8 new)
• Storage test suite: 70 / 70 pass
• Agent sub-graph e2e (`test/e2e-sub-graphs.test.ts`): 15 / 15 pass
• Full `pnpm run build:runtime` across all 12 runtime packages: clean (TypeScript compiles)
• Linux CI must go green before merge — see caveat below

Reviewer guidance — Linux CI is the gating signal

Please do not be spooked by Windows-env failures. When running the full `@origintrail-official/dkg-agent` suite locally on Windows, 9 tests fail in 8 files. None of these failures are caused by this PR's changes — they are all pre-existing environmental issues that affect the agent suite generally:

• 3 uncaught `spawn npx ENOENT` exceptions: `e2e-finalization.test.ts`, `e2e-chain.test.ts`, `e2e-agents.test.ts` — the hardhat subprocess bootstrap can't find `npx` in the subprocess PATH on Windows.
• 4 timeouts waiting on the hardhat/libp2p bootstrap: `e2e-publish-protocol.test.ts`, `gossip-validation.test.ts`, `publish-jsonld.test.ts`, `e2e-finalization.test.ts`.
• 2 libp2p timing failures: `workspace-ttl.test.ts`, `e2e-security.test.ts`.

None of these tests touch `packages/publisher/src/dkg-publisher.ts`, `packages/agent/src/dkg-agent.ts`, or `packages/storage/src/graph-manager.ts` (the three source files this PR modifies). The 15 sub-graph e2e tests that DO exercise the modified code all pass locally. Please rely on the GitHub Actions Linux runner for the definitive green signal — that is the merge gate, not local Windows runs.

Closes selected findings of OriginTrail/dkgv10-spec#81.

🤖 Generated with Claude Code

[github-actions]

Codex review produced 1 comment(s) but all targeted lines outside the diff and were dropped. Check the workflow logs for details.