@origintrail-official/dkg-agent 10.0.19 → 10.0.21

package/dist/dkg-agent-cg-registry.js

@@ -1,9 +1,21 @@
 // SPDX-License-Identifier: Apache-2.0
+/**
+ * Context-graph registration / sub-graph subsystem extracted from dkg-agent.ts
+ * as a mixin holder: on-chain registration + policy reads, stored
+ * registration options, allowed-peers, sub-graph create/list/remove,
+ * local-CG materialization, and endorsement trust-target helpers. 1:1 move;
+ * methods take `this: DKGAgent` so cross-calls resolve against the composed
+ * class.
+ */
+import { contextGraphBindingAbortReason, raceContextGraphBindingAgainstAbort } from './internal/context-graph-binding-abort.js';
+import { resolveApprovedPrivateReplicaAuthority, } from './approved-private-replica.js';
 import { contextGraphPublishTopic, contextGraphDataGraphUri, contextGraphMetaGraphUri, SYSTEM_CONTEXT_GRAPHS, DKG_ONTOLOGY, createOperationContext, sparqlString, assertSafeIri, TRUST_LEVEL_PREDICATE, buildTrustLevelQuads, assertRdfLiteralMutf8Safe, contextGraphOnChainIdBindingQuery, contextGraphMetadataHomeGraph, } from '@origintrail-official/dkg-core';
 import { GraphManager, deleteByPatternWithoutCount, tryUpdateWithTouchedGraphs } from '@origintrail-official/dkg-storage';
-import { CONTEXT_GRAPH_AUTHORITY_RPC_SITES as CG_AUTH_RPC_SITES, withRpcUsageSite } from '@origintrail-official/dkg-chain';
+import { CONTEXT_GRAPH_AUTHORITY_RPC_SITES as CG_AUTH_RPC_SITES, withRpcRequestContext, withRpcUsageSite } from '@origintrail-official/dkg-chain';
+import { finalizedTargetPlan, projectFinalizedTargets, peekFinalizedTargets } from './internal/context-graph-authority/finalized-target-projection.js';
 import { isRfc64AuthorityRpcCircuitOpenErrorV1 } from './rfc64/authority-rpc-circuit-breaker-v1.js';
-import { finalizedContextGraphSnapshotMismatchV1, resolveFinalizedContextGraphNameBindingV1, } from './internal/context-graph-authority/finalized-context-graph-binding.js';
+import { finalizedContextGraphSnapshotMismatchV1, } from './internal/context-graph-authority/finalized-context-graph-binding.js';
+import { contextGraphReadAuthorityDependencyOf, } from './context-graph-authority-dependency.js';
 import { TIMEOUT_SENTINEL, ON_CHAIN_PUBLISH_POLICY_CACHE_TTL_MS, CONTEXT_GRAPH_NAME_HASH_RESOLUTION_TIMEOUT_MS, } from './dkg-agent-constants.js';
 import { chainAuthorityReadBudgetsOf } from './chain-authority-read-budgets.js';
 import { finalizedAuthorityColdResolutionOf } from './finalized-authority-cold-resolution.js';
@@ -11,40 +23,11 @@ import { isBoundedOperationTimeoutError, runBoundedOperation } from './bounded-o
 import { parseRfc64AuthoritySnapshotV1 } from './rfc64/release-native-catalog-authority-v1.js';
 import { DKGAgentBase } from './dkg-agent-base.js';
 import { LocalContextGraphRegistrationStatusStore } from './local-context-graph-registration-status.js';
-import { isCanonicalAuthoritativeContextGraphId, isCanonicalPositiveContextGraphId, localContextGraphIdMatchesCommittedNameHash, } from './context-graph-binding-state.js';
+import { isCanonicalPositiveContextGraphId, localContextGraphIdMatchesCommittedNameHash, } from './context-graph-binding-state.js';
 import { createContextGraphRegistrationReadPlan, } from './context-graph-registration-read-plan.js';
+import { proveOnChainIdClaim, provenOnChainIdsFor, refutesOnChainBinding, } from './context-graph-claim-proof.js';
 const CHAIN_ATTESTED_DECLARATION_SCAN_MAX = 512;
 const CONTEXT_GRAPH_URI_PREFIX = 'did:dkg:context-graph:';
-function contextGraphBindingAbortReason(signal) {
-    if (signal.reason instanceof Error)
-        return signal.reason;
-    const error = new Error(String(signal.reason ?? 'Context Graph binding resolution aborted'));
-    error.name = 'AbortError';
-    return error;
-}
-function raceContextGraphBindingAgainstAbort(work, signal) {
-    if (!signal)
-        return work;
-    if (signal.aborted)
-        return Promise.reject(contextGraphBindingAbortReason(signal));
-    return new Promise((resolve, reject) => {
-        const onAbort = () => {
-            cleanup();
-            reject(contextGraphBindingAbortReason(signal));
-        };
-        const cleanup = () => signal.removeEventListener('abort', onAbort);
-        signal.addEventListener('abort', onAbort, { once: true });
-        work.then((value) => {
-            cleanup();
-            resolve(value);
-        }, (error) => {
-            cleanup();
-            reject(error);
-        });
-        if (signal.aborted)
-            onAbort();
-    });
-}
 function localContextGraphIdFromTerm(raw) {
     const uri = typeof raw === 'string' ? raw.replace(/^<|>$/g, '') : '';
     return uri.startsWith(CONTEXT_GRAPH_URI_PREFIX) && uri.length > CONTEXT_GRAPH_URI_PREFIX.length
@@ -330,23 +313,6 @@ export class ContextGraphRegistryMethods extends DKGAgentBase {
      */
     async resolveFinalizedContextGraphAuthorityTargetsV1(contextGraphIds, options = {}) {
         const { onRpcRead, durableBindingHints, ...chainReadOptions } = options;
-        const uniqueContextGraphIds = [...new Set(contextGraphIds)];
-        const bindingTargets = uniqueContextGraphIds.map((contextGraphId) => {
-            const hintedBinding = durableBindingHints?.get(contextGraphId);
-            const durableHint = hintedBinding?.contextGraphId === contextGraphId
-                ? hintedBinding
-                : undefined;
-            const { localId, subscription, expectedNameHash } = resolveFinalizedContextGraphNameBindingV1(this, contextGraphId, durableHint);
-            const authoritativeOnChainId = this.contextGraphBindingState
-                .authorityIndexOnChainIdFor(localId, subscription ?? durableHint);
-            return {
-                contextGraphId,
-                expectedNameHash,
-                expectedOnChainId: authoritativeOnChainId === undefined
-                    ? undefined
-                    : BigInt(authoritativeOnChainId),
-            };
-        });
         const indexReader = this.chain.contextGraphAuthorityIndexRevisionReader;
         if (indexReader === undefined)
             return { kind: 'legacy-current' };
@@ -355,41 +321,25 @@ export class ContextGraphRegistryMethods extends DKGAgentBase {
         // commitments make that lookup deliberately ambiguous even though the
         // locally persisted binding remains authoritative. The caller still owns
         // a finalized numeric snapshot batch and validates its id/name evidence.
-        const targets = new Map();
-        const reverseBindingTargets = bindingTargets.filter((target) => {
-            if (target.expectedOnChainId === undefined)
-                return true;
-            targets.set(target.contextGraphId, Object.freeze({
-                kind: 'durable-binding',
-                expectedNameHash: target.expectedNameHash,
-                expectedOnChainId: target.expectedOnChainId,
-            }));
-            return false;
-        });
+        const plan = finalizedTargetPlan(this, this.contextGraphBindingState.authorityIndexOnChainIdFor.bind(this.contextGraphBindingState), contextGraphIds, durableBindingHints);
+        const { targets, reverseBindingTargets } = plan;
         if (reverseBindingTargets.length === 0) {
             return { kind: 'finalized-index', targets };
         }
-        const resolveSnapshots = indexReader
-            .resolveFinalizedContextGraphAuthoritySnapshotsByNameHashes;
+        const resolveSnapshots = indexReader.resolveFinalizedContextGraphAuthoritySnapshotsByNameHashes;
         if (resolveSnapshots !== undefined) {
             options.signal?.throwIfAborted();
             onRpcRead?.();
-            const snapshotsByNameHash = await resolveSnapshots.call(indexReader, reverseBindingTargets.map(({ expectedNameHash }) => expectedNameHash), chainReadOptions);
+            // Registration classification gates private catalog admission and read
+            // access. A background reconciliation must not sit behind the ordinary
+            // background RPC reserve until the authority read's fail-closed deadline
+            // expires; use the same bounded foreground authority lane as explicit
+            // security reads, while retaining the caller's cancellation signal.
+            const snapshotsByNameHash = await withRpcRequestContext({ requestClass: 'foreground', admissionPriority: 'authority', signal: options.signal }, () => resolveSnapshots.call(indexReader, reverseBindingTargets.map(({ expectedNameHash }) => expectedNameHash), chainReadOptions));
             // Custom readers may not honor cancellation or may return a superset.
             // Publish only exact logical targets after the caller's final fence.
             options.signal?.throwIfAborted();
-            for (const { contextGraphId, expectedNameHash } of reverseBindingTargets) {
-                const finalizedSnapshot = snapshotsByNameHash.get(expectedNameHash);
-                if (finalizedSnapshot !== undefined) {
-                    targets.set(contextGraphId, Object.freeze({
-                        kind: 'resolved-snapshot',
-                        expectedNameHash,
-                        expectedOnChainId: BigInt(finalizedSnapshot.contextGraphId),
-                        finalizedSnapshot,
-                    }));
-                }
-            }
-            return { kind: 'finalized-index', targets };
+            return projectFinalizedTargets(plan, snapshotsByNameHash);
         }
         if (reverseBindingTargets.length === 1) {
             const resolveSnapshot = indexReader
@@ -547,7 +497,7 @@ export class ContextGraphRegistryMethods extends DKGAgentBase {
             && this.localContextGraphProvenance.hasLocalCreate(contextGraphId)) {
             try {
                 if (await this.isLocalFirstUnregisteredContextGraph(contextGraphId)) {
-                    return { kind: 'unregistered' };
+                    return { kind: 'unregistered', unregisteredEvidence: 'local-create' };
                 }
             }
             catch (err) {
@@ -572,6 +522,98 @@ export class ContextGraphRegistryMethods extends DKGAgentBase {
             ?? (hasBindingCandidate
                 ? chainAuthorityReadBudgetsOf(this).requestTimeoutMs
                 : CONTEXT_GRAPH_NAME_HASH_RESOLUTION_TIMEOUT_MS);
+        /**
+         * Bind an unregistered result to the current durable private-join proof.
+         *
+         * Finalized-index adapters use this proof after exact finalized absence.
+         * Legacy adapters use it only after their compatibility lookup has already
+         * returned unregistered. In both cases, retaining the source-qualified
+         * peer gate on the typed result is what keeps SWM consumers from either
+         * widening through merged metadata or rejecting a valid approved join.
+         */
+        const resolveApprovedPrivateReplicaUnregisteredBinding = async (source) => {
+            if (options.allowApprovedPrivateReplicaFinalizedAbsence !== true)
+                return null;
+            const approved = this.localApprovedAgentByCG?.get(contextGraphId);
+            if (approved === undefined)
+                return null;
+            const metadataRevision = this.contextGraphMetaProjection
+                .readContextGraphAuthorityFactsRevision(contextGraphId);
+            let privateResolution = null;
+            try {
+                privateResolution = await runBoundedOperation((signal) => resolveApprovedPrivateReplicaAuthority(this, contextGraphId, approved, () => this.localApprovedAgentByCG.get(contextGraphId)?.toLowerCase()
+                    === approved.toLowerCase(), () => this.contextGraphMetaProjection
+                    .readContextGraphAuthorityFactsRevision(contextGraphId) === metadataRevision, signal), {
+                    label: `resolveApprovedPrivateReplicaAuthority(${contextGraphId})`,
+                    timeoutMs: chainAuthorityReadBudgetsOf(this).requestTimeoutMs,
+                    signal: options.signal,
+                });
+            }
+            catch (err) {
+                return {
+                    kind: 'unavailable',
+                    reason: 'finalized-name-absence-unaccepted',
+                    detail: err instanceof Error ? err.message : String(err),
+                    dependency: contextGraphReadAuthorityDependencyOf(err),
+                };
+            }
+            if (privateResolution === null) {
+                // Approval removal while the proof was in flight restores ordinary
+                // legacy behaviour. A still-present marker with no matching proof is
+                // an authority failure and must not fall through to merged metadata.
+                return this.localApprovedAgentByCG.has(contextGraphId)
+                    ? {
+                        kind: 'unavailable',
+                        reason: 'finalized-name-absence-unaccepted',
+                        detail: 'local private join approval has no current source-qualified replica proof',
+                    }
+                    : null;
+            }
+            options.signal?.throwIfAborted();
+            // Registration can start while either store-backed proof is in flight.
+            // Never publish unregistered authority or the legacy registered-metadata
+            // compatibility result across that boundary.
+            const bindingId = localTarget?.localId ?? contextGraphId;
+            if (this.contextGraphRegistrationsInFlight?.has(contextGraphId)
+                || this.contextGraphBindingState.hasBindingCandidate(bindingId, this.subscribedContextGraphs.get(bindingId))) {
+                return {
+                    kind: 'unavailable',
+                    reason: 'finalized-name-absence-unaccepted',
+                    detail: 'Context Graph binding changed during private replica registration discovery',
+                };
+            }
+            if (privateResolution.kind === 'confirmed-registered-meta') {
+                return source === 'legacy-current'
+                    ? {
+                        kind: 'unregistered',
+                        approvedPrivateReplicaAuthority: privateResolution.authority,
+                    }
+                    : {
+                        kind: 'unavailable',
+                        reason: 'finalized-name-absence-unaccepted',
+                        detail: 'exact private metadata claims a registered Context Graph; finalized absence cannot authorize it as an unregistered replica',
+                    };
+            }
+            const privateAuthority = privateResolution.authority;
+            return {
+                kind: 'unregistered',
+                // The legacy adapter lane permits participant reads, but cannot prove
+                // chain absence. Only the finalized lane may exempt VM catch-up.
+                ...(source === 'legacy-current' ? {} : {
+                    unregisteredEvidence: 'approved-private-replica-finalized-absence',
+                }),
+                approvedPrivateReplicaAuthority: privateAuthority,
+            };
+        };
+        const resolveLegacyUnregisteredBinding = async () => {
+            // An accepted owner policy remains stronger than participant-only
+            // authority. Its caller rechecks policy activation after this await.
+            if (options.allowAcceptedRfc64FinalizedAbsence === true) {
+                return { kind: 'unregistered' };
+            }
+            return (await resolveApprovedPrivateReplicaUnregisteredBinding('legacy-current'))
+                ?? { kind: 'unregistered' };
+        };
         // A durable numeric binding is already authoritative and must stay on the
         // zero-RPC fast path. Invalid durable values may be repaired only by the
         // finalized name index below; they bypass every local/ontology/legacy
@@ -597,19 +639,24 @@ export class ContextGraphRegistryMethods extends DKGAgentBase {
                         timeoutMs: registrationResolutionTimeoutMs,
                         signal: options.signal,
                     });
-                    if (binding === null)
-                        return { kind: 'unregistered' };
-                    return {
-                        kind: 'registered',
-                        onChainId: BigInt(binding.onChainId),
-                        provenance: binding.provenance,
-                    };
+                    if (binding !== null) {
+                        return {
+                            kind: 'registered',
+                            onChainId: BigInt(binding.onChainId),
+                            provenance: binding.provenance,
+                        };
+                    }
+                    // A retained local row without an admitted binding is not proof
+                    // that a graph is unregistered. Continue to the finalized capability
+                    // discriminator below; only its explicit legacy-current result may
+                    // reach the compatibility lane.
                 }
                 catch (err) {
                     return {
                         kind: 'unavailable',
                         reason: 'local-chain-binding-unavailable',
                         detail: err instanceof Error ? err.message : String(err),
+                        dependency: contextGraphReadAuthorityDependencyOf(err),
                     };
                 }
             }
@@ -688,32 +735,31 @@ export class ContextGraphRegistryMethods extends DKGAgentBase {
                                 }]]),
                     }
                     : undefined;
-                const flightKey = repairHints === undefined
-                    ? `registration-binding:${contextGraphId}`
-                    : `registration-binding-repair:${contextGraphId}:${durableBinding?.onChainId ?? ''}:${durableBinding?.onChainHash ?? ''}`;
-                const resolution = await finalizedAuthorityColdResolutionOf(this).read(flightKey, async (flightSignal) => {
-                    try {
-                        return await this.rfc64AuthorityReadCoordinatorV1.runForeground(flightSignal, (readSignal, evidence) => this.resolveFinalizedContextGraphAuthorityTargetsV1([contextGraphId], {
-                            ...evidence.agentResolverReadOptions(readSignal),
-                            ...repairHints,
-                        }));
-                    }
-                    finally {
-                        // The index reader's drain is global — one activity set shared with
-                        // the bulk catalog lane — so it must run OUTSIDE the foreground
-                        // permit: holding the permit across it would make every sibling
-                        // registration read wait on unrelated bulk index activity inside
-                        // this boundary's policy-read budget. It stays inside the flight,
-                        // so a detached resolution retires only once its physical index
-                        // work has settled.
-                        await indexReader.whenIdle();
-                    }
-                }, {
+                // Keep graph IDs, repair hints and freshness distinct even with delimiters.
+                const flightKey = JSON.stringify([
+                    'registration-binding', contextGraphId, options.freshness ?? 'live',
+                    repairHints === undefined ? null : [durableBinding?.onChainId ?? null, durableBinding?.onChainHash ?? null],
+                ]);
+                const coldResolution = finalizedAuthorityColdResolutionOf(this);
+                // Eligible readers may use retained evidence during cooldown, but a
+                // cache miss must defer; only normal circuit admission may reach RPC.
+                const mayServeAcceptedUnregisteredProjection = options.allowAcceptedRfc64FinalizedAbsence === true
+                    || (options.allowApprovedPrivateReplicaFinalizedAbsence === true
+                        && this.localApprovedAgentByCG?.has(contextGraphId) === true);
+                const resolution = await coldResolution.read(flightKey, (flightSignal) => this.rfc64AuthorityReadCoordinatorV1.runForeground(flightSignal, (readSignal, evidence) => this.resolveFinalizedContextGraphAuthorityTargetsV1([contextGraphId], {
+                    ...evidence.agentResolverReadOptions(readSignal),
+                    ...(options.freshness === undefined
+                        ? {}
+                        : { freshness: options.freshness }),
+                    ...repairHints,
+                }), mayServeAcceptedUnregisteredProjection
+                    ? { retainedFallback: (signal) => peekFinalizedTargets(finalizedTargetPlan(this, this.contextGraphBindingState.authorityIndexOnChainIdFor.bind(this.contextGraphBindingState), [contextGraphId], repairHints?.durableBindingHints), this.chain.contextGraphAuthorityIndexRevisionReader, { signal, ...(options.freshness === undefined ? {} : { freshness: options.freshness }) }) }
+                    : undefined), {
                     label: `resolveFinalizedContextGraphRegistrationBinding(${contextGraphId})`,
                     requestTimeoutMs: registrationResolutionTimeoutMs,
                     signal: options.signal,
                 });
-                const finalizedBinding = (() => {
+                const finalizedBinding = await (async () => {
                     // An older reader object without any finalized name capability is
                     // an explicitly legacy adapter and may use the compatibility path.
                     if (resolution.kind === 'legacy-current') {
@@ -724,14 +770,32 @@ export class ContextGraphRegistryMethods extends DKGAgentBase {
                     }
                     const target = resolution.targets.get(contextGraphId);
                     if (target === undefined) {
-                        return !strictFinalizedDurableBindingRepair
-                            && options.allowAcceptedRfc64FinalizedAbsence === true
-                            ? { kind: 'unregistered' }
-                            : {
-                                kind: 'unavailable',
-                                reason: 'finalized-name-absence-unaccepted',
-                                detail: 'finalized name absence has no accepted owner-signed unregistered authority',
+                        // An already accepted owner policy is stronger and may be public
+                        // or carry a wider signed private roster. Preserve that canonical
+                        // path instead of masking it with this receiver's local approval.
+                        if (!strictFinalizedDurableBindingRepair
+                            && options.allowAcceptedRfc64FinalizedAbsence === true) {
+                            return {
+                                kind: 'unregistered',
+                                unregisteredEvidence: 'accepted-rfc64-finalized-absence',
                             };
+                        }
+                        // A locally approved private replica may use exact finalized name
+                        // absence only while its current approval, metadata, membership,
+                        // and receiver delegation all still validate. This is participant
+                        // read/sync authority, not a generic accepted owner policy.
+                        if (!strictFinalizedDurableBindingRepair
+                            && !hasBindingCandidate
+                            && options.allowApprovedPrivateReplicaFinalizedAbsence === true) {
+                            const privateBinding = await resolveApprovedPrivateReplicaUnregisteredBinding('finalized-absence');
+                            if (privateBinding !== null)
+                                return privateBinding;
+                        }
+                        return {
+                            kind: 'unavailable',
+                            reason: 'finalized-name-absence-unaccepted',
+                            detail: 'finalized name absence has no accepted unregistered authority',
+                        };
                     }
                     if (target.expectedOnChainId <= 0n
                         || target.expectedOnChainId >= (1n << 256n)) {
@@ -786,7 +850,7 @@ export class ContextGraphRegistryMethods extends DKGAgentBase {
                     signal: options.signal,
                 });
                 if (binding === null)
-                    return { kind: 'unregistered' };
+                    return resolveLegacyUnregisteredBinding();
                 return {
                     kind: 'registered',
                     onChainId: BigInt(binding.onChainId),
@@ -798,12 +862,13 @@ export class ContextGraphRegistryMethods extends DKGAgentBase {
                     kind: 'unavailable',
                     reason: 'local-chain-binding-unavailable',
                     detail: err instanceof Error ? err.message : String(err),
+                    dependency: contextGraphReadAuthorityDependencyOf(err),
                 };
             }
         }
         const resolveByNameHash = this.chain.resolveContextGraphIdByNameHash;
         if (typeof resolveByNameHash !== 'function')
-            return { kind: 'unregistered' };
+            return resolveLegacyUnregisteredBinding();
         try {
             const nameHash = this.contextGraphNameCommitment(contextGraphId);
             const onChainId = await runBoundedOperation((signal) => resolveByNameHash.call(this.chain, nameHash, { signal }), {
@@ -812,7 +877,7 @@ export class ContextGraphRegistryMethods extends DKGAgentBase {
                 signal: options.signal,
             });
             return onChainId === null || onChainId <= 0n
-                ? { kind: 'unregistered' }
+                ? resolveLegacyUnregisteredBinding()
                 : { kind: 'registered', onChainId, provenance: 'name-hash' };
         }
         catch (err) {
@@ -834,20 +899,73 @@ export class ContextGraphRegistryMethods extends DKGAgentBase {
         if (currentBinding !== undefined)
             return currentBinding;
         // The durable RDF binding: ontology for a public graph, the graph's own
-        // `_meta` for a curated one (reported with the same provenance).
-        const result = await this.store.query(contextGraphOnChainIdBindingQuery(contextGraphId), {
+        // `_meta` for a curated one (reported with the same provenance). Both are
+        // claims (see context-graph-claim-proof.ts), and a subject can carry any
+        // number of them, so ask only for the ones this chain proves: no other
+        // claim can then push the proven one out of the answer. With none proven
+        // the list is empty and matches nothing, but the store is still read, so
+        // a failing store fails closed instead of reading as an unregistered graph.
+        const result = await this.store.query(contextGraphOnChainIdBindingQuery(contextGraphId, { onChainIds: this.provenOnChainIdsFor(contextGraphId) }), {
             signal: options.signal,
             source: options.source ?? 'agent.contextGraph.onChainId',
         });
-        if (result.type !== 'bindings' || result.bindings.length === 0)
-            return null;
-        const value = result.bindings[0]?.['id'];
-        if (typeof value !== 'string')
+        if (result.type !== 'bindings')
             return null;
-        const onChainId = value.replace(/^"|"$/g, '');
-        return isCanonicalAuthoritativeContextGraphId(onChainId)
-            ? { onChainId, provenance: 'ontology' }
-            : null;
+        for (const binding of result.bindings) {
+            const value = binding['id'];
+            if (typeof value !== 'string')
+                continue;
+            const proven = this.provenOnChainContextGraphClaim(contextGraphId, value.replace(/^"|"$/g, ''));
+            if (proven !== null)
+                return { onChainId: proven.onChainId, provenance: 'ontology' };
+        }
+        return null;
+    }
+    /**
+     * The on-chain ids this node's chain facts prove for `contextGraphId`
+     * (`provenOnChainIdsFor` in context-graph-claim-proof.ts).
+     */
+    provenOnChainIdsFor(contextGraphId) {
+        // Shared read paths also run on the partial agents unit fixtures build,
+        // which have no facts map.
+        const facts = this.onChainContextGraphFacts;
+        if (facts === undefined || facts.size === 0)
+            return [];
+        return provenOnChainIdsFor(contextGraphId, facts, (localId) => this.isWireIdKeyedSubscription(localId));
+    }
+    /**
+     * The binding an off-chain claim names, when this node's own chain proves
+     * it; otherwise null (`proveOnChainIdClaim` in context-graph-claim-proof.ts,
+     * against the name hash this node read for the claimed slot). No RPC is
+     * spent: a slot this node has no facts for proves nothing.
+     */
+    provenOnChainContextGraphClaim(contextGraphId, claimedOnChainId) {
+        return proveOnChainIdClaim(contextGraphId, claimedOnChainId, 
+        // `?.`: partial agents built by unit fixtures have no facts map.
+        this.onChainContextGraphFacts?.get(claimedOnChainId)?.nameHash, (localId) => this.isWireIdKeyedSubscription(localId));
+    }
+    /**
+     * Clear every binding to `onChainId` that this chain refutes, now that the
+     * slot's committed name hash is known (`refutesOnChainBinding` in
+     * context-graph-claim-proof.ts decides, from the hash passed in). Returns
+     * the ids it unbound.
+     *
+     * Store discovery used to bind every ontology claim unchecked, and a Core
+     * auto-subscribes what it discovers and persists the binding, so upgraded
+     * nodes restore other networks' graphs under this chain's ids. Such a
+     * binding can only fail: RFC-64 rejects its evidence as an invalid
+     * identity, a reverse lookup of the id can return it instead of the graph
+     * the slot names, and every authority read of it fails closed as a stale
+     * mapping.
+     */
+    clearRefutedOnChainContextGraphBindings(onChainId, committedNameHash) {
+        const isWireIdKeyedRow = (localId) => this.isWireIdKeyedSubscription(localId);
+        const refuted = [...this.subscribedContextGraphs]
+            .filter(([localId, row]) => refutesOnChainBinding(localId, row, onChainId, committedNameHash, isWireIdKeyedRow))
+            .map(([localId]) => localId);
+        for (const localId of refuted)
+            this.unbindSubscriptionOnChainId(localId);
+        return refuted;
     }
     /**
      * Resolve whether the TARGET context graph on a StorageACK requires curated
@@ -945,6 +1063,26 @@ export class ContextGraphRegistryMethods extends DKGAgentBase {
      */
     async getContextGraphOnChainPolicy(contextGraphId, options) {
         const signal = options?.signal;
+        // With a finalized authority index, a named graph's id comes only from the
+        // finalized registration binding. The current-state binding falls back to
+        // a live registry range scan, which a member of a graph that was never
+        // registered paid twice on every share: minutes on a public chain (#2827
+        // follow-up). A legacy adapter and a numeric id keep that binding. Either
+        // way the id is looked up at most once per call.
+        let onChainIdLookup;
+        const resolveOnChainId = () => {
+            onChainIdLookup ??= (async () => {
+                if (this.chain?.contextGraphAuthorityIndexRevisionReader === undefined
+                    || typeof this.resolveContextGraphRegistrationBinding !== 'function'
+                    || isCanonicalPositiveContextGraphId(contextGraphId)) {
+                    return this.getContextGraphOnChainId(contextGraphId, { signal }).catch(() => null);
+                }
+                const binding = await this.resolveContextGraphRegistrationBinding(contextGraphId, { signal })
+                    .catch(() => null);
+                return binding?.kind === 'registered' ? binding.onChainId.toString() : null;
+            })();
+            return onChainIdLookup;
+        };
         // Keep the explicitly-created local-first state off the registry lookup
         // path. The registration guard below used to run only after the cache
         // re-key step had already called `getContextGraphOnChainId()` (twice on a
@@ -999,7 +1137,7 @@ export class ContextGraphRegistryMethods extends DKGAgentBase {
         let onChainId;
         if (accessPolicy === undefined || publishPolicy === undefined) {
             onChainId = this.subscribedContextGraphs.get(contextGraphId)?.onChainId
-                ?? (await this.getContextGraphOnChainId(contextGraphId, { signal }).catch(() => null))
+                ?? (await resolveOnChainId())
                 ?? undefined;
             if (onChainId && onChainId !== contextGraphId) {
                 if (accessPolicy === undefined)
@@ -1043,7 +1181,7 @@ export class ContextGraphRegistryMethods extends DKGAgentBase {
             if (!registeredViaStatus) {
                 if (onChainId === undefined) {
                     onChainId = this.subscribedContextGraphs.get(contextGraphId)?.onChainId
-                        ?? (await this.getContextGraphOnChainId(contextGraphId, { signal }).catch(() => null))
+                        ?? (await resolveOnChainId())
                         ?? undefined;
                 }
                 if (onChainId) {
@@ -1090,7 +1228,7 @@ export class ContextGraphRegistryMethods extends DKGAgentBase {
             && this.chain) {
             if (onChainId === undefined) {
                 onChainId = this.subscribedContextGraphs.get(contextGraphId)?.onChainId
-                    ?? (await this.getContextGraphOnChainId(contextGraphId, { signal }).catch(() => null))
+                    ?? (await resolveOnChainId())
                     ?? undefined;
             }
             let numericId;