@kya-os/mcp 1.16.1 → 1.17.0

package/dist/audit/providers/source-state.js

@@ -1,31 +1,58 @@
-/** In-process reference source-watermark state. Production AAP-3 needs durability. */
+import { AUDIT_ERROR_CODES, AuditProtocolError } from '../errors.js';
+const DEFAULT_REDELIVERY_WINDOW = 1024;
+function publicClaim(claim) {
+    return {
+        sequence: claim.sequence.toString(),
+        ...(claim.previousSourceEventDigest === undefined
+            ? {}
+            : { previousSourceEventDigest: claim.previousSourceEventDigest }),
+    };
+}
+/**
+ * In-process reference source-watermark state. Production AAP-3 needs
+ * durability. Memory is bounded by the pending (unreceipted) events plus the
+ * redelivery window, however long a gap stays open.
+ */
 export class MemoryAuditSourceState {
     capabilities = { durability: 'ephemeral', atomicClaim: true };
     states = new Map();
+    redeliveryWindow;
+    constructor(options = {}) {
+        this.redeliveryWindow = options.redeliveryWindow ?? DEFAULT_REDELIVERY_WINDOW;
+        if (!Number.isSafeInteger(this.redeliveryWindow) || this.redeliveryWindow < 0) {
+            throw new RangeError('Source redelivery window must be a non-negative safe integer');
+        }
+    }
     async claimEvent(sourceId, eventId) {
         const state = this.state(sourceId);
         const existing = state.claims.get(eventId);
         if (existing !== undefined) {
-            return {
-                sequence: existing.sequence.toString(),
-                ...(existing.previousSourceEventDigest === undefined
-                    ? {}
-                    : { previousSourceEventDigest: existing.previousSourceEventDigest }),
-            };
+            if (state.retained.delete(eventId))
+                state.retained.add(eventId);
+            return publicClaim(existing);
         }
         state.next += 1n;
-        const previousSourceEventDigest = state.eventDigests.get(state.next - 1n);
         const claim = {
             sequence: state.next,
-            ...(previousSourceEventDigest === undefined ? {} : { previousSourceEventDigest }),
+            ...(state.latestDigest === undefined ? {} : { previousSourceEventDigest: state.latestDigest }),
         };
+        state.latestDigest = undefined;
         state.claims.set(eventId, claim);
-        return {
-            sequence: claim.sequence.toString(),
-            ...(claim.previousSourceEventDigest === undefined
-                ? {}
-                : { previousSourceEventDigest: claim.previousSourceEventDigest }),
-        };
+        state.pending.set(claim.sequence, eventId);
+        return publicClaim(claim);
+    }
+    async abandonClaim(sourceId, eventId, sequence) {
+        const state = this.state(sourceId);
+        const claim = state.claims.get(eventId);
+        // An emitted claim may already be in flight, and a later claim has linked
+        // past this one; either way the sequence stays a visible pending gap.
+        if (claim === undefined || claim.sequence !== BigInt(sequence) ||
+            claim.eventDigest !== undefined || claim.sequence !== state.next)
+            return;
+        state.claims.delete(eventId);
+        state.pending.delete(claim.sequence);
+        state.next -= 1n;
+        state.latestDigest = claim.previousSourceEventDigest;
     }
     async markEmitted(sourceId, eventId, sequence, eventDigest) {
         const state = this.state(sourceId);
@@ -33,47 +60,42 @@ export class MemoryAuditSourceState {
         const claim = state.claims.get(eventId);
         if (claim?.sequence !== parsed)
             throw new RangeError('Unknown source event claim');
-        const existing = state.eventDigests.get(parsed);
-        if (existing !== undefined && existing !== eventDigest) {
-            throw new Error(`Source event identity collision: ${eventId}`);
+        if (claim.eventDigest !== undefined && claim.eventDigest !== eventDigest) {
+            // The same conflict the recorder reports for a reused event ID, so a
+            // caller sees one error whichever layer catches the divergent content.
+            throw new AuditProtocolError(AUDIT_ERROR_CODES.EVENT_ID_CONFLICT, `Source event identity collision: ${eventId}`, { sourceId, eventId });
         }
-        state.eventDigests.set(parsed, eventDigest);
+        claim.eventDigest = eventDigest;
+        if (parsed === state.next)
+            state.latestDigest = eventDigest;
     }
     async markReceipted(sourceId, sequence) {
         const parsed = BigInt(sequence);
         const state = this.state(sourceId);
         if (parsed < 1n || parsed > state.next)
             throw new RangeError('Unknown source sequence');
-        if (parsed <= state.receiptedWatermark)
+        const eventId = state.pending.get(parsed);
+        if (eventId === undefined)
             return;
-        state.receipted.add(parsed);
-        while (state.receipted.delete(state.receiptedWatermark + 1n)) {
-            state.receiptedWatermark += 1n;
-        }
-        // Keep only the current watermark's claim/digest plus unresolved entries.
-        // This bounds the reference adapter by the outstanding delivery window,
-        // while retaining the digest needed to link the next producer event.
-        for (const [eventId, claim] of state.claims) {
-            if (claim.sequence < state.receiptedWatermark)
-                state.claims.delete(eventId);
-        }
-        for (const sequenceNumber of state.eventDigests.keys()) {
-            if (sequenceNumber < state.receiptedWatermark)
-                state.eventDigests.delete(sequenceNumber);
+        state.pending.delete(parsed);
+        state.retained.add(eventId);
+        for (const oldest of state.retained) {
+            if (state.retained.size <= this.redeliveryWindow)
+                break;
+            state.retained.delete(oldest);
+            state.claims.delete(oldest);
         }
     }
     async getState(sourceId) {
         const state = this.state(sourceId);
-        const pendingSequences = [];
-        for (let sequence = state.receiptedWatermark + 1n; sequence <= state.next; sequence += 1n) {
-            if (!state.receipted.has(sequence))
-                pendingSequences.push(sequence.toString());
-        }
+        // Claims take strictly increasing sequences and are only ever removed, so
+        // the map's insertion order is already ascending.
+        const pending = [...state.pending.keys()];
         return {
             sourceId,
             highestEmitted: state.next.toString(),
-            highestReceipted: state.receiptedWatermark.toString(),
-            pendingSequences,
+            highestReceipted: (pending.length === 0 ? state.next : pending[0] - 1n).toString(),
+            pendingSequences: pending.map((value) => value.toString()),
         };
     }
     state(sourceId) {
@@ -82,10 +104,9 @@ export class MemoryAuditSourceState {
             return existing;
         const created = {
             next: 0n,
-            receiptedWatermark: 0n,
-            receipted: new Set(),
+            pending: new Map(),
             claims: new Map(),
-            eventDigests: new Map(),
+            retained: new Set(),
         };
         this.states.set(sourceId, created);
         return created;

package/dist/audit/providers/source-state.js.map

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

package/dist/audit/read-contract.d.ts

@@ -442,4 +442,3 @@ export declare function toAuditHeadResponse(head: AuditHead | null): AuditHeadRe
 export declare function toAuditListEntriesResponse(page: AuditReadEntriesPage): AuditListEntriesResponseV1;
 export declare function toAuditInclusionProofResponse(proof: AuditBundleInclusionProofV1): AuditInclusionProofResponseV1;
 export declare function toAuditConsistencyProofResponse(proof: AuditBundleConsistencyProofV1): AuditConsistencyProofResponseV1;
-//# sourceMappingURL=read-contract.d.ts.map

package/dist/audit/read-service.d.ts

@@ -78,8 +78,8 @@ export declare const MAX_READ_ENTRIES_LIMIT = 1000;
  * proofs are needed, an {@link AuditCheckpointReadAccess}.
  *
  * Reads ride the journal's ordered `readRange`, so paging cost is independent of
- * ledger size. Pagination fetches one extra entry to detect a further page
- * without a second round trip.
+ * ledger size. Each page is bounded by the head read before it, which decides
+ * whether a further page exists.
  */
 export declare class LocalAuditReadService implements AuditReadService {
     private readonly journal;
@@ -96,4 +96,3 @@ export declare class LocalAuditReadService implements AuditReadService {
 }
 /** One-call composition helper mirroring {@link createLocalAuditRecorder}. */
 export declare function createLocalAuditReadService(deps: AuditReadServiceDeps): AuditReadService;
-//# sourceMappingURL=read-service.d.ts.map

package/dist/audit/read-service.js

@@ -20,8 +20,8 @@ function requireDecimal(value, label) {
  * proofs are needed, an {@link AuditCheckpointReadAccess}.
  *
  * Reads ride the journal's ordered `readRange`, so paging cost is independent of
- * ledger size. Pagination fetches one extra entry to detect a further page
- * without a second round trip.
+ * ledger size. Each page is bounded by the head read before it, which decides
+ * whether a further page exists.
  */
 export class LocalAuditReadService {
     journal;
@@ -36,21 +36,26 @@ export class LocalAuditReadService {
     async listEntries(query) {
         const limit = clampLimit(query.limit);
         const ledger = ledgerOf(query);
-        // Over-fetch by one: if the journal yields limit+1, a further page exists.
-        const collected = [];
+        // The head is read first and bounds the page, so the echoed head and the
+        // cursor describe the same snapshot even while appends continue.
+        const head = await this.journal.getHead(ledger);
+        if (head === null)
+            return { entries: [], head, nextAfterSequence: null };
+        const headSequence = BigInt(head.sequence);
+        const entries = [];
         for await (const entry of this.journal.readRange({
             ...ledger,
             ...(query.afterSequence === undefined ? {} : { afterSequence: query.afterSequence }),
-            limit: limit + 1,
+            limit,
         })) {
-            collected.push(entry);
-            if (collected.length > limit)
+            if (BigInt(entry.core.sequence) > headSequence)
                 break;
+            entries.push(entry);
         }
-        const hasMore = collected.length > limit;
-        const entries = hasMore ? collected.slice(0, limit) : collected;
-        const nextAfterSequence = hasMore ? entries[entries.length - 1].core.sequence : null;
-        const head = await this.journal.getHead(ledger);
+        const last = entries[entries.length - 1];
+        const nextAfterSequence = last === undefined || last.core.sequence === head.sequence
+            ? null
+            : last.core.sequence;
         return { entries, head, nextAfterSequence };
     }
     async getLatestCheckpoint(ledger) {
@@ -104,7 +109,7 @@ export class LocalAuditReadService {
     async entryAtSequence(ledger, sequence) {
         const value = requireDecimal(sequence, 'sequence');
         // `readRange` is exclusive on afterSequence, so start one below the target.
-        const afterSequence = value > 1n ? String(value - 1n) : undefined;
+        const afterSequence = value > 0n ? String(value - 1n) : undefined;
         for await (const entry of this.journal.readRange({
             ...ledger,
             ...(afterSequence === undefined ? {} : { afterSequence }),

package/dist/audit/read-service.js.map

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

package/dist/audit/recorder-service.d.ts

@@ -54,25 +54,53 @@ export declare class AuditRecorderService {
     private readonly config;
     private readonly maxAppendConflicts;
     private initialization?;
+    /** Highest head this recorder has itself appended in its epoch. */
+    private committedHead;
+    /** Highest head the journal has reported in a compare-and-append result. */
+    private reportedHead;
+    /** Write-ahead evidence objects held by submissions in flight, by object ID. */
+    private readonly heldEvidence;
     constructor(config: AuditRecorderServiceConfig);
     submitAuthenticated(submission: AuditRecorderSubmission, context: AuthenticatedAuditSubmissionContext): Promise<SignedAuditEntryV1>;
     /**
-     * Best-effort compensation for write-ahead evidence whose append failed: the
-     * ciphertext is disposed only after re-confirming that no committed entry
-     * claims this event identity, so a raced idempotent commit is never stripped
-     * of its evidence. Failures here leave orphans for operator retention tooling.
+     * Registers this submission as a holder of each evidence object it carries.
+     * An object two submissions hold at once is marked shared for as long as
+     * either still holds it: both may have seen it as new, and the other may
+     * already have committed a reference to it.
+     */
+    private holdEvidence;
+    private releaseEvidence;
+    /**
+     * Best-effort compensation for write-ahead evidence whose append failed. Only
+     * objects this submission newly stored are disposed: an object that already
+     * existed may be referenced by another committed entry, and so may one that
+     * a concurrent submission held at the same time. They are disposed only
+     * after re-confirming that no committed entry claims this event identity, so
+     * a raced idempotent commit is never stripped of its evidence. Failures here
+     * leave orphans for operator retention tooling.
      */
     private disposeUncommittedEvidence;
     private validateSubmissionEnvelope;
     private validateEventAuthority;
+    /** Persists write-ahead evidence and returns the objects that did not exist before. */
     private persistSubmittedEvidence;
     private ensureInitialized;
     private validateExistingGenesis;
     private genesisEvent;
     private appendEvent;
+    /**
+     * The compare-and-append result is the journal's authoritative head. One
+     * below a head this recorder had committed before issuing the append, or a
+     * different digest at a sequence the journal already reported, means a
+     * failover to a lagging primary or a restore. Retrying there would sign a
+     * second entry at a receipted sequence, so the recorder fails closed. The
+     * heads compared are the ones known when the append was issued, so a
+     * concurrent submission's later commit never makes a correct answer look
+     * stale.
+     */
+    private assertNoRegression;
     private identifyEvent;
     private resolveDuplicate;
     private buildCandidate;
     private ledgerRef;
 }
-//# sourceMappingURL=recorder-service.d.ts.map

package/dist/audit/recorder-service.js

@@ -15,6 +15,14 @@ function sameHead(left, right) {
         return left === right;
     return left.entryDigest === right.entryDigest && left.sequence === right.sequence;
 }
+/** The later of two heads; at an equal sequence the first one is kept. */
+function higherHead(current, candidate) {
+    if (candidate === null)
+        return current;
+    if (current === null)
+        return candidate;
+    return BigInt(candidate.sequence) > BigInt(current.sequence) ? candidate : current;
+}
 function sameSigner(left, right) {
     return left.did === right.did && left.kid === right.kid && left.alg === right.alg;
 }
@@ -31,6 +39,12 @@ export class AuditRecorderService {
     config;
     maxAppendConflicts;
     initialization;
+    /** Highest head this recorder has itself appended in its epoch. */
+    committedHead = null;
+    /** Highest head the journal has reported in a compare-and-append result. */
+    reportedHead = null;
+    /** Write-ahead evidence objects held by submissions in flight, by object ID. */
+    heldEvidence = new Map();
     constructor(config) {
         this.config = config;
         if ((config.previousEpochId === undefined) !==
@@ -62,29 +76,66 @@ export class AuditRecorderService {
             throw new AuditProtocolError(AUDIT_ERROR_CODES.EPOCH_MISMATCH, 'Wrong audit ledger epoch');
         }
         await this.ensureInitialized();
-        await this.persistSubmittedEvidence(submission.encryptedEvidence, producerEvent);
+        const held = this.holdEvidence(submission.encryptedEvidence);
         try {
-            return await this.appendEvent(producerEvent, context, false, identity);
+            const stored = await this.persistSubmittedEvidence(submission.encryptedEvidence, producerEvent);
+            try {
+                return await this.appendEvent(producerEvent, context, false, identity);
+            }
+            catch (error) {
+                await this.disposeUncommittedEvidence(stored, identity);
+                throw error;
+            }
         }
-        catch (error) {
-            await this.disposeUncommittedEvidence(submission.encryptedEvidence, identity);
-            throw error;
+        finally {
+            this.releaseEvidence(held);
         }
     }
     /**
-     * Best-effort compensation for write-ahead evidence whose append failed: the
-     * ciphertext is disposed only after re-confirming that no committed entry
-     * claims this event identity, so a raced idempotent commit is never stripped
-     * of its evidence. Failures here leave orphans for operator retention tooling.
+     * Registers this submission as a holder of each evidence object it carries.
+     * An object two submissions hold at once is marked shared for as long as
+     * either still holds it: both may have seen it as new, and the other may
+     * already have committed a reference to it.
      */
-    async disposeUncommittedEvidence(evidence, identity) {
-        if (evidence.length === 0 || this.config.evidence === undefined)
+    holdEvidence(evidence) {
+        const objectIds = [...new Set(evidence.map((item) => item.ref.objectId))];
+        for (const objectId of objectIds) {
+            const hold = this.heldEvidence.get(objectId);
+            if (hold === undefined)
+                this.heldEvidence.set(objectId, { holders: 1, shared: false });
+            else
+                this.heldEvidence.set(objectId, { holders: hold.holders + 1, shared: true });
+        }
+        return objectIds;
+    }
+    releaseEvidence(objectIds) {
+        for (const objectId of objectIds) {
+            const hold = this.heldEvidence.get(objectId);
+            if (hold.holders === 1)
+                this.heldEvidence.delete(objectId);
+            else
+                this.heldEvidence.set(objectId, { ...hold, holders: hold.holders - 1 });
+        }
+    }
+    /**
+     * Best-effort compensation for write-ahead evidence whose append failed. Only
+     * objects this submission newly stored are disposed: an object that already
+     * existed may be referenced by another committed entry, and so may one that
+     * a concurrent submission held at the same time. They are disposed only
+     * after re-confirming that no committed entry claims this event identity, so
+     * a raced idempotent commit is never stripped of its evidence. Failures here
+     * leave orphans for operator retention tooling.
+     */
+    async disposeUncommittedEvidence(stored, identity) {
+        if (stored.length === 0 || this.config.evidence === undefined)
             return;
         try {
             const committed = await this.config.journal.getByIdempotencyKey(this.config.ledgerId, identity.idempotencyKey);
             if (committed !== null)
                 return;
-            for (const item of evidence) {
+            for (const item of stored) {
+                if (this.heldEvidence.get(item.ref.objectId)?.shared === true)
+                    continue;
                 await this.config.evidence.applyRetention({
                     kind: 'dispose',
                     ref: item.ref,
@@ -114,15 +165,17 @@ export class AuditRecorderService {
             throw new AuditProtocolError(AUDIT_ERROR_CODES.UNAUTHORIZED_SUBMISSION, 'Event tenant does not match the authenticated tenant authority');
         }
     }
+    /** Persists write-ahead evidence and returns the objects that did not exist before. */
     async persistSubmittedEvidence(evidence, event) {
         if (evidence.length === 0)
-            return;
+            return [];
         if (this.config.evidence === undefined) {
             throw new AuditProtocolError(AUDIT_ERROR_CODES.EVIDENCE_FAILURE, 'Encrypted evidence was submitted but no evidence provider is configured');
         }
         try {
             const refs = new Map(collectAuditEvidenceRefs(event).map((ref) => [ref.objectId, ref]));
             const submitted = new Set();
+            const stored = [];
             for (const item of evidence) {
                 const referenced = refs.get(item.ref.objectId);
                 if (submitted.has(item.ref.objectId) || referenced === undefined ||
@@ -130,8 +183,12 @@ export class AuditRecorderService {
                     throw new AuditProtocolError(AUDIT_ERROR_CODES.EVIDENCE_FAILURE, 'Submitted evidence does not exactly match a unique frozen event reference', { objectId: item.ref.objectId });
                 }
                 submitted.add(item.ref.objectId);
+                const existed = await this.config.evidence.has(item.ref);
                 await this.config.evidence.putIfAbsent(item);
+                if (!existed)
+                    stored.push(item);
             }
+            return stored;
         }
         catch (error) {
             if (error instanceof AuditProtocolError &&
@@ -242,7 +299,14 @@ export class AuditRecorderService {
         }
         const ledger = this.ledgerRef();
         for (let attempt = 0; attempt <= this.maxAppendConflicts; attempt += 1) {
-            const head = await this.config.journal.getHead(ledger);
+            // A read behind this recorder's own commits (a lagging replica) is not
+            // an append position: compare-and-append against the committed head, so
+            // a stale read costs one retry and a journal that really moved backwards
+            // answers with a conflict that proves it instead of accepting a second
+            // entry at a receipted sequence.
+            const committed = this.committedHead;
+            const reported = this.reportedHead;
+            const head = higherHead(committed, await this.config.journal.getHead(ledger));
             if (genesis && head !== null) {
                 const raced = await this.config.journal.getByIdempotencyKey(this.config.ledgerId, idempotencyKey);
                 if (raced !== null)
@@ -261,20 +325,52 @@ export class AuditRecorderService {
             catch (error) {
                 throw new AuditProtocolError(AUDIT_ERROR_CODES.JOURNAL_FAILURE, 'Audit journal append failed', undefined, { cause: error });
             }
-            if (result.kind === 'appended' || result.kind === 'duplicate') {
-                return result.kind === 'duplicate'
-                    ? this.resolveDuplicate(result.entry, eventDigest)
-                    : result.entry;
+            if (result.kind === 'appended') {
+                const appended = {
+                    ...ledger,
+                    sequence: result.entry.core.sequence,
+                    entryDigest: result.entry.entryDigest,
+                };
+                this.committedHead = higherHead(this.committedHead, appended);
+                this.reportedHead = higherHead(this.reportedHead, appended);
+                return result.entry;
             }
-            if (result.kind === 'idempotency_conflict') {
-                return this.resolveDuplicate(result.existing, eventDigest);
+            if (result.kind === 'duplicate' || result.kind === 'idempotency_conflict') {
+                const existing = result.kind === 'duplicate' ? result.entry : result.existing;
+                // A replica that lost the cold-start genesis race finds a genesis that
+                // differs only in recorder-authored timing; it is accepted on epoch
+                // configuration, never as an event-identity conflict.
+                return genesis
+                    ? this.validateExistingGenesis(existing)
+                    : this.resolveDuplicate(existing, eventDigest);
             }
+            this.assertNoRegression(result.actualHead, committed, reported);
+            this.reportedHead = higherHead(this.reportedHead, result.actualHead);
             if (sameHead(head, result.actualHead)) {
                 throw new AuditProtocolError(AUDIT_ERROR_CODES.JOURNAL_FAILURE, 'Audit journal reported a head conflict without advancing its head');
             }
         }
         throw new AuditProtocolError(AUDIT_ERROR_CODES.APPEND_CONFLICT_EXHAUSTED, 'Audit append conflict retry budget exhausted');
     }
+    /**
+     * The compare-and-append result is the journal's authoritative head. One
+     * below a head this recorder had committed before issuing the append, or a
+     * different digest at a sequence the journal already reported, means a
+     * failover to a lagging primary or a restore. Retrying there would sign a
+     * second entry at a receipted sequence, so the recorder fails closed. The
+     * heads compared are the ones known when the append was issued, so a
+     * concurrent submission's later commit never makes a correct answer look
+     * stale.
+     */
+    assertNoRegression(actual, committed, reported) {
+        const forks = (known) => known !== null && actual !== null &&
+            known.sequence === actual.sequence && known.entryDigest !== actual.entryDigest;
+        if ((committed !== null &&
+            (actual === null || BigInt(actual.sequence) < BigInt(committed.sequence))) ||
+            forks(committed) || forks(reported)) {
+            throw new AuditProtocolError(AUDIT_ERROR_CODES.JOURNAL_FAILURE, 'Audit journal head moved behind a head this recorder already committed or saw', { committedSequence: committed?.sequence, reportedSequence: actual?.sequence });
+        }
+    }
     async identifyEvent(event, context) {
         const eventDigest = await digestAuditEvent(this.config.hasher, event);
         const idempotencyKey = await hashAuditValue(this.config.hasher, AUDIT_DIGEST_DOMAINS.idempotency, {