@origintrail-official/dkg-agent 10.0.19 → 10.0.21

package/dist/vm-refresh.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Refresh of confirmed Verifiable Memory copies after a Knowledge Asset update.
+ *
+ * An update keeps the KA id and moves its latest on-chain root. The ordinal
+ * sweep never revisits a settled ordinal, so a node whose only copy is a
+ * confirmed VM copy (a member of a catalog graph, a core outside the update's
+ * ACK set) has no other lane that brings the new version. The live
+ * `KnowledgeAssetUpdated` nudge records one target per holding graph; a
+ * refresh worker the graph's reconcile pass starts works the targets off,
+ * reading the chain before it fetches anything.
+ *
+ * This module owns only the bounded, process-local target set and its retry
+ * schedule. A target is a hint: every attempt re-derives the decision from the
+ * local copy and the chain, so a stale target costs at most a chain read,
+ * never a wrong version.
+ *
+ * The update event is the durable record. The event lane never persists its
+ * cursor past the oldest held target's block ({@link VmRefreshQueue.oldestBlockNumber}),
+ * so after a restart it replays every event whose target was not settled, and
+ * the nudge records the target again. A full set refuses a new target, which
+ * fails the event's dispatch, so the lane holds and dispatches it again later.
+ * A target held past its maximum age is given up
+ * ({@link VmRefreshQueue.expire}): it releases its slot and the lane's cursor,
+ * and the copy waits for the KA's next update or an explicit asset fetch.
+ */
+export interface VmRefreshTarget {
+    readonly localCgId: string;
+    readonly ual: string;
+    readonly kaId: bigint;
+    /** Root the update event announced, 0x-prefixed lowercase hex. */
+    readonly merkleRoot: string;
+    /**
+     * Block of the update event, when known. A chain view older than it has
+     * not seen the update, so it can never settle the target as current. Only
+     * targets with a block hold the event lane's persisted cursor.
+     */
+    readonly blockNumber?: number;
+    /** Hash of the event's block, to distinguish a replacement fork. */
+    readonly blockHash?: string;
+    /** Position within the block, so two updates with the same root remain distinct. */
+    readonly logIndex?: number;
+    /** Transaction identity when a log position is unavailable or a block reorganizes. */
+    readonly txHash?: string;
+    /** Required chain-view height when an unseen event arrives behind a held one. */
+    readonly proofBlockNumber?: number;
+    /**
+     * The copy already holds the announced root. Roots name content, not
+     * versions, so an update that repeats content (or an A -> B -> A history)
+     * can leave the copy at an older version with the same root; the attempt
+     * then compares versions with the chain instead of settling on the root.
+     */
+    readonly checkVersion?: boolean;
+}
+/** A due target with the failed attempts before it. */
+export interface VmRefreshDue extends VmRefreshTarget {
+    readonly failures: number;
+}
+/**
+ * What one attempt concluded.
+ *  - `current`: the local copy already holds the chain's current version.
+ *  - `refreshed`: the current version was fetched and materialized.
+ *  - `not-applicable`: nothing for this lane to do (no confirmed copy any
+ *    more, or a chain adapter that cannot read or prove the current version).
+ *  - `retry`: the chain or the network could not settle it; try again later.
+ */
+export type VmRefreshOutcome = 'current' | 'refreshed' | 'not-applicable' | 'retry';
+/** One attempt's outcome and what decided it, for the lane's log line. */
+export interface VmRefreshAttempt {
+    readonly outcome: VmRefreshOutcome;
+    readonly detail: string;
+}
+/**
+ * What an offer did: recorded a new update, kept the already held event (and
+ * its retry schedule), or refused it because the set is full.
+ */
+export type VmRefreshOfferResult = 'recorded' | 'held' | 'full';
+/** A target given up at its maximum age, with the failed attempts behind it. */
+export interface VmRefreshGivenUp extends VmRefreshTarget {
+    readonly failures: number;
+    readonly heldMs: number;
+}
+export interface VmRefreshQueueOptions {
+    /** Upper bound on targets held across all graphs; a full set refuses new ones. */
+    readonly maxEntries: number;
+    /** Delay before the first retry; doubles per failure. */
+    readonly baseBackoffMs: number;
+    /** Ceiling of the retry delay. */
+    readonly maxBackoffMs: number;
+    /** Age, from its first offer, at which a target that never settled is given up. */
+    readonly maxAgeMs: number;
+    readonly now?: () => number;
+}
+export declare class VmRefreshQueue {
+    #private;
+    constructor(options: VmRefreshQueueOptions);
+    get size(): number;
+    /** Offers refused because the set was full, since this queue was made. */
+    get refusedTotal(): number;
+    /** Targets given up at their maximum age, since this queue was made. */
+    get givenUpTotal(): number;
+    /**
+     * Record a target, due after `delayMs`. A replay of a held or superseded
+     * update keeps the current retry schedule. An unseen update replaces it,
+     * even at a lower position: that event could be from a replacement fork.
+     * A same-root or lower-position replacement must check the chain version.
+     */
+    offer(target: VmRefreshTarget, delayMs?: number): VmRefreshOfferResult;
+    /** Due targets of one graph, oldest first, at most `limit`. */
+    due(localCgId: string, limit: number): VmRefreshDue[];
+    hasDue(localCgId: string): boolean;
+    /** Graphs with at least one due target, in the order of their oldest one. */
+    dueContextGraphIds(): string[];
+    /**
+     * Lowest event block of the held targets that carry one: the event lane
+     * must replay from it after a restart. Undefined when none is held.
+     */
+    oldestBlockNumber(): number | undefined;
+    /**
+     * Settle one attempt. Only the exact target that was attempted is settled:
+     * a newer event recorded while the attempt ran stays queued and due.
+     * Returns when a retried target is due again.
+     */
+    settle(target: VmRefreshTarget, outcome: VmRefreshOutcome): number | undefined;
+    /**
+     * Give up every target held for `maxAgeMs` or longer since its first offer,
+     * whether it kept failing or was never attempted (a graph whose pass no
+     * longer runs). Returns the targets given up.
+     */
+    expire(): VmRefreshGivenUp[];
+    clearContextGraph(localCgId: string): void;
+    clear(): void;
+    /** Every held target with its retry state, oldest first. */
+    snapshot(): ReadonlyArray<VmRefreshTarget & {
+        failures: number;
+        nextAttemptAt: number;
+    }>;
+}
+//# sourceMappingURL=vm-refresh.d.ts.map

package/dist/vm-refresh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vm-refresh.d.ts","sourceRoot":"","sources":["../src/vm-refresh.ts"],"names":[],"mappings":"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"}

package/dist/vm-refresh.js

@@ -0,0 +1,201 @@
+// SPDX-License-Identifier: Apache-2.0
+function recordKey(localCgId, ual) {
+    return `${localCgId}\0${ual}`;
+}
+function updateKey(target) {
+    // Complete positions remain distinct, including across forks. Legacy
+    // adapters without a position can only coalesce the evidence they supply.
+    if (target.blockNumber === undefined)
+        return JSON.stringify(['legacy', target.merkleRoot]);
+    if (target.logIndex !== undefined) {
+        return JSON.stringify([
+            'log', target.blockNumber, target.logIndex, target.blockHash,
+            target.txHash, target.merkleRoot,
+        ]);
+    }
+    if (target.txHash !== undefined) {
+        return JSON.stringify([
+            'transaction', target.blockNumber, target.blockHash, target.txHash, target.merkleRoot,
+        ]);
+    }
+    return JSON.stringify(['legacy-block', target.blockNumber, target.merkleRoot]);
+}
+function behindHeld(incoming, held) {
+    if (incoming.blockNumber === undefined || held.blockNumber === undefined)
+        return false;
+    if (incoming.blockNumber !== held.blockNumber)
+        return incoming.blockNumber < held.blockNumber;
+    return incoming.logIndex !== undefined && held.logIndex !== undefined
+        && incoming.logIndex < held.logIndex;
+}
+export class VmRefreshQueue {
+    #records = new Map();
+    #maxEntries;
+    #baseBackoffMs;
+    #maxBackoffMs;
+    #maxAgeMs;
+    #now;
+    #refusedTotal = 0;
+    #givenUpTotal = 0;
+    constructor(options) {
+        this.#maxEntries = Math.max(1, Math.floor(options.maxEntries));
+        this.#baseBackoffMs = Math.max(0, options.baseBackoffMs);
+        this.#maxBackoffMs = Math.max(this.#baseBackoffMs, options.maxBackoffMs);
+        this.#maxAgeMs = Math.max(0, options.maxAgeMs);
+        this.#now = options.now ?? (() => Date.now());
+    }
+    get size() {
+        return this.#records.size;
+    }
+    /** Offers refused because the set was full, since this queue was made. */
+    get refusedTotal() {
+        return this.#refusedTotal;
+    }
+    /** Targets given up at their maximum age, since this queue was made. */
+    get givenUpTotal() {
+        return this.#givenUpTotal;
+    }
+    /**
+     * Record a target, due after `delayMs`. A replay of a held or superseded
+     * update keeps the current retry schedule. An unseen update replaces it,
+     * even at a lower position: that event could be from a replacement fork.
+     * A same-root or lower-position replacement must check the chain version.
+     */
+    offer(target, delayMs = 0) {
+        const key = recordKey(target.localCgId, target.ual);
+        const held = this.#records.get(key);
+        const keyOfUpdate = updateKey(target);
+        if (held !== undefined
+            && (updateKey(held.target) === keyOfUpdate || held.seenUpdateKeys.has(keyOfUpdate))) {
+            return 'held';
+        }
+        if (held === undefined && this.#records.size >= this.#maxEntries) {
+            this.#refusedTotal += 1;
+            return 'full';
+        }
+        const seenUpdateKeys = new Set(held?.seenUpdateKeys);
+        if (held !== undefined)
+            seenUpdateKeys.add(updateKey(held.target));
+        // The queue is bounded, and so is the replay memory for a busy KA.
+        if (seenUpdateKeys.size > 128)
+            seenUpdateKeys.delete(seenUpdateKeys.values().next().value);
+        const behind = held !== undefined && behindHeld(target, held.target);
+        const previousProof = held?.target.proofBlockNumber ?? held?.target.blockNumber;
+        const incomingProof = target.proofBlockNumber ?? target.blockNumber;
+        const proofBlockNumber = previousProof === undefined ? incomingProof
+            : incomingProof === undefined ? previousProof
+                : Math.max(previousProof, incomingProof);
+        this.#records.delete(key);
+        const now = this.#now();
+        this.#records.set(key, {
+            target: Object.freeze({
+                ...target,
+                ...(held?.target.merkleRoot === target.merkleRoot || behind ? { checkVersion: true } : {}),
+                ...(proofBlockNumber !== undefined && proofBlockNumber !== target.blockNumber
+                    ? { proofBlockNumber } : {}),
+            }),
+            firstOfferedAt: now,
+            seenUpdateKeys,
+            failures: 0,
+            nextAttemptAt: delayMs > 0 ? now + delayMs : 0,
+        });
+        return 'recorded';
+    }
+    /** Due targets of one graph, oldest first, at most `limit`. */
+    due(localCgId, limit) {
+        const now = this.#now();
+        const out = [];
+        for (const record of this.#records.values()) {
+            if (out.length >= limit)
+                break;
+            if (record.target.localCgId !== localCgId || record.nextAttemptAt > now)
+                continue;
+            out.push(Object.freeze({ ...record.target, failures: record.failures }));
+        }
+        return out;
+    }
+    hasDue(localCgId) {
+        return this.due(localCgId, 1).length > 0;
+    }
+    /** Graphs with at least one due target, in the order of their oldest one. */
+    dueContextGraphIds() {
+        const now = this.#now();
+        const out = new Set();
+        for (const record of this.#records.values()) {
+            if (record.nextAttemptAt <= now)
+                out.add(record.target.localCgId);
+        }
+        return [...out];
+    }
+    /**
+     * Lowest event block of the held targets that carry one: the event lane
+     * must replay from it after a restart. Undefined when none is held.
+     */
+    oldestBlockNumber() {
+        let oldest;
+        for (const record of this.#records.values()) {
+            const block = record.target.blockNumber;
+            if (block === undefined)
+                continue;
+            if (oldest === undefined || block < oldest)
+                oldest = block;
+        }
+        return oldest;
+    }
+    /**
+     * Settle one attempt. Only the exact target that was attempted is settled:
+     * a newer event recorded while the attempt ran stays queued and due.
+     * Returns when a retried target is due again.
+     */
+    settle(target, outcome) {
+        const key = recordKey(target.localCgId, target.ual);
+        const held = this.#records.get(key);
+        if (held === undefined || updateKey(held.target) !== updateKey(target))
+            return undefined;
+        if (outcome !== 'retry') {
+            this.#records.delete(key);
+            return undefined;
+        }
+        held.failures += 1;
+        const exponent = Math.min(held.failures - 1, 16);
+        held.nextAttemptAt = this.#now()
+            + Math.min(this.#maxBackoffMs, this.#baseBackoffMs * 2 ** exponent);
+        return held.nextAttemptAt;
+    }
+    /**
+     * Give up every target held for `maxAgeMs` or longer since its first offer,
+     * whether it kept failing or was never attempted (a graph whose pass no
+     * longer runs). Returns the targets given up.
+     */
+    expire() {
+        const now = this.#now();
+        const out = [];
+        for (const [key, record] of this.#records) {
+            const heldMs = now - record.firstOfferedAt;
+            if (heldMs < this.#maxAgeMs)
+                continue;
+            this.#records.delete(key);
+            this.#givenUpTotal += 1;
+            out.push(Object.freeze({ ...record.target, failures: record.failures, heldMs }));
+        }
+        return out;
+    }
+    clearContextGraph(localCgId) {
+        for (const [key, record] of this.#records) {
+            if (record.target.localCgId === localCgId)
+                this.#records.delete(key);
+        }
+    }
+    clear() {
+        this.#records.clear();
+    }
+    /** Every held target with its retry state, oldest first. */
+    snapshot() {
+        return [...this.#records.values()].map((record) => Object.freeze({
+            ...record.target,
+            failures: record.failures,
+            nextAttemptAt: record.nextAttemptAt,
+        }));
+    }
+}
+//# sourceMappingURL=vm-refresh.js.map

package/dist/vm-refresh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vm-refresh.js","sourceRoot":"","sources":["../src/vm-refresh.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@origintrail-official/dkg-agent",
-  "version": "10.0.19",
+  "version": "10.0.21",
   "type": "module",
   "engines": {
     "node": ">=22.13.0 <23.0.0 || >=23.4.0"
@@ -25,6 +25,7 @@
     },
     "./package.json": "./package.json",
     "./dist/internal/*": null,
+    "./dist/approved-private-replica.js": null,
     "./dist/random-sampling-runtime.js": null,
     "./dist/random-sampling-eligibility.js": null,
     "./dist/rfc64/author-catalog-producer.js": "./dist/rfc64/author-catalog-producer.js",
@@ -40,6 +41,8 @@
     "./dist/rfc64/swm-author-inventory-producer-v1.js": "./dist/rfc64/swm-author-inventory-producer-v1.js",
     "./dist/rfc64/swm-inventory-catalog-reconciler-v1.js": null,
     "./dist/rfc64/swm-catalog-durable-asset-resolver-v1.js": null,
+    "./dist/rfc64/catalog-repair-diagnostics-v1.js": null,
+    "./dist/rfc64/catalog-repair-retry-v1.js": null,
     "./dist/rfc64/abort-v1.js": null,
     "./dist/rfc64/catalog-mutation-runtime-v1.js": null,
     "./dist/rfc64/catalog-replay-connection-runtime-v1.js": null,
@@ -47,6 +50,10 @@
     "./dist/rfc64/catalog-replay-recovery-runtime-v1.js": null,
     "./dist/rfc64/catalog-replay-snapshot-runtime-v1.js": null,
     "./dist/rfc64/catalog-operational-applied-heads-v1.js": null,
+    "./dist/rfc64/catalog-operational-reads-v1.js": null,
+    "./dist/rfc64/catalog-completion-evidence-v1.js": null,
+    "./dist/rfc64/private-catalog-subscription-readiness-v1.js": null,
+    "./dist/rfc64/registered-private-empty-vm-proof-v1.js": null,
     "./dist/rfc64/catalog-runtime-v1.js": null,
     "./dist/rfc64/background-work-dispatcher-v1.js": null,
     "./dist/rfc64/supervisor-status-v1.js": null,
@@ -129,7 +136,10 @@
     "./dist/rfc64/swm-recovery-coordinator-v1.js": null,
     "./dist/rfc64/swm-recovery-plan-v1.js": null,
     "./dist/rfc64/*": null,
-    "./dist/*": "./dist/*"
+    "./dist/*": "./dist/*",
+    "./dist/rfc64/legacy-swm-boundary-codec-v1.js": null,
+    "./dist/rfc64/catalog-operational-targets-v1.js": null,
+    "./dist/rfc64/private-read-roster-v1.js": null
   },
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
@@ -141,13 +151,13 @@
     "ethers": "^6",
     "js-yaml": "^4.1.1",
     "jsonld": "^8.3.3",
-    "@origintrail-official/dkg-chain": "10.0.19",
-    "@origintrail-official/dkg-query": "10.0.19",
-    "@origintrail-official/dkg-publisher": "10.0.19",
-    "@origintrail-official/dkg-random-sampling": "10.0.19",
-    "@origintrail-official/dkg-rdf-utils": "10.0.19",
-    "@origintrail-official/dkg-core": "10.0.19",
-    "@origintrail-official/dkg-storage": "10.0.19"
+    "@origintrail-official/dkg-core": "10.0.21",
+    "@origintrail-official/dkg-publisher": "10.0.21",
+    "@origintrail-official/dkg-storage": "10.0.21",
+    "@origintrail-official/dkg-random-sampling": "10.0.21",
+    "@origintrail-official/dkg-chain": "10.0.21",
+    "@origintrail-official/dkg-query": "10.0.21",
+    "@origintrail-official/dkg-rdf-utils": "10.0.21"
   },
   "devDependencies": {
     "@libp2p/crypto": "^5.1.18",

package/dist/finalization-annotations.d.ts

@@ -1,5 +0,0 @@
-/** Agent-local cache annotations; they are not publisher protocol metadata. */
-export declare const SWM_SNAPSHOT_MERKLE_ROOT_PREDICATE = "http://dkg.io/ontology/snapshotMerkleRoot";
-export declare const SWM_SNAPSHOT_CONTENT_DIGEST_PREDICATE = "http://dkg.io/ontology/snapshotContentDigest";
-export declare const SWM_FINALIZATION_ANNOTATION_PREDICATES: ReadonlySet<string>;
-//# sourceMappingURL=finalization-annotations.d.ts.map

package/dist/finalization-annotations.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"finalization-annotations.d.ts","sourceRoot":"","sources":["../src/finalization-annotations.ts"],"names":[],"mappings":"AAMA,+EAA+E;AAC/E,eAAO,MAAM,kCAAkC,8CACF,CAAC;AAC9C,eAAO,MAAM,qCAAqC,iDACF,CAAC;AAEjD,eAAO,MAAM,sCAAsC,EAAE,WAAW,CAAC,MAAM,CAC7B,CAAC"}

package/dist/finalization-annotations.js

@@ -1,6 +0,0 @@
-import { ENTITY_SHARE_METADATA_SIDECAR_PREDICATES, ENTITY_SHARE_SNAPSHOT_CONTENT_DIGEST_PREDICATE, ENTITY_SHARE_SNAPSHOT_MERKLE_ROOT_PREDICATE, } from '@origintrail-official/dkg-publisher';
-/** Agent-local cache annotations; they are not publisher protocol metadata. */
-export const SWM_SNAPSHOT_MERKLE_ROOT_PREDICATE = ENTITY_SHARE_SNAPSHOT_MERKLE_ROOT_PREDICATE;
-export const SWM_SNAPSHOT_CONTENT_DIGEST_PREDICATE = ENTITY_SHARE_SNAPSHOT_CONTENT_DIGEST_PREDICATE;
-export const SWM_FINALIZATION_ANNOTATION_PREDICATES = ENTITY_SHARE_METADATA_SIDECAR_PREDICATES;
-//# sourceMappingURL=finalization-annotations.js.map

package/dist/finalization-annotations.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"finalization-annotations.js","sourceRoot":"","sources":["../src/finalization-annotations.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wCAAwC,EACxC,8CAA8C,EAC9C,2CAA2C,GAC5C,MAAM,qCAAqC,CAAC;AAE7C,+EAA+E;AAC/E,MAAM,CAAC,MAAM,kCAAkC,GAC7C,2CAA2C,CAAC;AAC9C,MAAM,CAAC,MAAM,qCAAqC,GAChD,8CAA8C,CAAC;AAEjD,MAAM,CAAC,MAAM,sCAAsC,GACjD,wCAAwC,CAAC"}

package/dist/swm-ka-bound.d.ts

@@ -1,21 +0,0 @@
-import type { SwmKaGraphBound } from '@origintrail-official/dkg-storage';
-/**
- * Derive the per-author SWM under-graph bound for the finalization gossip read
- * from a KA batch's packed `startKAId`/`endKAId` (#1549).
- *
- * `startKAId`/`endKAId` are packed `(author << 96) | number` (see
- * `packKnowledgeAssetIdFromIdentity`), whereas the SWM under-graph URI's last
- * segment is only the low-96 per-author number. We therefore unpack both ends and
- * bound on `(agentAddress, [startNumber, endNumber])`. A range whose two ends
- * unpack to DIFFERENT authors is not a contiguous per-author number range — the
- * low-96 numbers wrap independently of the high-160 address — so no single
- * `SwmKaGraphBound` can describe it and we return `undefined` (unbounded).
- *
- * PURE: identical inputs always yield an identical result, so this has no home in
- * the message handler. The ops kill-switch (`DKG_DISABLE_SWM_KA_BOUND`) is applied
- * by the finalization orchestration before calling this, not here. Returning
- * `undefined` is always safe: the caller widens to the unbounded read on
- * empty-or-mismatch before it defers.
- */
-export declare function deriveSwmKaGraphBound(startKAId: bigint, endKAId: bigint): SwmKaGraphBound | undefined;
-//# sourceMappingURL=swm-ka-bound.d.ts.map

package/dist/swm-ka-bound.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"swm-ka-bound.d.ts","sourceRoot":"","sources":["../src/swm-ka-bound.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAGzE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAarG"}

package/dist/swm-ka-bound.js

@@ -1,36 +0,0 @@
-import { unpackKnowledgeAssetId } from './ka-identity.js';
-/**
- * Derive the per-author SWM under-graph bound for the finalization gossip read
- * from a KA batch's packed `startKAId`/`endKAId` (#1549).
- *
- * `startKAId`/`endKAId` are packed `(author << 96) | number` (see
- * `packKnowledgeAssetIdFromIdentity`), whereas the SWM under-graph URI's last
- * segment is only the low-96 per-author number. We therefore unpack both ends and
- * bound on `(agentAddress, [startNumber, endNumber])`. A range whose two ends
- * unpack to DIFFERENT authors is not a contiguous per-author number range — the
- * low-96 numbers wrap independently of the high-160 address — so no single
- * `SwmKaGraphBound` can describe it and we return `undefined` (unbounded).
- *
- * PURE: identical inputs always yield an identical result, so this has no home in
- * the message handler. The ops kill-switch (`DKG_DISABLE_SWM_KA_BOUND`) is applied
- * by the finalization orchestration before calling this, not here. Returning
- * `undefined` is always safe: the caller widens to the unbounded read on
- * empty-or-mismatch before it defers.
- */
-export function deriveSwmKaGraphBound(startKAId, endKAId) {
-    if (startKAId <= 0n || endKAId < startKAId)
-        return undefined;
-    const start = unpackKnowledgeAssetId(startKAId);
-    const end = unpackKnowledgeAssetId(endKAId);
-    // Both sides come from `unpack`, which is already lowercase, so a plain compare
-    // suffices here. The graph-URI side is NOT — see the case-insensitive compare in
-    // storage's bounded resolver.
-    if (start.agentAddress !== end.agentAddress)
-        return undefined;
-    return {
-        agentAddress: start.agentAddress,
-        startNumber: start.kaNumber,
-        endNumber: end.kaNumber,
-    };
-}
-//# sourceMappingURL=swm-ka-bound.js.map

package/dist/swm-ka-bound.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"swm-ka-bound.js","sourceRoot":"","sources":["../src/swm-ka-bound.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAE1D;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,qBAAqB,CAAC,SAAiB,EAAE,OAAe;IACtE,IAAI,SAAS,IAAI,EAAE,IAAI,OAAO,GAAG,SAAS;QAAE,OAAO,SAAS,CAAC;IAC7D,MAAM,KAAK,GAAG,sBAAsB,CAAC,SAAS,CAAC,CAAC;IAChD,MAAM,GAAG,GAAG,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAC5C,gFAAgF;IAChF,iFAAiF;IACjF,8BAA8B;IAC9B,IAAI,KAAK,CAAC,YAAY,KAAK,GAAG,CAAC,YAAY;QAAE,OAAO,SAAS,CAAC;IAC9D,OAAO;QACL,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,WAAW,EAAE,KAAK,CAAC,QAAQ;QAC3B,SAAS,EAAE,GAAG,CAAC,QAAQ;KACxB,CAAC;AACJ,CAAC"}