@bsv/overlay 2.3.1 → 2.6.1

package/dist/cjs/src/RemoteSecurity.js

@@ -0,0 +1,301 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REMOTE_BODY_TIMEOUT_MS = exports.MAX_RAW_TRANSACTION_BYTES = exports.MAX_GASP_NODE_JSON_BYTES = exports.MAX_REMOTE_JSON_BYTES = exports.MAX_BASM_TXIDS = exports.MAX_GASP_PAGE_SIZE = void 0;
+exports.validateAdmittanceInstructions = validateAdmittanceInstructions;
+exports.assertTopic = assertTopic;
+exports.assertRegistryName = assertRegistryName;
+exports.assertHash = assertHash;
+exports.assertOutputIndex = assertOutputIndex;
+exports.assertNonnegativeInteger = assertNonnegativeInteger;
+exports.assertOutpoint = assertOutpoint;
+exports.assertHexBytes = assertHexBytes;
+exports.assertTxidList = assertTxidList;
+exports.normalizePeerEndpoint = normalizePeerEndpoint;
+exports.securePeerFetch = securePeerFetch;
+exports.readPeerJSON = readPeerJSON;
+exports.assertGASPInitialResponse = assertGASPInitialResponse;
+exports.assertGASPNode = assertGASPNode;
+exports.assertRawTransactionMatches = assertRawTransactionMatches;
+const sdk_1 = require("@bsv/sdk");
+exports.MAX_GASP_PAGE_SIZE = 10000;
+exports.MAX_BASM_TXIDS = 256;
+exports.MAX_REMOTE_JSON_BYTES = 64 * 1024 * 1024;
+exports.MAX_GASP_NODE_JSON_BYTES = 32 * 1024 * 1024;
+exports.MAX_RAW_TRANSACTION_BYTES = 32 * 1024 * 1024;
+exports.REMOTE_BODY_TIMEOUT_MS = 30000;
+const MAX_TOPIC_BYTES = 256;
+const MAX_METADATA_BYTES = 1024 * 1024;
+const MAX_GASP_INPUTS = 100000;
+const MAX_ERROR_SNIPPET_BYTES = 1024;
+const HASH_HEX = /^[0-9a-fA-F]{64}$/;
+const EVEN_HEX = /^(?:[0-9a-fA-F]{2})+$/;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function validateAdmittanceInstructions(value, tx, previousCoins) {
+    if (!isRecord(value) ||
+        !Array.isArray(value.outputsToAdmit) ||
+        !Array.isArray(value.coinsToRetain)) {
+        throw new TypeError('Topic manager returned invalid admittance instructions');
+    }
+    const validateIndexes = (indexes, limit, label) => {
+        const seen = new Set();
+        return indexes.map(index => {
+            if (typeof index !== 'number' ||
+                !Number.isSafeInteger(index) ||
+                index < 0 ||
+                index >= limit ||
+                seen.has(index)) {
+                throw new TypeError(`Topic manager returned invalid ${label}`);
+            }
+            seen.add(index);
+            return index;
+        });
+    };
+    const outputsToAdmit = validateIndexes(value.outputsToAdmit, tx.outputs.length, 'outputsToAdmit');
+    const coinsToRetain = validateIndexes(value.coinsToRetain, tx.inputs.length, 'coinsToRetain');
+    const previousCoinSet = new Set(previousCoins);
+    if (coinsToRetain.some(index => !previousCoinSet.has(index))) {
+        throw new TypeError('Topic manager retained an input that is not a previous topical coin');
+    }
+    return { outputsToAdmit, coinsToRetain };
+}
+function assertTopic(topic, label = 'topic') {
+    if (typeof topic !== 'string' ||
+        topic.length === 0 ||
+        new TextEncoder().encode(topic).byteLength > MAX_TOPIC_BYTES ||
+        Array.from(topic).some(character => {
+            var _a;
+            const codePoint = (_a = character.codePointAt(0)) !== null && _a !== void 0 ? _a : 0;
+            return codePoint <= 0x1f || codePoint === 0x7f;
+        })) {
+        throw new TypeError(`${label} is invalid`);
+    }
+}
+function assertRegistryName(value, label) {
+    assertTopic(value, label);
+    if (value === '__proto__' || value === 'prototype' || value === 'constructor') {
+        throw new TypeError(`${label} uses a reserved object property name`);
+    }
+}
+function assertHash(value, label) {
+    if (typeof value !== 'string' || !HASH_HEX.test(value)) {
+        throw new TypeError(`${label} must be 32 bytes of hex`);
+    }
+}
+function assertOutputIndex(value, label) {
+    if (!Number.isSafeInteger(value) || value < 0 || value > 0xffffffff) {
+        throw new TypeError(`${label} must be an unsigned 32-bit integer`);
+    }
+}
+function assertNonnegativeInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new TypeError(`${label} must be a non-negative safe integer`);
+    }
+}
+function assertOutpoint(value, label) {
+    if (typeof value !== 'string')
+        throw new TypeError(`${label} is invalid`);
+    const separator = value.lastIndexOf('.');
+    if (separator !== 64)
+        throw new TypeError(`${label} is invalid`);
+    assertHash(value.slice(0, separator), `${label} txid`);
+    const index = value.slice(separator + 1);
+    if (!/^(0|[1-9]\d*)$/.test(index))
+        throw new TypeError(`${label} is invalid`);
+    assertOutputIndex(Number(index), `${label} output index`);
+}
+function assertHexBytes(value, label, maxBytes, allowEmpty = false) {
+    if (typeof value !== 'string' ||
+        (!allowEmpty && value.length === 0) ||
+        value.length > maxBytes * 2 ||
+        (value.length !== 0 && !EVEN_HEX.test(value))) {
+        throw new TypeError(`${label} must be bounded, even-length hexadecimal data`);
+    }
+}
+function assertTxidList(value, label, options = {}) {
+    var _a;
+    const max = (_a = options.max) !== null && _a !== void 0 ? _a : exports.MAX_BASM_TXIDS;
+    if (!Array.isArray(value) || (!options.allowEmpty && value.length === 0) || value.length > max) {
+        throw new TypeError(`${label} must contain between ${options.allowEmpty === true ? 0 : 1} and ${max} txids`);
+    }
+    const seen = new Set();
+    for (const [index, txid] of value.entries()) {
+        assertHash(txid, `${label}[${index}]`);
+        const canonical = txid.toLowerCase();
+        if (seen.has(canonical))
+            throw new TypeError(`${label} contains duplicate txids`);
+        seen.add(canonical);
+    }
+}
+function normalizePeerEndpoint(endpoint) {
+    const url = new URL(endpoint);
+    if (url.protocol !== 'https:' ||
+        url.username !== '' ||
+        url.password !== '' ||
+        url.hash !== '' ||
+        url.search !== '') {
+        throw new TypeError('Overlay peer endpoints must be credential-free HTTPS URLs without query or fragment data');
+    }
+    return url.toString().replace(/\/$/, '');
+}
+function securePeerFetch(endpoint, supplied) {
+    const normalized = normalizePeerEndpoint(endpoint);
+    return {
+        endpoint: normalized,
+        fetchImpl: supplied !== null && supplied !== void 0 ? supplied : (0, sdk_1.createPublicHTTPSFetch)(new URL(normalized).origin)
+    };
+}
+async function readBody(response, maxBytes, truncate = false) {
+    var _a, _b, _c;
+    const declared = (_b = (_a = response.headers) === null || _a === void 0 ? void 0 : _a.get) === null || _b === void 0 ? void 0 : _b.call(_a, 'content-length');
+    if (declared !== null && declared !== undefined) {
+        if (!truncate && (!/^(0|[1-9]\d*)$/.test(declared) || Number(declared) > maxBytes)) {
+            await ((_c = response.body) === null || _c === void 0 ? void 0 : _c.cancel());
+            throw new RangeError(`Overlay peer response exceeds ${maxBytes} bytes`);
+        }
+    }
+    if (response.body === null || response.body === undefined) {
+        const text = await response.text();
+        if (new TextEncoder().encode(text).byteLength > maxBytes) {
+            throw new RangeError(`Overlay peer response exceeds ${maxBytes} bytes`);
+        }
+        return text;
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    let timeout;
+    try {
+        const bytes = await Promise.race([
+            (async () => {
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    if (truncate && total + value.byteLength > maxBytes) {
+                        chunks.push(value.slice(0, maxBytes - total));
+                        total = maxBytes;
+                        break;
+                    }
+                    total += value.byteLength;
+                    if (total > maxBytes) {
+                        throw new RangeError(`Overlay peer response exceeds ${maxBytes} bytes`);
+                    }
+                    chunks.push(value);
+                }
+                const combined = new Uint8Array(total);
+                let offset = 0;
+                for (const chunk of chunks) {
+                    combined.set(chunk, offset);
+                    offset += chunk.byteLength;
+                }
+                return combined;
+            })(),
+            new Promise((_resolve, reject) => {
+                timeout = setTimeout(() => reject(new Error('Overlay peer response body timed out')), exports.REMOTE_BODY_TIMEOUT_MS);
+            })
+        ]);
+        return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    finally {
+        if (timeout !== undefined)
+            clearTimeout(timeout);
+        await reader.cancel().catch(() => { });
+        reader.releaseLock();
+    }
+}
+async function readPeerJSON(response, maxBytes = exports.MAX_REMOTE_JSON_BYTES) {
+    var _a, _b, _c;
+    const contentType = (_b = (_a = response.headers) === null || _a === void 0 ? void 0 : _a.get) === null || _b === void 0 ? void 0 : _b.call(_a, 'content-type');
+    if (contentType !== null &&
+        contentType !== undefined &&
+        !/^application\/(?:[\w.-]+\+)?json(?:\s*;|$)/i.test(contentType)) {
+        await ((_c = response.body) === null || _c === void 0 ? void 0 : _c.cancel());
+        throw new TypeError('Overlay peer response is not JSON');
+    }
+    const text = await readBody(response, response.ok ? maxBytes : Math.min(maxBytes, MAX_ERROR_SNIPPET_BYTES), !response.ok);
+    if (!response.ok) {
+        const snippet = new TextDecoder().decode(new TextEncoder().encode(text).slice(0, MAX_ERROR_SNIPPET_BYTES));
+        throw new Error(`Overlay peer returned HTTP ${response.status}: ${JSON.stringify(snippet)}`);
+    }
+    if (text.length === 0)
+        throw new TypeError('Overlay peer returned an empty JSON response');
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new TypeError('Overlay peer returned malformed JSON');
+    }
+}
+function assertGASPInitialResponse(value, maxOutputs) {
+    if (!isRecord(value) || !Array.isArray(value.UTXOList) || value.UTXOList.length > maxOutputs) {
+        throw new TypeError('Invalid GASP initial response');
+    }
+    assertNonnegativeInteger(value.since, 'GASP response since');
+    const seen = new Set();
+    for (const [index, item] of value.UTXOList.entries()) {
+        if (!isRecord(item))
+            throw new TypeError(`GASP UTXOList[${index}] is invalid`);
+        assertHash(item.txid, `GASP UTXOList[${index}].txid`);
+        assertOutputIndex(item.outputIndex, `GASP UTXOList[${index}].outputIndex`);
+        assertNonnegativeInteger(item.score, `GASP UTXOList[${index}].score`);
+        const outpoint = `${item.txid.toLowerCase()}.${item.outputIndex}`;
+        if (seen.has(outpoint))
+            throw new TypeError('GASP initial response contains duplicate outpoints');
+        seen.add(outpoint);
+    }
+}
+function assertGASPNode(value, expected) {
+    if (!isRecord(value))
+        throw new TypeError('Invalid GASP node response');
+    assertOutpoint(value.graphID, 'GASP node graphID');
+    if (value.graphID !== expected.graphID)
+        throw new TypeError('GASP node graphID does not match the request');
+    assertOutputIndex(value.outputIndex, 'GASP node outputIndex');
+    if (value.outputIndex !== expected.outputIndex) {
+        throw new TypeError('GASP node outputIndex does not match the request');
+    }
+    assertHexBytes(value.rawTx, 'GASP node rawTx', exports.MAX_RAW_TRANSACTION_BYTES);
+    let actualTxid;
+    try {
+        actualTxid = sdk_1.Transaction.fromHex(value.rawTx).id('hex');
+    }
+    catch {
+        throw new TypeError('GASP node rawTx is not a valid transaction');
+    }
+    if (actualTxid.toLowerCase() !== expected.txid.toLowerCase()) {
+        throw new TypeError('GASP node transaction does not match the requested txid');
+    }
+    for (const field of ['proof', 'txMetadata', 'outputMetadata']) {
+        if (value[field] !== undefined) {
+            assertHexBytes(value[field], `GASP node ${field}`, field === 'proof' ? exports.MAX_RAW_TRANSACTION_BYTES : MAX_METADATA_BYTES, true);
+        }
+    }
+    if (value.inputs !== undefined) {
+        if (!isRecord(value.inputs) || Object.keys(value.inputs).length > MAX_GASP_INPUTS) {
+            throw new TypeError('GASP node inputs are invalid');
+        }
+        for (const [outpoint, metadata] of Object.entries(value.inputs)) {
+            assertOutpoint(outpoint, 'GASP node input outpoint');
+            if (!isRecord(metadata))
+                throw new TypeError('GASP node input metadata is invalid');
+            assertHash(metadata.hash, 'GASP node input metadata hash');
+        }
+    }
+}
+function assertRawTransactionMatches(txid, rawTx) {
+    assertHash(txid, 'transaction txid');
+    assertHexBytes(rawTx, 'raw transaction', exports.MAX_RAW_TRANSACTION_BYTES);
+    let actual;
+    try {
+        actual = sdk_1.Transaction.fromHex(rawTx).id('hex');
+    }
+    catch {
+        throw new TypeError('Peer returned an invalid raw transaction');
+    }
+    if (actual.toLowerCase() !== txid.toLowerCase()) {
+        throw new TypeError('Peer raw transaction does not match its txid');
+    }
+}
+//# sourceMappingURL=RemoteSecurity.js.map

package/dist/cjs/src/RemoteSecurity.js.map

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

package/dist/cjs/src/storage/AdmissionStorage.d.ts

@@ -0,0 +1,185 @@
+import type { HistoryRevisionHandoff } from './RecoveryContract.js';
+/** Canonical unsigned decimal, 0..2^64-1. Never round through a JS number. */
+export type StorageUint64 = string & {
+    readonly __brand: unique symbol;
+};
+export interface StorageScope {
+    network: string;
+    genesisHash: string;
+    nodeId: string;
+}
+/** These revisions are independent: a late admission need not be a reorg. */
+export interface HistoryFence {
+    chainEpoch: StorageUint64;
+    topicHistoryGeneration: StorageUint64;
+}
+export interface AdmissionIdentity {
+    scope: StorageScope;
+    /** Derived from verified immutable transaction bytes before storage is called. */
+    txid: string;
+    mode: 'live' | 'historical';
+    /** Digest of off-chain values and any other immutable admission-policy inputs. */
+    contextDigest: string;
+    topics: Array<{
+        topic: string;
+        policyId: string;
+    }>;
+}
+export interface AdmissionOperationKey {
+    scope: StorageScope;
+    operationId: string;
+    semanticDigest: string;
+}
+/** Small reference to content published outside the database transaction. */
+export interface AdmissionPayloadRef {
+    digest: string;
+    byteLength: StorageUint64;
+    kind: 'raw-transaction' | 'merkle-path' | 'beef-manifest' | 'locking-script' | 'outbox-data';
+}
+export interface AdmissionOutpoint {
+    txid: string;
+    /** Canonical decimal uint32, the transaction wire outpoint index domain. */
+    outputIndex: StorageUint64;
+}
+/** Adapter-issued revision token; absence is also a read predicate. */
+export interface AdmissionReadPredicate {
+    key: string;
+    expectedVersion: string | null;
+}
+export interface AdmissionOutput extends AdmissionOutpoint {
+    satoshis: StorageUint64;
+    score: StorageUint64;
+    /** A byte range supports even an individually oversized output script. */
+    script: {
+        payload: AdmissionPayloadRef;
+        offset: StorageUint64;
+        byteLength: StorageUint64;
+    };
+}
+export interface AdmissionTopicDecision {
+    topic: string;
+    expectedHistory: HistoryFence;
+    /** Includes all point/range/projection reads that influenced topic admission. */
+    reads: AdmissionReadPredicate[];
+    spends: Array<{
+        outpoint: AdmissionOutpoint;
+        expectedVersion: string;
+        spender: string;
+    }>;
+    /** Remove current serving outputs only; retain applied history and evidence. */
+    evictions: AdmissionOutpoint[];
+    outputs: AdmissionOutput[];
+    edges: Array<{
+        source: AdmissionOutpoint;
+        consumer: AdmissionOutpoint;
+    }>;
+    /** Retain this history after output spend, serving moderation or index eviction. */
+    applied: {
+        txid: string;
+        firstSeenHeight?: StorageUint64;
+        proof?: AdmissionPayloadRef;
+        block?: {
+            height: StorageUint64;
+            hash: string;
+            index: StorageUint64;
+            merkleRoot: string;
+        };
+    };
+    /** Invalidate downstream anchors/comparisons; own repair checkpoint moves atomically. */
+    historyUpdate?: {
+        nextTopicHistoryGeneration: StorageUint64;
+        affectedFromHeight: StorageUint64;
+        /** Present when a recovery worker itself caused this history revision. */
+        handoff?: HistoryRevisionHandoff;
+    };
+}
+/** Every event has a stable scope-local ID and ready payload references. */
+export interface AdmissionOutboxIntent {
+    eventId: string;
+    kind: 'lookup' | 'propagation';
+    target: string;
+    payloads: AdmissionPayloadRef[];
+}
+export interface AdmissionCommit {
+    key: AdmissionOperationKey;
+    identity: AdmissionIdentity;
+    /** Shared raw/proof components or a manifest; never per-output inline BEEF. */
+    payloads: AdmissionPayloadRef[];
+    decisions: AdmissionTopicDecision[];
+    outbox: AdmissionOutboxIntent[];
+    /** Exact UTF-8 STEAK JSON saved with the commit, then replayed without regeneration. */
+    steak: string;
+}
+export interface AdmissionReceipt {
+    operationId: string;
+    semanticDigest: string;
+    /** Only the selected adapter can establish this guarantee. */
+    durability: 'atomic-local';
+    steak: string;
+    /** Only enlisted indexes may be visible at commit. External indexes remain pending. */
+    indexes: Array<{
+        target: string;
+        state: 'visible' | 'pending';
+    }>;
+    propagation: 'not-requested' | 'pending';
+}
+/** Pending is not an ACK. Unknown commit must retain its opaque attempt identity. */
+export type AdmissionCommitResult = {
+    state: 'committed';
+    receipt: AdmissionReceipt;
+} | {
+    state: 'pending';
+    attemptId: string;
+} | {
+    state: 'rejected';
+    code: 'digest-mismatch' | 'read-conflict' | 'spend-conflict' | 'payload-not-ready' | 'unsupported-projection' | 'invalid-plan';
+};
+export type AdmissionReconcileResult = AdmissionCommitResult | {
+    state: 'aborted';
+};
+/**
+ * Optional v1 contract, separate from legacy CRUD Storage. No current adapter or
+ * Engine call path implements it. A provider must atomically revalidate reads,
+ * fences, conditional spends and ready-payload pins, and save every effect plus
+ * the receipt. Matching retries return the saved receipt before checking stale
+ * reads; conflicting semantic digests reject. Do not run verification, uploads,
+ * network requests or arbitrary plug-ins inside commitAdmission.
+ *
+ * TransientTransactionError permits a fresh whole-body attempt after abort and
+ * reread/redecision. UnknownTransactionCommitResult requires reconcileAdmission
+ * on the SAME attempt until committed or definitively aborted; absence of an
+ * operation record alone does not establish abort. Repeated commitAdmission
+ * must first recover any persisted unresolved attempt for this operation, even
+ * after a lost response or process restart, before it can start a fresh body.
+ * Transport failures remain
+ * errors, never rejection/abort or a successful local ACK.
+ */
+export interface AdmissionStorage {
+    readonly protocol: 'overlay-admission-v1';
+    commitAdmission: (plan: AdmissionCommit) => Promise<AdmissionCommitResult>;
+    reconcileAdmission: (key: AdmissionOperationKey, attemptId?: string) => Promise<AdmissionReconcileResult>;
+}
+/** External projection delivery may be retried only with both capabilities. */
+export interface ReplaySafeProjection {
+    readonly protocol: 'overlay-projection-v1';
+    applyEvent: (scope: StorageScope, intent: AdmissionOutboxIntent) => Promise<{
+        checkpoint: string;
+    }>;
+    reconcile: (scope: StorageScope, checkpoint: string | null) => Promise<{
+        checkpoint: string;
+    }>;
+}
+/** Shape detection is a declaration, not proof that an adapter is durable. */
+export declare function getAdmissionStorage(storage: unknown): AdmissionStorage | undefined;
+export declare function isReplaySafeProjection(projection: unknown): projection is ReplaySafeProjection;
+export declare function parseStorageUint64(value: string): bigint;
+export declare function asStorageUint64(value: string): StorageUint64;
+/** Validate the wire outpoint domain before conversion to an exact STEAK number. */
+export declare function parseStorageOutputIndex(value: string): number;
+/**
+ * SHA-256 of UTF-8 length-framed fields, see specs/overlay/persistence-v1.md.
+ * Mutable reads/decisions and proof variants are deliberately outside semantic
+ * identity. Their validation and atomic read predicates remain mandatory.
+ */
+export declare function admissionSemanticDigest(identity: AdmissionIdentity): string;
+//# sourceMappingURL=AdmissionStorage.d.ts.map

package/dist/cjs/src/storage/AdmissionStorage.d.ts.map

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

package/dist/cjs/src/storage/AdmissionStorage.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAdmissionStorage = getAdmissionStorage;
+exports.isReplaySafeProjection = isReplaySafeProjection;
+exports.parseStorageUint64 = parseStorageUint64;
+exports.asStorageUint64 = asStorageUint64;
+exports.parseStorageOutputIndex = parseStorageOutputIndex;
+exports.admissionSemanticDigest = admissionSemanticDigest;
+const node_crypto_1 = require("node:crypto");
+/** Shape detection is a declaration, not proof that an adapter is durable. */
+function getAdmissionStorage(storage) {
+    if (typeof storage !== 'object' || storage === null || !('admission' in storage))
+        return undefined;
+    const candidate = storage.admission;
+    if (typeof candidate !== 'object' || candidate === null)
+        return undefined;
+    if (!('protocol' in candidate) || candidate.protocol !== 'overlay-admission-v1')
+        return undefined;
+    if (!('commitAdmission' in candidate) || typeof candidate.commitAdmission !== 'function')
+        return undefined;
+    if (!('reconcileAdmission' in candidate) || typeof candidate.reconcileAdmission !== 'function')
+        return undefined;
+    return candidate;
+}
+function isReplaySafeProjection(projection) {
+    return (typeof projection === 'object' &&
+        projection !== null &&
+        'protocol' in projection &&
+        projection.protocol === 'overlay-projection-v1' &&
+        'applyEvent' in projection &&
+        typeof projection.applyEvent === 'function' &&
+        'reconcile' in projection &&
+        typeof projection.reconcile === 'function');
+}
+function parseStorageUint64(value) {
+    if (typeof value !== 'string' || !/^(0|[1-9]\d{0,19})$/.test(value))
+        throw new Error('Invalid storage uint64');
+    const result = BigInt(value);
+    if (result > BigInt('18446744073709551615'))
+        throw new Error('Invalid storage uint64');
+    return result;
+}
+function asStorageUint64(value) {
+    parseStorageUint64(value);
+    return value;
+}
+/** Validate the wire outpoint domain before conversion to an exact STEAK number. */
+function parseStorageOutputIndex(value) {
+    const result = parseStorageUint64(value);
+    if (result > BigInt('4294967295'))
+        throw new Error('Invalid storage output index');
+    return Number(result);
+}
+/**
+ * SHA-256 of UTF-8 length-framed fields, see specs/overlay/persistence-v1.md.
+ * Mutable reads/decisions and proof variants are deliberately outside semantic
+ * identity. Their validation and atomic read predicates remain mandatory.
+ */
+function admissionSemanticDigest(identity) {
+    if (!/^[0-9a-f]{64}$/.test(identity.txid) ||
+        !/^[0-9a-f]{64}$/.test(identity.scope.genesisHash) ||
+        !/^[0-9a-f]{64}$/.test(identity.contextDigest)) {
+        throw new Error('Invalid admission hash');
+    }
+    if (identity.mode !== 'live' && identity.mode !== 'historical')
+        throw new Error('Invalid admission mode');
+    const topics = [...identity.topics].sort((a, b) => Buffer.compare(Buffer.from(a.topic), Buffer.from(b.topic)));
+    if (topics.length === 0 ||
+        topics.some((item, index) => index > 0 && item.topic === topics[index - 1].topic)) {
+        throw new Error('Invalid admission topics');
+    }
+    const fields = [
+        'overlay-admission-v1',
+        identity.scope.network,
+        identity.scope.genesisHash,
+        identity.scope.nodeId,
+        identity.txid,
+        identity.mode,
+        identity.contextDigest,
+        String(topics.length),
+        ...topics.flatMap(({ topic, policyId }) => [topic, policyId])
+    ];
+    const hash = (0, node_crypto_1.createHash)('sha256');
+    for (const field of fields) {
+        if (field.length === 0 || !field.isWellFormed())
+            throw new Error('Invalid admission identity');
+        const bytes = Buffer.from(field, 'utf8');
+        hash.update(String(bytes.length) + ':');
+        hash.update(bytes);
+    }
+    return hash.digest('hex');
+}
+//# sourceMappingURL=AdmissionStorage.js.map

package/dist/cjs/src/storage/AdmissionStorage.js.map

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