@origintrail-official/dkg-agent 10.0.19 → 10.0.21

package/dist/dkg-agent-publish.js

@@ -7,111 +7,34 @@
  * register/batch/identity entrypoints. Bodies are a 1:1 move; methods take
  * `this: DKGAgent` so cross-calls resolve against the composed class.
  */
-import { createHash, randomUUID } from 'node:crypto';
-import { PROTOCOL_SWM_UPDATE, contextGraphPublishTopic, contextGraphWorkspaceTopic, contextGraphUpdateTopic, contextGraphFinalizationTopic, contextGraphDataGraphUri, contextGraphMetaGraphUri, contextGraphWorkspaceMetaGraphUri, contextGraphSharedMemoryUri, contextGraphDataUri, contextGraphMetaUri, assertionLifecycleUri, contextGraphAssertionUri, contextGraphCatalogUri, contextGraphLayerUri, MemoryLayer, encodeKAUpdateRequest, encodeGossipEnvelope, GOSSIP_ENVELOPE_VERSION, encodeFinalizationMessage, SYSTEM_CONTEXT_GRAPHS, DKG_ONTOLOGY, createOperationContext, escapeSparqlLiteral, isSafeIri, assertSafeIri, isTrustLevelQuad, buildAuthorAttestationTypedData, buildUpdateAuthorAttestationTypedData, AUTHOR_SCHEME_VERSION_V1, buildAssertionSealQuads, buildAssertionPublishReceiptQuads, parseAssertionSealQuads, ASSERTION_SEAL_PREDICATES, GRAPH_KA_CONTENT_SCOPE_VERSION, LegacyKnowledgeAssetReadOnlyError, createGraphKnowledgeAssetScope, knowledgeAssetLayerGraphUri, computeSwmSenderKeyMembershipHash, encryptV10PublishPayload, encryptChunked, buildCiphertextChunksRoot, computeGossipSigningPayloadV2, GOSSIP_TYPE_WORKSPACE_PUBLISH_CHUNKED, ciphertextChunkStoreGraph, ciphertextChunkStoreSubject, CIPHERTEXT_CHUNK_PREDICATE, withSpan, getMetrics, assertQuadLiteralsMutf8Safe, PUBLISH_AUTHOR_NOT_CUSTODIAL_CODE, PUBLISH_AUTHOR_SELECTION_CONFLICT_CODE, formatPublishAuthorNotCustodialMessage, } from '@origintrail-official/dkg-core';
+import { planKnowledgeAssetVmPublication, isGraphScopedKnowledgeAssetVmPublishRequest, assertionSealFromQueuedKnowledgeAssetVmPublishRequest, createKnowledgeAssetVmPublishIntentKey } from './internal/knowledge-asset-vm-publish-request.js';
+export { createKnowledgeAssetVmPublishIntentKey } from './internal/knowledge-asset-vm-publish-request.js';
+import { randomUUID } from 'node:crypto';
+import { preflightKnowledgeAssetVmPublishSnapshot } from './vm-publish-snapshot-preflight.js';
+import { PROTOCOL_SWM_UPDATE, contextGraphPublishTopic, contextGraphWorkspaceTopic, contextGraphUpdateTopic, contextGraphFinalizationTopic, contextGraphDataGraphUri, contextGraphMetaGraphUri, contextGraphSharedMemoryUri, contextGraphDataUri, contextGraphMetaUri, assertionLifecycleUri, contextGraphAssertionUri, contextGraphCatalogUri, contextGraphLayerUri, MemoryLayer, encodeKAUpdateRequest, encodeGossipEnvelope, GOSSIP_ENVELOPE_VERSION, encodeFinalizationMessage, SYSTEM_CONTEXT_GRAPHS, DKG_ONTOLOGY, createOperationContext, escapeSparqlLiteral, assertSafeIri, isTrustLevelQuad, buildAuthorAttestationTypedData, buildUpdateAuthorAttestationTypedData, AUTHOR_SCHEME_VERSION_V1, buildAssertionSealQuads, buildAssertionPublishReceiptQuads, parseAssertionSealQuads, ASSERTION_SEAL_PREDICATES, GRAPH_KA_CONTENT_SCOPE_VERSION, LegacyKnowledgeAssetReadOnlyError, createGraphKnowledgeAssetScope, knowledgeAssetLayerGraphUri, computeSwmSenderKeyMembershipHash, encryptV10PublishPayload, encryptChunked, buildCiphertextChunksRoot, computeGossipSigningPayloadV2, GOSSIP_TYPE_WORKSPACE_PUBLISH_CHUNKED, ciphertextChunkStoreGraph, ciphertextChunkStoreSubject, CIPHERTEXT_CHUNK_PREDICATE, withSpan, getMetrics, assertQuadLiteralsMutf8Safe, PUBLISH_AUTHOR_NOT_CUSTODIAL_CODE, PUBLISH_AUTHOR_SELECTION_CONFLICT_CODE, formatPublishAuthorNotCustodialMessage, } from '@origintrail-official/dkg-core';
 import { SpanStatusCode } from '@opentelemetry/api';
-import { deleteByPatternWithoutCount, GraphManager, PrivateContentStore, loadSharedMemoryQuadsForScope, canonicalSharedMemoryScopeWriteGraph, } from '@origintrail-official/dkg-storage';
-import { computeFlatKCRootV10 as computeFlatKCRoot, computePrivateRootV10 as computePrivateRoot, skolemizeKnowledgeAssetParts, assertNoKnowledgeAssetPayloadNamedGraphs, assertValidPrecomputedUpdateAttestation, isReservedSubject, canonicalPublishPayload, generatedPrivateCatalogTripleKeys, appendMissingGeneratedPrivateCatalogFloor, createKnowledgeAssetVmPublishSnapshotMetadata, createKnowledgeAssetVmPublishSnapshotRequest, resolveLiftWorkspaceSlice, resolveKnowledgeAssetOperationPublicQuads, resolveKnowledgeAssetWorkspaceHead, workspaceHeadIncludesShareOperationId, KnowledgeAssetOperationPublicSnapshotNotFoundError, workspacePublicQuadsDigest, validateLiftPublishPayload, TripleStoreAsyncLiftPublisher, 
-// OT-RFC-43 A2 — per-layer pointer + KA-id predicates and stamp helpers.
-KA_ID_PRED, RESERVED_UAL_PRED, WM_CURRENT_ASSERTION_PRED, SWM_CURRENT_ASSERTION_PRED, VM_CURRENT_ASSERTION_PRED, createResolveCurrentWorkspaceGossipPayload, parseEncodedWorkspaceGossipPayload, assertPublicationPricingPolicyApplicable, } from '@origintrail-official/dkg-publisher';
+import { deleteByPatternWithoutCount, GraphManager, PrivateContentStore, loadSharedMemoryQuadsForScope, } from '@origintrail-official/dkg-storage';
+import { computeFlatKCRootV10 as computeFlatKCRoot, computePrivateRootV10 as computePrivateRoot, skolemizeKnowledgeAssetParts, assertNoKnowledgeAssetPayloadNamedGraphs, assertValidPrecomputedUpdateAttestation, isReservedSubject, canonicalPublishPayload, generatedPrivateCatalogTripleKeys, resolveKnowledgeAssetOperationPublicQuads, resolveKnowledgeAssetWorkspaceHead, workspaceHeadIncludesShareOperationId, KnowledgeAssetOperationPublicSnapshotNotFoundError, workspacePublicQuadsDigest, TripleStoreAsyncLiftPublisher, KA_ID_PRED, RESERVED_UAL_PRED, WM_CURRENT_ASSERTION_PRED, SWM_CURRENT_ASSERTION_PRED, VM_CURRENT_ASSERTION_PRED, createResolveCurrentWorkspaceGossipPayload, parseEncodedWorkspaceGossipPayload, } from '@origintrail-official/dkg-publisher';
 import { pickPublishLifecycleHooks } from '@origintrail-official/dkg-publisher';
 import { ethers } from 'ethers';
 import { buildAuthoritativePublicMetaQuads } from './context-graph-public-meta-proof.js';
 import { resolveFinalizedAssertionAuthor } from './finalized-assertion-author.js';
-import { RootlessUpdateError } from './rootless-update-error.js';
+import { RootlessUpdateError, isRootlessUpdateError } from './rootless-update-error.js';
 import { emitPublicProjection, buildPublicProjection } from './context-graph-public-projection.js';
 import { chooseFanOutTier, executeSubstrateFanOut, classifySendResult, } from './swm/substrate-fanout.js';
 import { classifySwmFanoutPeerOutcome, } from './swm/swm-fanout-peer-selection.js';
-import { KEEP_ROOT_COPY_PREDICATE } from './finalization-handler.js';
 import { applyPublishedNamedKaVmLifecycle } from './named-ka-vm-lifecycle.js';
+import { packKnowledgeAssetIdFromIdentity } from './ka-identity.js';
 import { normalizeRecoveredNamedKaPublish, throwIfRecoveryDeadlineReached, } from './named-ka-publish-recovery.js';
 import { stripLiteral, jsonLdToQuads, } from './dkg-agent-utils.js';
 import { PRIVATE_DATA_ANCHOR, } from './dkg-agent-constants.js';
 import { ContextGraphNotFoundError, InvalidContentError, } from './dkg-agent-types.js';
 import { normalizePublishContextGraphId, isPublishAsyncQuadEnvelope, assertQuadArray, sliceIntoCiphertextChunks, } from './dkg-agent-helpers.js';
 import { readMaxKaNumberWithRetry, isTransientChainError } from './allocator.js';
-import { swmSenderStateKey, } from './dkg-agent-swm-state.js';
+import { computeSwmSenderKeyRecipientRouteHash, swmSenderStateKey, } from './dkg-agent-swm-state.js';
 import { DKGAgentBase } from './dkg-agent-base.js';
 import { CONTEXT_GRAPH_AUTHORITY_RPC_SITES as CG_AUTH_RPC_SITES, withRpcUsageSite, } from '@origintrail-official/dkg-chain';
 import { createLocalContextGraphOriginMembershipRecord } from './local-context-graph-provenance.js';
-/** One operation discriminator shared by admission, sync, and queued execution. */
-function planKnowledgeAssetVmPublication(input) {
-    if (input.vmCurrentAssertion) {
-        assertPublicationPricingPolicyApplicable(input.pricingPolicy, { kind: 'update' });
-        return { kind: 'update', vmCurrentAssertion: input.vmCurrentAssertion };
-    }
-    assertPublicationPricingPolicyApplicable(input.pricingPolicy, {
-        kind: 'initial',
-        graphScoped: true,
-    });
-    return { kind: 'initial', pricingPolicy: input.pricingPolicy };
-}
-/** Rebuild the immutable graph-scoped seal carried by one queued VM request. */
-function assertionSealFromQueuedKnowledgeAssetVmPublishRequest(request) {
-    // Both execution boundaries validate the immutable graph-scoped envelope
-    // before calling this shared reconstruction helper.
-    const graphScope = createGraphKnowledgeAssetScope(request.kaUal, request.assertionVersion);
-    return {
-        merkleRoot: ethers.getBytes(request.seal.merkleRoot),
-        authorAddress: ethers.getAddress(request.seal.authorAddress),
-        authorAttestationR: ethers.getBytes(request.seal.signature.r),
-        authorAttestationVS: ethers.getBytes(request.seal.signature.vs),
-        authorSchemeVersion: request.seal.schemeVersion,
-        chainId: BigInt(request.sealChainId),
-        kav10Address: ethers.getAddress(request.sealKav10Address),
-        finalizedAtIso: request.sealFinalizedAtIso,
-        contentScopeVersion: GRAPH_KA_CONTENT_SCOPE_VERSION,
-        kaUal: graphScope.ual,
-        assertionVersion: graphScope.assertionVersion,
-        publicTripleCount: request.publicTripleCount,
-        ...(request.privateMerkleRoot
-            ? { privateMerkleRoot: ethers.getBytes(request.privateMerkleRoot) }
-            : {}),
-        privateTripleCount: request.privateTripleCount,
-        rootEntities: [],
-        ...(request.seal.reservedKaId !== undefined
-            ? { reservedKaId: BigInt(request.seal.reservedKaId) }
-            : {}),
-    };
-}
-/** Canonical immutable projection of the persisted queued-publish request. */
-export function createKnowledgeAssetVmPublishIntentKey(request) {
-    const canonicalIntent = {
-        contextGraphId: request.contextGraphId,
-        name: request.name,
-        agentAddress: request.agentAddress ?? null,
-        subGraphName: request.subGraphName ?? null,
-        shareOperationId: request.shareOperationId,
-        roots: request.roots,
-        contentScopeVersion: request.contentScopeVersion ?? null,
-        kaUal: request.kaUal ?? null,
-        assertionVersion: request.assertionVersion ?? null,
-        publicTripleCount: request.publicTripleCount ?? null,
-        privateMerkleRoot: request.privateMerkleRoot?.toLowerCase() ?? null,
-        privateTripleCount: request.privateTripleCount ?? null,
-        accessPolicy: request.accessPolicy ?? null,
-        allowedPeers: request.allowedPeers ?? [],
-        entityProofs: request.entityProofs ?? null,
-        sealMerkleRoot: request.sealMerkleRoot.toLowerCase(),
-        seal: request.seal,
-        sealChainId: request.sealChainId,
-        sealKav10Address: request.sealKav10Address,
-        sealFinalizedAtIso: request.sealFinalizedAtIso,
-        wmCurrentAssertion: request.wmCurrentAssertion ?? null,
-        swmCurrentAssertion: request.swmCurrentAssertion ?? null,
-        vmCurrentAssertion: request.vmCurrentAssertion ?? null,
-        kaNumber: request.kaNumber ?? null,
-        reservedUal: request.reservedUal ?? null,
-        publishEpochs: request.publishEpochs ?? null,
-        // Keep the pre-feature canonical JSON unchanged when the policy is omitted.
-        ...(request.pricingPolicy !== undefined
-            ? { pricingPolicy: request.pricingPolicy }
-            : {}),
-        clearSharedMemoryAfter: request.clearSharedMemoryAfter ?? null,
-        publisherNodeIdentityIdOverride: request.publisherNodeIdentityIdOverride ?? null,
-    };
-    return `sha256:${createHash('sha256').update(JSON.stringify(canonicalIntent)).digest('hex')}`;
-}
 /**
  * #1116 (round 11) — stable code tagged on the `assertionFinalize` throws that are
  * recoverable SIGNING/CHAIN CAPABILITY GAPS (no local signing key, non-V10 chain
@@ -155,6 +78,24 @@ function updateAttestationNotCustodialError(authorAddress) {
 function rootlessUpdateError(code, message) {
     return new RootlessUpdateError(code, message);
 }
+/**
+ * GH#2958 — a finalized update numbered anything but `confirmed + 1` can never be published: the
+ * publisher, the StorageACK handler, peers and the chain all require exactly that number. Coded
+ * `PUBLISH_INTENT_STALE` (the draft no longer matches what can be published) so the async lane
+ * records a terminal pre-send failure instead of the retryable `rpc_unavailable` an untyped
+ * error falls into, and both publish routes answer 409. The recovery depends on which way the
+ * number is off: a draft numbered too high keeps its shared content, a draft numbered too low
+ * means the published version moved on, so it is re-based on that.
+ */
+function versionGapError(kaUal, sealVersion, requiredVersion) {
+    const sealed = BigInt(sealVersion);
+    const recovery = sealed > requiredVersion
+        ? 'Re-open the draft with wm/pull-from (layer "swm" keeps the shared content), then finalize and share it again.'
+        : 'The published version has moved on since this draft was finalized: re-base it with wm/pull-from '
+            + '(layer "vm"), re-apply your edits, then finalize and share it again.';
+    return Object.assign(new Error(`Cannot publish the update of ${kaUal}: this finalized version is numbered ${sealed}, but the next `
+        + `publishable version is ${requiredVersion} (the confirmed version is ${requiredVersion - 1n}). ${recovery}`), { code: 'PUBLISH_INTENT_STALE' });
+}
 function latestShareOperationId(history) {
     const promoted = [...history.events]
         .reverse()
@@ -986,14 +927,25 @@ export class PublishMethods extends DKGAgentBase {
         if (!opts?.localOnly && promoted.gossipPayload) {
             await this.publishWorkspaceGossip(contextGraphId, promoted.gossipPayload, ctx, gossipSigner, promoted.shareOperationId);
         }
-        await this.afterDurableSwmPromotionV1({
-            contextGraphId,
-            subGraphName: opts?.subGraphName,
-            assertionCoordinate: assertionName,
-            lifecycleAgentAddress,
-            shareOperationId: promoted.shareOperationId,
-            ctx,
-        });
+        try {
+            await this.afterDurableSwmPromotionV1({
+                contextGraphId,
+                subGraphName: opts?.subGraphName,
+                assertionCoordinate: assertionName,
+                lifecycleAgentAddress,
+                shareOperationId: promoted.shareOperationId,
+                ctx,
+            });
+        }
+        catch {
+            // Deliberately best-effort here (the stamp already logged its cause).
+            // This entry point mints a fresh `async-<uuid>` assertion per call, so
+            // surfacing the error would hand the caller a failure for a name it
+            // cannot replay, inviting a re-publish under a NEW identity. The VM
+            // publish queued below stamps `vmCurrentAssertion`, and an absent swm
+            // pointer is then the valid divergence-only shape (swm == vm).
+            // Named-KA shares (`assertion.promote`) do surface and replay the failure.
+        }
         const intent = await this.resolveFinalizedAssertionVmPublishIntent(contextGraphId, assertionName, {
             agentAddress: lifecycleAgentAddress,
             subGraphName: opts?.subGraphName,
@@ -1350,8 +1302,7 @@ export class PublishMethods extends DKGAgentBase {
             }
             if (opts.assertionVersion !== undefined
                 && BigInt(opts.assertionVersion) !== BigInt(nextAssertionVersion)) {
-                throw new Error(`Graph-scoped update assertionVersion ${String(opts.assertionVersion)} must advance ` +
-                    `the durable current version to ${nextAssertionVersion}`);
+                throw versionGapError(updateScope.ual, opts.assertionVersion, BigInt(nextAssertionVersion));
             }
             if (opts.publicTripleCount !== undefined
                 && opts.publicTripleCount !== canonicalParts.publicQuads.length) {
@@ -1505,7 +1456,10 @@ export class PublishMethods extends DKGAgentBase {
             const result = await publisher.updateKnowledgeAssetFromStagedSharedWorkingMemoryV1(kaId, publisherUpdateOptions);
             this.log.info(ctx, `Update complete — status=${result.status}`);
             onPhase?.('broadcast', 'start');
-            if (result.onChainResult && result.publicQuads) {
+            // Members of a curated graph pick up an update from the chain update
+            // event, which refreshes their Verifiable Memory from the curator. The
+            // graph's update topic carries public updates only.
+            if (result.onChainResult && result.publicQuads && !isCuratedUpdate) {
                 try {
                     const dataGraph = knowledgeAssetLayerGraphUri(contextGraphId, MemoryLayer.VerifiableMemory, updateScope, opts?.subGraphName);
                     const nquadsStr = result.publicQuads
@@ -2238,6 +2192,18 @@ export class PublishMethods extends DKGAgentBase {
                 `KaNumberAllocator on the agent (daemon lifecycle) or supply a ` +
                 `preSignedAuthorAttestation whose reservedKaId lives in the author's namespace.`), { code: SEAL_CAPABILITY_GAP_CODE });
         }
+        // GH#2958 — a draft of a PUBLISHED KA is numbered from the confirmed record `update()` will
+        // validate, not from the lifecycle counter. That counter is "last FINALIZED": it only ever
+        // grows, so every finalized update that is abandoned before it is published (superseded,
+        // discarded, replaced by pull-from) would push the next draft one number too high, past
+        // what `update()`, the publisher and the chain accept, and the KA could never be updated
+        // again. An abandoned draft instead shares its number with its successor, as an
+        // unpublished mint already does. The lifecycle counter above stays the fallback for a
+        // record that cannot answer. The number is not signed (the attestation binds merkleRoot,
+        // author, reservedKaId and scheme), so deriving it here changes no signature.
+        if (hasConfirmedVm) {
+            assertionVersion = await this._nextUpdateVersionOrUndefined(reservedKaId, contextGraphId, opts?.subGraphName) ?? assertionVersion;
+        }
         // 8. Build EIP-712 typed data (binds reservedKaId — OT-RFC-43 §F2).
         const typedData = buildAuthorAttestationTypedData({
             chainId,
@@ -2748,12 +2714,21 @@ export class PublishMethods extends DKGAgentBase {
                 recipientKeyId: r.recipientKeyId,
             })),
         });
+        const recipientRouteHash = computeSwmSenderKeyRecipientRouteHash({
+            contextGraphId,
+            subGraphName,
+            recipients: resolution.recipients,
+        });
         const stateKey = swmSenderStateKey(contextGraphId, subGraphName, senderAddress);
         let state = this.swmSenderKeySendStates.get(stateKey);
-        if (!state || state.membershipHash !== membershipHash) {
+        if (!state
+            || state.membershipHash !== membershipHash
+            || state.recipientRouteHash !== recipientRouteHash) {
             const reason = !state
                 ? 'no persisted state'
-                : `membership changed (was=${state.membershipHash} now=${membershipHash})`;
+                : state.membershipHash !== membershipHash
+                    ? `membership changed (was=${state.membershipHash} now=${membershipHash})`
+                    : `recipient routes changed (was=${state.recipientRouteHash ?? 'legacy-untracked'} now=${recipientRouteHash})`;
             this.log.info(ctx, `${logPrefix}: bootstrapping/rotating swm-sender-key epoch for curated CG ${contextGraphId} ` +
                 `(sender=${senderAddress}, recipients=${resolution.recipients.length}, reason=${reason})`);
             const pruned = this.prunePendingSenderKeysForEpochRotation({
@@ -2778,7 +2753,12 @@ export class PublishMethods extends DKGAgentBase {
             await this.saveSwmSenderKeyState();
         }
         else {
-            await this.drainPendingSenderKeyForRecipients(resolution.recipients, ctx);
+            await this.drainPendingSenderKeyForRecipients(resolution.recipients, ctx, {
+                contextGraphId,
+                subGraphName,
+                senderAgentAddress: state.senderAgentAddress,
+                epochId: state.epochId,
+            });
         }
         return {
             chainKey: state.chainKey,
@@ -3202,6 +3182,17 @@ export class PublishMethods extends DKGAgentBase {
             throw Object.assign(new Error(`Cannot publish "${name}" asynchronously: the current SWM share has no sealed assertion pointer. ` +
                 `Finalize and share the full asset before publishing.`), { code: 'PUBLISH_INTENT_STALE' });
         }
+        if (operationPlan.kind === 'update') {
+            // GH#2958 — refuse a finalized update `update()` is going to refuse, here, before a job
+            // exists, so the client learns it at the moment it can act. Last, so every recovery this
+            // error recommends (re-open from the shared copy) is possible whenever it is raised. A
+            // confirmed record that cannot answer leaves the decision to `update()`.
+            const sealScope = createGraphKnowledgeAssetScope(seal.kaUal, seal.assertionVersion);
+            const requiredVersion = await this._nextUpdateVersionOrUndefined(packKnowledgeAssetIdFromIdentity(sealScope), contextGraphId, opts?.subGraphName);
+            if (requiredVersion !== undefined && requiredVersion !== BigInt(seal.assertionVersion)) {
+                throw versionGapError(seal.kaUal, seal.assertionVersion, requiredVersion);
+            }
+        }
         const sealMerkleRoot = (merkleBare.startsWith('0x') ? merkleBare : `0x${merkleBare}`);
         const queuedSeal = {
             merkleRoot: ethers.hexlify(seal.merkleRoot),
@@ -3261,43 +3252,32 @@ export class PublishMethods extends DKGAgentBase {
             intentKey: createKnowledgeAssetVmPublishIntentKey(request),
         };
     }
-    async preflightKnowledgeAssetVmPublishSnapshot(request) {
-        const snapshot = createKnowledgeAssetVmPublishSnapshotRequest(request);
-        const snapshotMetadata = createKnowledgeAssetVmPublishSnapshotMetadata(request);
+    /**
+     * GH#2958 — the version a finalized update of this KA must carry, read from the SAME confirmed
+     * record `update()` validates, so the number a draft is sealed with and the number `update()`
+     * demands cannot disagree. `undefined` when that record cannot answer (not materialized here,
+     * not confirmed yet, corrupt or legacy): the caller then falls back to its own rule. Anything
+     * else (a store failure) propagates - a transient read error must never silently pick a number.
+     */
+    async _nextUpdateVersionOrUndefined(kaId, contextGraphId, subGraphName) {
         try {
-            const resolved = await resolveLiftWorkspaceSlice({
-                store: this.store,
-                graphManager: new GraphManager(this.store),
-                request: snapshot,
-                publicSnapshotStore: this.publicSnapshotStore,
-            });
-            validateLiftPublishPayload({
-                request: snapshot,
-                metadata: snapshotMetadata,
-                resolved,
-            });
-            if (resolved.quads.length === 0 && (resolved.privateQuads ?? []).length === 0) {
-                throw new Error(`No queued shared-memory snapshot quads for context graph ${request.contextGraphId} ` +
-                    `share operation ${request.shareOperationId}`);
-            }
+            const scope = await resolveDirectRootlessUpdateScope(this, this.chain.chainId, kaId, contextGraphId, subGraphName);
+            return BigInt(scope.assertionVersion);
         }
         catch (err) {
-            if (err instanceof LegacyKnowledgeAssetReadOnlyError)
+            if (!isRootlessUpdateError(err) && !(err instanceof LegacyKnowledgeAssetReadOnlyError))
                 throw err;
-            const wrapped = new Error(`Cannot enqueue VM publish for "${request.name}" because share snapshot ` +
-                `${request.shareOperationId} is unavailable or stale. Re-share the knowledge asset before enqueueing: ` +
-                (err instanceof Error ? err.message : String(err)));
-            wrapped.code = 'PUBLISH_INTENT_STALE';
-            throw wrapped;
+            this.log.debug(createOperationContext('publish'), `The confirmed record of KA ${kaId} cannot number its next update (${err.code}); using the lifecycle counter`);
+            return undefined;
         }
     }
+    async preflightKnowledgeAssetVmPublishSnapshot(request) {
+        return preflightKnowledgeAssetVmPublishSnapshot({
+            store: this.store, publicSnapshotStore: this.publicSnapshotStore, log: this.log, request,
+        });
+    }
     async preflightQueuedKnowledgeAssetVmPublishExecution(request, opts) {
-        if (request.contentScopeVersion !== GRAPH_KA_CONTENT_SCOPE_VERSION
-            || request.kaUal === undefined
-            || request.assertionVersion === undefined
-            || request.publicTripleCount === undefined
-            || request.privateTripleCount === undefined
-            || request.roots.length !== 0) {
+        if (!isGraphScopedKnowledgeAssetVmPublishRequest(request)) {
             throw new LegacyKnowledgeAssetReadOnlyError();
         }
         createGraphKnowledgeAssetScope(request.kaUal, request.assertionVersion);
@@ -3380,10 +3360,10 @@ export class PublishMethods extends DKGAgentBase {
             throw stale(`Knowledge asset VM publish intent for "${request.name}" changed after enqueue: ` +
                 'the immutable SWM access envelope no longer matches the queued request.');
         }
-        // `_stampSwmPointer` is explicitly a best-effort post-commit projection.
-        // A managed-store restart can therefore leave this optional lifecycle row
-        // absent even though the complete-share marker and immutable graph-scoped
-        // head both committed. Absence alone is not proof that the queued content
+        // The swm pointer is a divergence-only projection, and `publishAsync`
+        // keeps its stamp best-effort. The lifecycle row can therefore be absent
+        // even though the complete-share marker and immutable graph-scoped head
+        // both committed. Absence alone is not proof that the queued content
         // changed: the exact operation id, assertion version, access envelope and
         // queued WM root above are the durable authority. A present-but-different
         // SWM pointer remains terminally stale via the comparison above.
@@ -3484,12 +3464,7 @@ export class PublishMethods extends DKGAgentBase {
     }
     async _finalizeRecoveredQueuedKnowledgeAssetVmPublish(input, ctx) {
         const { request, job, lookup, recovery, signal } = input;
-        if (request.contentScopeVersion !== GRAPH_KA_CONTENT_SCOPE_VERSION
-            || request.kaUal === undefined
-            || request.assertionVersion === undefined
-            || request.publicTripleCount === undefined
-            || request.privateTripleCount === undefined
-            || request.roots.length !== 0) {
+        if (!isGraphScopedKnowledgeAssetVmPublishRequest(request)) {
             throw new LegacyKnowledgeAssetReadOnlyError();
         }
         const recovered = await normalizeRecoveredNamedKaPublish({
@@ -3697,11 +3672,7 @@ export class PublishMethods extends DKGAgentBase {
         if (request.contentScopeVersion !== GRAPH_KA_CONTENT_SCOPE_VERSION) {
             throw new LegacyKnowledgeAssetReadOnlyError();
         }
-        if (request.roots.length !== 0
-            || request.kaUal === undefined
-            || request.assertionVersion === undefined
-            || request.publicTripleCount === undefined
-            || request.privateTripleCount === undefined) {
+        if (!isGraphScopedKnowledgeAssetVmPublishRequest(request)) {
             throw new Error('Queued graph-scoped VM publish has an incomplete KA content envelope');
         }
         const graphScope = createGraphKnowledgeAssetScope(request.kaUal, request.assertionVersion);
@@ -3791,12 +3762,14 @@ export class PublishMethods extends DKGAgentBase {
         let result;
         const clearPublishedGraph = async (label) => {
             try {
-                await publisher.clearPublishedKnowledgeAssetSwm(request.contextGraphId, sharedMemoryScope, request.subGraphName, ctx, graphScope.ual);
+                await publisher.clearPublishedKnowledgeAssetSwm(request.contextGraphId, sharedMemoryScope, request.subGraphName, ctx, graphScope.ual, graphScope.assertionVersion);
             }
             catch (err) {
                 this.log.warn(ctx, `Failed to clear published SWM graph after confirmed queued ${label} of <${lifecycleUri}>: ` +
                     (err instanceof Error ? err.message : String(err)));
+                return;
             }
+            await this.retireLegacySwmAfterConfirmedLocalPublish(request.contextGraphId, graphScope.ual, graphScope.assertionVersion, request.subGraphName, ctx);
         };
         const clearRemainingSharedMemory = async () => {
             try {
@@ -4022,29 +3995,6 @@ export class PublishMethods extends DKGAgentBase {
             catch {
                 this.log.warn(ctx, `No peers subscribed to ${topic} yet`);
             }
-            try {
-                const gm = new GraphManager(this.store);
-                const wsMetaGraph = request.subGraphName
-                    ? gm.sharedMemoryMetaUri(request.contextGraphId, request.subGraphName)
-                    : contextGraphWorkspaceMetaGraphUri(request.contextGraphId);
-                const keepLiteral = `"${keepRootCopyOnLabel}"`;
-                for (const root of rootEntities.filter(isSafeIri)) {
-                    await deleteByPatternWithoutCount(this.store, {
-                        subject: root,
-                        predicate: KEEP_ROOT_COPY_PREDICATE,
-                        graph: wsMetaGraph,
-                    });
-                    await this.store.insert([{
-                            subject: root,
-                            predicate: KEEP_ROOT_COPY_PREDICATE,
-                            object: keepLiteral,
-                            graph: wsMetaGraph,
-                        }]);
-                }
-            }
-            catch (err) {
-                this.log.warn(ctx, `Failed to persist keepRootCopyOnLabel signal for ${result.ual}: ${err instanceof Error ? err.message : String(err)}`);
-            }
         }
         if (result.status === 'confirmed') {
             try {
@@ -4261,7 +4211,8 @@ export class PublishMethods extends DKGAgentBase {
             // that mirrored the share), so SWM and VM permanently disagreed.
             if (result.status === 'confirmed') {
                 try {
-                    await publisher.clearPublishedKnowledgeAssetSwm(contextGraphId, sharedMemoryScope, opts?.subGraphName, opts?.operationCtx ?? createOperationContext('publishFromSWM'), graphScope.ual);
+                    await publisher.clearPublishedKnowledgeAssetSwm(contextGraphId, sharedMemoryScope, opts?.subGraphName, opts?.operationCtx ?? createOperationContext('publishFromSWM'), graphScope.ual, graphScope.assertionVersion);
+                    await this.retireLegacySwmAfterConfirmedLocalPublish(contextGraphId, graphScope.ual, graphScope.assertionVersion, opts?.subGraphName, opts?.operationCtx ?? createOperationContext('publishFromSWM'));
                 }
                 catch (err) {
                     this.log.warn(opts?.operationCtx ?? createOperationContext('publishFromSWM'), `Failed to clear SWM after confirmed update of <${lifecycleUri}>: ` +
@@ -4527,6 +4478,21 @@ export class PublishMethods extends DKGAgentBase {
             return;
         await this.observeRfc64ConfirmedVmV1(input);
     }
+    /** The local confirmed publisher has already written VM and drained this exact SWM root. */
+    async retireLegacySwmAfterConfirmedLocalPublish(contextGraphId, kaUal, assertionVersion, subGraphName, ctx) {
+        try {
+            await this.retireLegacySwmAfterVerifiedVmTwin({
+                contextGraphId,
+                kaUal,
+                assertionVersion,
+                subGraphName,
+            });
+        }
+        catch (err) {
+            this.log.warn(ctx, `Failed to retire the legacy SWM boundary after confirmed local VM publish: ` +
+                (err instanceof Error ? err.message : String(err)));
+        }
+    }
     /**
      * OT-RFC-43 A2 — mint a `precomputedUpdateAttestation` over
      * `UpdateAuthorAttestation(kaId, newMerkleRoot=seal.merkleRoot, author)` for
@@ -4641,10 +4607,16 @@ export class PublishMethods extends DKGAgentBase {
      * OT-RFC-43 A2 (decision 2) — stamp `dkg:swmCurrentAssertion` on the
      * lifecycle URN when an assertion is promoted/shared into SWM. The pointer
      * value is the assertion's sealed merkle root hex (read from the seal on the
-     * assertion-graph URI). Best-effort: a missing seal (a non-finalized
-     * promote) leaves the SWM pointer unset, which `deriveStatus` reads as "not
-     * yet wm-sealed for SWM". Never throws — the SWM share itself already
-     * committed.
+     * assertion-graph URI). A missing seal (a non-finalized promote) leaves the
+     * SWM pointer unset, which `deriveStatus` reads as "not yet wm-sealed for
+     * SWM".
+     *
+     * A store failure is logged and RETHROWN. The SWM share already committed, so
+     * the caller owns the classification: swallowing it here left a share that
+     * reported success with a permanently missing root (GH#2901). The stamp is an
+     * idempotent drop-then-set, so replaying the already-committed operation is
+     * the repair. The drop and the set are two store calls: until that replay, a
+     * failure between them leaves the committed share with no pointer.
      */
     async _stampSwmPointer(contextGraphId, name, agentAddress, subGraphName) {
         try {
@@ -4665,52 +4637,26 @@ export class PublishMethods extends DKGAgentBase {
         catch (err) {
             this.log.warn(createOperationContext('share'), `Failed to stamp swmCurrentAssertion for "${name}" in "${contextGraphId}": ` +
                 (err instanceof Error ? err.message : String(err)));
+            throw err;
         }
     }
-    /**
-     * OT-RFC-49 legacy compatibility — ensure a curated CG's public `_catalog`
-     * floor is in SWM for an arbitrary root-selected combined-model publish.
-     *
-     * New graph-scoped KAs never call this helper: they keep the catalog detached
-     * from WM/SWM and derive its proof material at the publisher boundary. This
-     * remains only for legacy selection-based publishes whose author seal and KC
-     * root intentionally use the historical combined model.
-     *
-      * IDEMPOTENT: repeated insertion dedupes in the store/V10 Merkle path because
-      * the floor is deterministic, so `catalogLeafCount` stays stable across
-      * repeated legacy selection publishes.
-     *
-     * Returns a possibly-extended `selection`: for a `{rootEntities}` publish the
-     * CG-DID catalog subject is appended so it is in scope for BOTH the author seal
-     * (`_loadSelectedSWMQuads`) and the publisher's reload — which scope identically.
-     * For `selection: 'all'` the selection is returned unchanged (both already read
-     * the whole SWM graph). The generated floor is written into the same explicit
-     * graph scope as the publish; otherwise an exact named-lifecycle read would
-     * correctly exclude a floor left in the legacy bucket.
-     */
-    async _ensureCuratedCatalogInSwm(contextGraphId, selection, subGraphName, ctx, scope = { kind: 'complete-family' }) {
-        const swmGraph = contextGraphSharedMemoryUri(contextGraphId, subGraphName);
-        const catalogTargetGraph = canonicalSharedMemoryScopeWriteGraph(swmGraph, scope);
-        const cgDid = contextGraphDataUri(contextGraphId);
-        const { quads: catalogQuads } = appendMissingGeneratedPrivateCatalogFloor(contextGraphId, [], catalogTargetGraph);
-        await this.store.insert(catalogQuads);
-        this.log.info(ctx, `OT-RFC-49: ensured ${catalogQuads.length}-quad public _catalog floor in SWM for curated CG ${contextGraphId} (from-SWM publish without finalize)`);
-        if (selection !== 'all' && !selection.rootEntities.includes(cgDid)) {
-            return { rootEntities: [...selection.rootEntities, cgDid] };
-        }
-        return selection;
-    }
     /**
      * Publish shared memory content: read from SWM graph and publish with full finality (data graph + chain).
      * After on-chain confirmation, broadcasts a lightweight FinalizationMessage so peers with matching
      * SWM state can promote it to canonical without re-downloading the full payload.
      *
-     * #1116 (round 9) — INTENTIONALLY NOT marker-gated. This is the
-     * "publish an arbitrary caller-selected SWM slice" internal escape hatch
-     * retained for substrate mechanics (#1087): it mints a FRESH inline seal over the
-     * selected slice rather than consuming a finalized named lifecycle, so the
-     * swmShareComplete full-share invariant does not apply. The marker gate lives on
-     * `publishFromFinalizedAssertion` (the named-lifecycle /vm/publish path) only.
+     * The publish must be graph-scoped (`contentScopeVersion`, `kaUal`,
+     * `assertionVersion`): a call without that scope is refused with
+     * `LegacyKnowledgeAssetReadOnlyError`. `publishFromFinalizedAssertion`
+     * supplies the scope from the finalized seal and is the entry point for
+     * callers that hold a named assertion.
+     *
+     * #1116 (round 9) — INTENTIONALLY NOT marker-gated. This is the internal
+     * substrate entry (#1087): without a precomputed seal it mints a FRESH inline
+     * seal over the selected slice rather than consuming a finalized named
+     * lifecycle, so the swmShareComplete full-share invariant does not apply. The
+     * marker gate lives on `publishFromFinalizedAssertion` (the named-lifecycle
+     * /vm/publish path) only.
      */
     async publishFromSharedMemory(contextGraphId, selection, options) {
         return withSpan('agent.publish_from_swm', async (span) => {
@@ -4725,6 +4671,16 @@ export class PublishMethods extends DKGAgentBase {
                     ...(chainId ? { 'dkg.chain_id': chainId } : {}),
                 });
                 const ctx = options?.operationCtx ?? createOperationContext('publishFromSWM');
+                // A publish names the Knowledge Asset's own graph. Root-entity Knowledge
+                // Assets are read-only: peers finalize nothing else, and a Core keeps no
+                // copy of such a publish that it could promote.
+                if (options?.contentScopeVersion !== GRAPH_KA_CONTENT_SCOPE_VERSION) {
+                    const scopeVersion = options?.contentScopeVersion;
+                    if (scopeVersion === undefined || scopeVersion === 0 || scopeVersion === 1) {
+                        throw new LegacyKnowledgeAssetReadOnlyError();
+                    }
+                    throw new Error(`Unsupported KA content scope version ${scopeVersion}`);
+                }
                 const effectiveSubCG = options?.subContextGraphId ?? options?.contextGraphId;
                 // `ctxGraphIdStr` doubles as `publishContextGraphId` for REMAP-flow
                 // publishes — the publisher uses its presence as a signal to DELETE the
@@ -4733,17 +4689,6 @@ export class PublishMethods extends DKGAgentBase {
                 const ctxGraphIdStr = effectiveSubCG != null ? String(effectiveSubCG) : undefined;
                 const onChainId = ctxGraphIdStr ?? (await this.getContextGraphOnChainId(contextGraphId)) ?? undefined;
                 const v10ACKProvider = this.createV10ACKProvider(contextGraphId);
-                // OT-RFC-49 catalog handling differs by content model. Legacy arbitrary
-                // SWM selections retain their combined-model floor injection. A V2 named
-                // lifecycle carries only the trusted floor capability: the publisher
-                // derives a detached catalog commitment without altering the exact KA
-                // graph or its author seal.
-                const graphScopedPublish = options?.contentScopeVersion === GRAPH_KA_CONTENT_SCOPE_VERSION;
-                let localTrustedNonManifestCatalogTriples;
-                if (!graphScopedPublish && onChainId != null && (await this.isPrivateContextGraph(contextGraphId))) {
-                    localTrustedNonManifestCatalogTriples = generatedPrivateCatalogTripleKeys(contextGraphId);
-                    selection = await this._ensureCuratedCatalogInSwm(contextGraphId, selection, options?.subGraphName, ctx, options?.sharedMemoryScope);
-                }
                 // RFC-001 §9.x — selection-based publish bridge. If the caller
                 // already sealed the content (named-assertion lifecycle) they
                 // pass `precomputedAttestation` through and we forward verbatim.
@@ -4769,7 +4714,7 @@ export class PublishMethods extends DKGAgentBase {
                             ...(options?.schemeVersion !== undefined
                                 ? { schemeVersion: options.schemeVersion }
                                 : {}),
-                            graphScoped: graphScopedPublish,
+                            graphScoped: true,
                         });
                     }
                 }
@@ -4802,17 +4747,16 @@ export class PublishMethods extends DKGAgentBase {
                     this.log.info(ctx, `LU-11: curated CG ${contextGraphId} — chunked path active (per-chunk SWM gossip + V2 ACK)`);
                 }
                 // V2 curation is decided by the live chain-aware encryption resolver, not
-                // by a second local `_meta` read. Keep the legacy combined-model behavior
-                // unchanged, but make graph-scoped publishes carry the detached catalog
-                // whenever the exact same operation was resolved as curated.
-                const trustedNonManifestCatalogTriples = graphScopedPublish
-                    ? resolveCuratedV2CatalogCapability({
-                        contextGraphId,
-                        graphScoped: true,
-                        onChainContextGraphId: onChainId,
-                        encryptInlinePayload,
-                    })
-                    : localTrustedNonManifestCatalogTriples;
+                // by a second local `_meta` read. The publish carries the detached catalog
+                // (OT-RFC-49) whenever the exact same operation was resolved as curated:
+                // the publisher derives its commitment without altering the exact KA graph
+                // or its author seal.
+                const trustedNonManifestCatalogTriples = resolveCuratedV2CatalogCapability({
+                    contextGraphId,
+                    graphScoped: true,
+                    onChainContextGraphId: onChainId,
+                    encryptInlinePayload,
+                });
                 const publisher = options?.publisherOverride ?? this.publisher;
                 const result = await publisher.publishFromSharedMemory(contextGraphId, selection, {
                     operationCtx: ctx,
@@ -4841,6 +4785,11 @@ export class PublishMethods extends DKGAgentBase {
                     encryptInlinePayload,
                     encryptInlineChunked,
                 });
+                if (result.status === 'confirmed'
+                    && options?.kaUal !== undefined
+                    && options.assertionVersion !== undefined) {
+                    await this.retireLegacySwmAfterConfirmedLocalPublish(contextGraphId, options.kaUal, String(options.assertionVersion), options.subGraphName, ctx);
+                }
                 span.setAttribute('dkg.publish_status', result.status);
                 if (result.status === 'failed') {
                     span.setStatus({ code: SpanStatusCode.ERROR });
@@ -4892,19 +4841,15 @@ export class PublishMethods extends DKGAgentBase {
                         targetContextGraphId: result.contextGraphError ? undefined : broadcastCgId,
                         subGraphName: options?.subGraphName,
                         keepRootCopyOnLabel,
-                        ...(options?.contentScopeVersion === GRAPH_KA_CONTENT_SCOPE_VERSION
-                            ? {
-                                contentScopeVersion: GRAPH_KA_CONTENT_SCOPE_VERSION,
-                                assertionVersion: String(options.assertionVersion),
-                                publicTripleCount: options.publicTripleCount ?? 0,
-                                ...(options.privateMerkleRoot
-                                    ? { privateMerkleRoot: options.privateMerkleRoot }
-                                    : {}),
-                                privateTripleCount: options.privateTripleCount ?? 0,
-                                accessPolicy: result.accessPolicy ?? 'ownerOnly',
-                                allowedPeers: result.allowedPeers ?? [],
-                            }
+                        contentScopeVersion: GRAPH_KA_CONTENT_SCOPE_VERSION,
+                        assertionVersion: String(options.assertionVersion),
+                        publicTripleCount: options.publicTripleCount ?? 0,
+                        ...(options.privateMerkleRoot
+                            ? { privateMerkleRoot: options.privateMerkleRoot }
                             : {}),
+                        privateTripleCount: options.privateTripleCount ?? 0,
+                        accessPolicy: result.accessPolicy ?? 'ownerOnly',
+                        allowedPeers: result.allowedPeers ?? [],
                     };
                     const topic = contextGraphFinalizationTopic(contextGraphId);
                     try {
@@ -4914,38 +4859,6 @@ export class PublishMethods extends DKGAgentBase {
                     catch {
                         this.log.warn(ctx, `No peers subscribed to ${topic} yet`);
                     }
-                    // Durable keep-root signal. The gossip envelope's `keepRootCopyOnLabel`
-                    // only reaches peers online for the broadcast; a subscriber that missed
-                    // it later recovers the publish via the chain-driven reconcile sweep,
-                    // which has no wire to learn the dual-write intent from. Persist the same
-                    // decision per root into SWM workspace meta — co-located with the per-root
-                    // `privateMerkleRoot` that already replicates to subscribers — so the
-                    // reconcile path can mirror the gossip dual-write decision. Read back by
-                    // `FinalizationHandler.getKeepRootCopySignal`. Updates reuse a root
-                    // entity, so replace any prior value rather than accumulate.
-                    try {
-                        const gm = new GraphManager(this.store);
-                        const wsMetaGraph = options?.subGraphName
-                            ? gm.sharedMemoryMetaUri(contextGraphId, options.subGraphName)
-                            : contextGraphWorkspaceMetaGraphUri(contextGraphId);
-                        const keepLiteral = `"${keepRootCopyOnLabel}"`;
-                        for (const root of rootEntities.filter(isSafeIri)) {
-                            await deleteByPatternWithoutCount(this.store, {
-                                subject: root,
-                                predicate: KEEP_ROOT_COPY_PREDICATE,
-                                graph: wsMetaGraph,
-                            });
-                            await this.store.insert([{
-                                    subject: root,
-                                    predicate: KEEP_ROOT_COPY_PREDICATE,
-                                    object: keepLiteral,
-                                    graph: wsMetaGraph,
-                                }]);
-                        }
-                    }
-                    catch (err) {
-                        this.log.warn(ctx, `Failed to persist keepRootCopyOnLabel signal for ${result.ual}: ${err instanceof Error ? err.message : String(err)}`);
-                    }
                 }
                 recordPublishOutcome(result.status, 'swm', publishStartedAt, chainId);
                 return result;