@cello-protocol/client 0.0.2

package/dist/agent-hash-queue.d.ts

@@ -0,0 +1,206 @@
+/**
+ * CELLO-PERSIST-012 — Agent Hash Queue + Signed Relay ACKs
+ *
+ * ── Pseudocode (Phase P) ──────────────────────────────────────────────────────
+ *
+ * The agent hash queue is a first-class protocol primitive. When relay connectivity
+ * is interrupted, the P2P conversation continues and hashes accumulate in the queue.
+ * On relay recovery or reassignment, queued hashes are submitted in FIFO order.
+ *
+ * buildSignedAckTbs(hashHex, sequenceNumber, timestamp):
+ *   // RFC 8032 (Ed25519), FIPS 180-4 (SHA-256)
+ *   // Deterministic TBS for signing and verification. Fixed-width encodings prevent
+ *   // ambiguity: a 4-byte and an 8-byte integer concatenated to 32-byte hash bytes.
+ *   hashBytes = Buffer.from(hashHex, 'hex')               // 32 bytes
+ *   seqBuf    = 4-byte big-endian uint32                   // 4 bytes
+ *   tsBuf     = 8-byte big-endian uint64                   // 8 bytes
+ *   preimage  = concat(hashBytes, seqBuf, tsBuf)           // 44 bytes
+ *   return SHA-256(preimage)                                // 32 bytes
+ *
+ * verifyRelayAck(hashHex, ack, relayPubkey):
+ *   // Reconstructs TBS and verifies Ed25519 signature
+ *   tbs = buildSignedAckTbs(hashHex, ack.sequenceNumber, ack.timestamp)
+ *   if ack.signature.length !== 64: return false
+ *   return Ed25519.verify(relayPubkey, tbs, ack.signature)
+ *
+ * AgentHashQueue.enqueue(sessionId, hashHex, correlationId):
+ *   // Must happen BEFORE relay submission (AC-001)
+ *   pending = await #loadPending(sessionId)
+ *   entry = { hashHex, sessionId, enqueuedAt: Date.now() }
+ *   pending.push(entry)
+ *   await #savePending(sessionId, pending)
+ *   logger.info("client.hashqueue.enqueued", { agentId, sessionId, hashHex,
+ *               queueDepth: pending.length, correlationId })
+ *
+ * AgentHashQueue.processAck(sessionId, hashHex, ack, lookupRelayPubkey, correlationId):
+ *   // 1. Verify ACK signature (SI-001: never remove without valid ACK)
+ *   relayPubkey = await lookupRelayPubkey(ack.relayId)
+ *   if relayPubkey === null || !verifyRelayAck(hashHex, ack, relayPubkey):
+ *     logger.warn("client.relay.ack.invalid", { agentId, sessionId, hashHex, reason })
+ *     return  // hash stays in queue
+ *   // 2. Store ACK as cryptographic receipt (SI-003: immutable, never overwrite)
+ *   existing = await #loadAck(hashHex)
+ *   if existing === undefined:
+ *     await #saveAck(hashHex, ack)
+ *   // 3. Remove from pending queue (only AFTER ACK is stored)
+ *   pending = await #loadPending(sessionId)
+ *   pending = pending.filter(e => e.hashHex !== hashHex)
+ *   await #savePending(sessionId, pending)
+ *   logger.info("client.hashqueue.acked", { agentId, sessionId, hashHex,
+ *               sequenceNumber: ack.sequenceNumber, correlationId })
+ *
+ * AgentHashQueue.pollDepth():
+ *   // Called on 30-second interval (externally scheduled)
+ *   // Logs client.hashqueue.depth when depth > 0 (AC-006)
+ *   // Also checks for stale entries (DB-001)
+ *   allPending = await #loadAllPending()
+ *   depth = total pending count
+ *   if depth === 0: return
+ *   logger.info("client.hashqueue.depth", { agentId, depth })
+ *   // Check staleness
+ *   oldestEntry = entry with minimum enqueuedAt
+ *   oldestAge = Date.now() - oldestEntry.enqueuedAt
+ *   if oldestAge > hashQueueMaxAgeMs:
+ *     logger.warn("client.hashqueue.stale", { agentId, depth, oldestHashAge: oldestAge })
+ *
+ * Storage keys:
+ *   pending queue:  "hq:pending:{sessionId}" → JSON PendingHashEntry[]
+ *   ACK receipt:    "hq:ack:{hashHex}"        → JSON StoredRelayAck
+ *   All-sessions index: "hq:sessions"         → JSON string[] of sessionIds with queues
+ */
+import type { ClientStore, Logger } from "@cello-protocol/interfaces";
+/** A single entry in the local pending hash queue. */
+export interface PendingHashEntry {
+    /** Session this hash belongs to. */
+    sessionId: string;
+    /** SHA-256 content hash as lowercase hex (32 bytes → 64 chars). */
+    hashHex: string;
+    /** Unix ms when the entry was enqueued. Used for staleness checks. */
+    enqueuedAt: number;
+}
+/** A relay's signed ACK for a submitted hash. Stored as an immutable receipt. */
+export interface RelayAck {
+    /** Stable identifier for the signing relay (used for pubkey lookup). */
+    relayId: string;
+    /** 32-byte Ed25519 public key of the relay that signed this ACK. */
+    relayPubkey: Uint8Array;
+    /** Relay-assigned sequence number for this hash. */
+    sequenceNumber: number;
+    /** Unix ms timestamp embedded in the ACK TBS. */
+    timestamp: number;
+    /** 64-byte Ed25519 signature over SHA-256(hashHex_bytes || seq_BE4 || ts_BE8). */
+    signature: Uint8Array;
+}
+/** Sentinel returned by handleResubmitRejection when predecessor relay is unknown. */
+export declare const RELAY_PREDECESSOR_UNKNOWN: "RELAY_PREDECESSOR_UNKNOWN";
+export type RelayPredecessorUnknown = typeof RELAY_PREDECESSOR_UNKNOWN;
+/** Options for constructing an AgentHashQueue. */
+export interface AgentHashQueueOptions {
+    /** ClientStore for persisting the queue and ACK receipts. */
+    store: ClientStore;
+    /** Stable agent identifier — included in all log events. */
+    agentId: string;
+    /** Structured logger injected at the composition root. */
+    logger: Logger;
+    /**
+     * Maximum age (ms) for a pending hash before DB-001 stale warning fires.
+     * Default: 24 * 60 * 60 * 1000 (24 hours).
+     */
+    hashQueueMaxAgeMs?: number;
+}
+/**
+ * Build the to-be-signed bytes for a relay ACK.
+ *
+ * Hex-decodes hashHex and delegates to buildRelayAckTbs (the canonical
+ * implementation in @cello-protocol/crypto shared with the relay signer).
+ *
+ * TBS = SHA-256(hash_bytes || seq_BE4 || ts_BE8). RFC 8032, FIPS 180-4.
+ */
+export declare function buildSignedAckTbs(hashHex: string, sequenceNumber: number, timestamp: number): Uint8Array;
+/**
+ * Verify a relay ACK signature.
+ *
+ * Returns true if:
+ *   - ack.signature is exactly 64 bytes
+ *   - Ed25519.verify(relayPubkey, buildSignedAckTbs(hashHex, ack.sequenceNumber, ack.timestamp), ack.signature) is true
+ *
+ * RFC 8032 (Ed25519), FIPS 180-4 (SHA-256)
+ */
+export declare function verifyRelayAck(hashHex: string, ack: RelayAck, relayPubkey: Uint8Array): boolean;
+/**
+ * Manages the local queue of Structure 1 hashes pending relay submission.
+ *
+ * Security invariants:
+ *   SI-001: A hash is never removed from the pending queue without a valid stored ACK.
+ *           The remove-from-queue step only executes after ACK verification passes.
+ *   SI-002: getPending() returns items in strict insertion order. The caller is
+ *           responsible for FIFO submission — the queue does not reorder.
+ *   SI-003: Once an ACK is stored for a hash, subsequent ACKs for the same hash
+ *           do not overwrite the existing receipt.
+ *
+ * Persistence: all state is stored in the injected ClientStore using JSON encoding.
+ * Keys: "hq:pending:{sessionId}" and "hq:ack:{hashHex}".
+ */
+export declare class AgentHashQueue {
+    #private;
+    constructor(opts: AgentHashQueueOptions);
+    /**
+     * Enqueue a hash in the local hash queue before relay submission.
+     *
+     * Must be called BEFORE attempting relay submission (AC-001).
+     * The hash is present in the queue until a valid signed ACK is processed.
+     *
+     * Logs: client.hashqueue.enqueued with { agentId, sessionId, hashHex, queueDepth, correlationId }
+     */
+    enqueue(sessionId: string, hashHex: string, correlationId: string): Promise<void>;
+    /**
+     * Process a relay ACK for a previously enqueued hash.
+     *
+     * Steps (SI-001 enforced):
+     *   1. Look up the relay's public key via lookupRelayPubkey(ack.relayId).
+     *   2. Verify the ACK signature with verifyRelayAck().
+     *   3. If verification fails: log client.relay.ack.invalid; return WITHOUT touching the queue.
+     *   4. Store the ACK as immutable receipt (SI-003: skip if already stored).
+     *   5. Remove the hash from the pending queue ONLY after ACK is stored.
+     *
+     * @param sessionId       - session the hash belongs to
+     * @param hashHex         - the hash being ACKed
+     * @param ack             - the relay's ACK frame
+     * @param lookupRelayPubkey - async function that looks up relay pubkey by relayId
+     * @param correlationId   - correlation ID for log tracing
+     */
+    processAck(sessionId: string, hashHex: string, ack: RelayAck, lookupRelayPubkey: (relayId: string) => Promise<Uint8Array | null>, correlationId: string): Promise<void>;
+    /**
+     * Return all pending (un-ACKed) hashes for a session in insertion order (SI-002).
+     */
+    getPending(sessionId: string): Promise<PendingHashEntry[]>;
+    /**
+     * Return the stored relay ACK for a hash, or undefined if not yet ACKed.
+     */
+    getAck(hashHex: string): Promise<RelayAck | undefined>;
+    /**
+     * Return the total number of pending hashes for a session.
+     */
+    depth(sessionId: string): Promise<number>;
+    /**
+     * Poll the total queue depth across all sessions.
+     *
+     * If depth > 0: logs client.hashqueue.depth at INFO with { agentId, depth }.
+     * If depth > 0 and oldest entry is older than hashQueueMaxAgeMs: additionally logs
+     *   client.hashqueue.stale at WARN with { agentId, depth, oldestHashAge } (DB-001).
+     *
+     * Called externally on a 30-second interval while the agent is running.
+     * Test-friendly: call directly without waiting.
+     */
+    pollDepth(): Promise<void>;
+    /**
+     * Handle a re-submission rejection from the new relay.
+     *
+     * Logs client.relay.resubmit.rejected at ERROR with { agentId, sessionId, hashHex, reason }.
+     * The hash remains in the pending queue (DB-002: operator must resolve manually).
+     *
+     * @returns the reason string (for caller convenience)
+     */
+    handleResubmitRejection(sessionId: string, hashHex: string, reason: string): Promise<string>;
+}
+//# sourceMappingURL=agent-hash-queue.d.ts.map

package/dist/agent-hash-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-hash-queue.d.ts","sourceRoot":"","sources":["../src/agent-hash-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAItE,sDAAsD;AACtD,MAAM,WAAW,gBAAgB;IAC/B,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,iFAAiF;AACjF,MAAM,WAAW,QAAQ;IACvB,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,WAAW,EAAE,UAAU,CAAC;IACxB,oDAAoD;IACpD,cAAc,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,SAAS,EAAE,UAAU,CAAC;CACvB;AAWD,sFAAsF;AACtF,eAAO,MAAM,yBAAyB,EAAG,2BAAoC,CAAC;AAC9E,MAAM,MAAM,uBAAuB,GAAG,OAAO,yBAAyB,CAAC;AAEvE,kDAAkD;AAClD,MAAM,WAAW,qBAAqB;IACpC,6DAA6D;IAC7D,KAAK,EAAE,WAAW,CAAC;IACnB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAgBD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,MAAM,GAChB,UAAU,CAEZ;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,QAAQ,EACb,WAAW,EAAE,UAAU,GACtB,OAAO,CAIT;AAID;;;;;;;;;;;;;GAaG;AACH,qBAAa,cAAc;;gBAMb,IAAI,EAAE,qBAAqB;IASvC;;;;;;;OAOG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAwBvF;;;;;;;;;;;;;;;OAeG;IACG,UAAU,CACd,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,QAAQ,EACb,iBAAiB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,EAClE,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC;IAgDhB;;OAEG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAIhE;;OAEG;IACG,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IAI5D;;OAEG;IACG,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAO/C;;;;;;;;;OASG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAgChC;;;;;;;OAOG;IACG,uBAAuB,CAC3B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC;CA2FnB"}

package/dist/agent-hash-queue.js

@@ -0,0 +1,380 @@
+/**
+ * CELLO-PERSIST-012 — Agent Hash Queue + Signed Relay ACKs
+ *
+ * ── Pseudocode (Phase P) ──────────────────────────────────────────────────────
+ *
+ * The agent hash queue is a first-class protocol primitive. When relay connectivity
+ * is interrupted, the P2P conversation continues and hashes accumulate in the queue.
+ * On relay recovery or reassignment, queued hashes are submitted in FIFO order.
+ *
+ * buildSignedAckTbs(hashHex, sequenceNumber, timestamp):
+ *   // RFC 8032 (Ed25519), FIPS 180-4 (SHA-256)
+ *   // Deterministic TBS for signing and verification. Fixed-width encodings prevent
+ *   // ambiguity: a 4-byte and an 8-byte integer concatenated to 32-byte hash bytes.
+ *   hashBytes = Buffer.from(hashHex, 'hex')               // 32 bytes
+ *   seqBuf    = 4-byte big-endian uint32                   // 4 bytes
+ *   tsBuf     = 8-byte big-endian uint64                   // 8 bytes
+ *   preimage  = concat(hashBytes, seqBuf, tsBuf)           // 44 bytes
+ *   return SHA-256(preimage)                                // 32 bytes
+ *
+ * verifyRelayAck(hashHex, ack, relayPubkey):
+ *   // Reconstructs TBS and verifies Ed25519 signature
+ *   tbs = buildSignedAckTbs(hashHex, ack.sequenceNumber, ack.timestamp)
+ *   if ack.signature.length !== 64: return false
+ *   return Ed25519.verify(relayPubkey, tbs, ack.signature)
+ *
+ * AgentHashQueue.enqueue(sessionId, hashHex, correlationId):
+ *   // Must happen BEFORE relay submission (AC-001)
+ *   pending = await #loadPending(sessionId)
+ *   entry = { hashHex, sessionId, enqueuedAt: Date.now() }
+ *   pending.push(entry)
+ *   await #savePending(sessionId, pending)
+ *   logger.info("client.hashqueue.enqueued", { agentId, sessionId, hashHex,
+ *               queueDepth: pending.length, correlationId })
+ *
+ * AgentHashQueue.processAck(sessionId, hashHex, ack, lookupRelayPubkey, correlationId):
+ *   // 1. Verify ACK signature (SI-001: never remove without valid ACK)
+ *   relayPubkey = await lookupRelayPubkey(ack.relayId)
+ *   if relayPubkey === null || !verifyRelayAck(hashHex, ack, relayPubkey):
+ *     logger.warn("client.relay.ack.invalid", { agentId, sessionId, hashHex, reason })
+ *     return  // hash stays in queue
+ *   // 2. Store ACK as cryptographic receipt (SI-003: immutable, never overwrite)
+ *   existing = await #loadAck(hashHex)
+ *   if existing === undefined:
+ *     await #saveAck(hashHex, ack)
+ *   // 3. Remove from pending queue (only AFTER ACK is stored)
+ *   pending = await #loadPending(sessionId)
+ *   pending = pending.filter(e => e.hashHex !== hashHex)
+ *   await #savePending(sessionId, pending)
+ *   logger.info("client.hashqueue.acked", { agentId, sessionId, hashHex,
+ *               sequenceNumber: ack.sequenceNumber, correlationId })
+ *
+ * AgentHashQueue.pollDepth():
+ *   // Called on 30-second interval (externally scheduled)
+ *   // Logs client.hashqueue.depth when depth > 0 (AC-006)
+ *   // Also checks for stale entries (DB-001)
+ *   allPending = await #loadAllPending()
+ *   depth = total pending count
+ *   if depth === 0: return
+ *   logger.info("client.hashqueue.depth", { agentId, depth })
+ *   // Check staleness
+ *   oldestEntry = entry with minimum enqueuedAt
+ *   oldestAge = Date.now() - oldestEntry.enqueuedAt
+ *   if oldestAge > hashQueueMaxAgeMs:
+ *     logger.warn("client.hashqueue.stale", { agentId, depth, oldestHashAge: oldestAge })
+ *
+ * Storage keys:
+ *   pending queue:  "hq:pending:{sessionId}" → JSON PendingHashEntry[]
+ *   ACK receipt:    "hq:ack:{hashHex}"        → JSON StoredRelayAck
+ *   All-sessions index: "hq:sessions"         → JSON string[] of sessionIds with queues
+ */
+import { verify, buildRelayAckTbs } from "@cello-protocol/crypto";
+/** Sentinel returned by handleResubmitRejection when predecessor relay is unknown. */
+export const RELAY_PREDECESSOR_UNKNOWN = "RELAY_PREDECESSOR_UNKNOWN";
+// ─── Storage key helpers ──────────────────────────────────────────────────────
+function pendingKey(sessionId) {
+    return `hq:pending:${sessionId}`;
+}
+function ackKey(hashHex) {
+    return `hq:ack:${hashHex}`;
+}
+const SESSIONS_INDEX_KEY = "hq:sessions";
+// ─── Pure crypto helpers ──────────────────────────────────────────────────────
+/**
+ * Build the to-be-signed bytes for a relay ACK.
+ *
+ * Hex-decodes hashHex and delegates to buildRelayAckTbs (the canonical
+ * implementation in @cello-protocol/crypto shared with the relay signer).
+ *
+ * TBS = SHA-256(hash_bytes || seq_BE4 || ts_BE8). RFC 8032, FIPS 180-4.
+ */
+export function buildSignedAckTbs(hashHex, sequenceNumber, timestamp) {
+    return buildRelayAckTbs(Buffer.from(hashHex, "hex"), sequenceNumber, timestamp);
+}
+/**
+ * Verify a relay ACK signature.
+ *
+ * Returns true if:
+ *   - ack.signature is exactly 64 bytes
+ *   - Ed25519.verify(relayPubkey, buildSignedAckTbs(hashHex, ack.sequenceNumber, ack.timestamp), ack.signature) is true
+ *
+ * RFC 8032 (Ed25519), FIPS 180-4 (SHA-256)
+ */
+export function verifyRelayAck(hashHex, ack, relayPubkey) {
+    if (ack.signature.length !== 64)
+        return false;
+    const tbs = buildSignedAckTbs(hashHex, ack.sequenceNumber, ack.timestamp);
+    return verify(relayPubkey, tbs, ack.signature);
+}
+// ─── AgentHashQueue ───────────────────────────────────────────────────────────
+/**
+ * Manages the local queue of Structure 1 hashes pending relay submission.
+ *
+ * Security invariants:
+ *   SI-001: A hash is never removed from the pending queue without a valid stored ACK.
+ *           The remove-from-queue step only executes after ACK verification passes.
+ *   SI-002: getPending() returns items in strict insertion order. The caller is
+ *           responsible for FIFO submission — the queue does not reorder.
+ *   SI-003: Once an ACK is stored for a hash, subsequent ACKs for the same hash
+ *           do not overwrite the existing receipt.
+ *
+ * Persistence: all state is stored in the injected ClientStore using JSON encoding.
+ * Keys: "hq:pending:{sessionId}" and "hq:ack:{hashHex}".
+ */
+export class AgentHashQueue {
+    #store;
+    #agentId;
+    #logger;
+    #hashQueueMaxAgeMs;
+    constructor(opts) {
+        this.#store = opts.store;
+        this.#agentId = opts.agentId;
+        this.#logger = opts.logger;
+        this.#hashQueueMaxAgeMs = opts.hashQueueMaxAgeMs ?? 24 * 60 * 60 * 1000;
+    }
+    // ─── Enqueue ───────────────────────────────────────────────────────────────
+    /**
+     * Enqueue a hash in the local hash queue before relay submission.
+     *
+     * Must be called BEFORE attempting relay submission (AC-001).
+     * The hash is present in the queue until a valid signed ACK is processed.
+     *
+     * Logs: client.hashqueue.enqueued with { agentId, sessionId, hashHex, queueDepth, correlationId }
+     */
+    async enqueue(sessionId, hashHex, correlationId) {
+        // Track the session in the sessions index for pollDepth()
+        await this.#addToSessionsIndex(sessionId);
+        const pending = await this.#loadPending(sessionId);
+        const entry = {
+            sessionId,
+            hashHex,
+            enqueuedAt: Date.now(),
+        };
+        pending.push(entry);
+        await this.#savePending(sessionId, pending);
+        this.#logger.info("client.hashqueue.enqueued", {
+            agentId: this.#agentId,
+            sessionId,
+            hashHex,
+            queueDepth: pending.length,
+            correlationId,
+        });
+    }
+    // ─── Process ACK ──────────────────────────────────────────────────────────
+    /**
+     * Process a relay ACK for a previously enqueued hash.
+     *
+     * Steps (SI-001 enforced):
+     *   1. Look up the relay's public key via lookupRelayPubkey(ack.relayId).
+     *   2. Verify the ACK signature with verifyRelayAck().
+     *   3. If verification fails: log client.relay.ack.invalid; return WITHOUT touching the queue.
+     *   4. Store the ACK as immutable receipt (SI-003: skip if already stored).
+     *   5. Remove the hash from the pending queue ONLY after ACK is stored.
+     *
+     * @param sessionId       - session the hash belongs to
+     * @param hashHex         - the hash being ACKed
+     * @param ack             - the relay's ACK frame
+     * @param lookupRelayPubkey - async function that looks up relay pubkey by relayId
+     * @param correlationId   - correlation ID for log tracing
+     */
+    async processAck(sessionId, hashHex, ack, lookupRelayPubkey, correlationId) {
+        // Step 1: Look up the relay's public key
+        const relayPubkey = await lookupRelayPubkey(ack.relayId);
+        // Step 2: Verify ACK signature
+        let validationError = null;
+        if (relayPubkey === null) {
+            validationError = "relay_pubkey_not_found";
+        }
+        else if (ack.signature.length !== 64) {
+            validationError = "signature_malformed";
+        }
+        else if (!verifyRelayAck(hashHex, ack, relayPubkey)) {
+            validationError = "signature_invalid";
+        }
+        if (validationError !== null) {
+            // Step 3: Invalid — log warning and leave hash in queue (SI-001)
+            this.#logger.warn("client.relay.ack.invalid", {
+                agentId: this.#agentId,
+                sessionId,
+                hashHex,
+                reason: validationError,
+            });
+            return;
+        }
+        // Step 4: Store ACK as immutable receipt (SI-003: never overwrite existing ACK)
+        const existing = await this.#loadAck(hashHex);
+        if (existing === undefined) {
+            await this.#saveAck(hashHex, ack);
+        }
+        // If already stored: SI-003 guarantees the first ACK is preserved.
+        // Step 5: Remove from pending queue ONLY after ACK is stored
+        const pending = await this.#loadPending(sessionId);
+        const updated = pending.filter((e) => e.hashHex !== hashHex);
+        await this.#savePending(sessionId, updated);
+        this.#logger.info("client.hashqueue.acked", {
+            agentId: this.#agentId,
+            sessionId,
+            hashHex,
+            sequenceNumber: ack.sequenceNumber,
+            correlationId,
+        });
+    }
+    // ─── Queue inspection ──────────────────────────────────────────────────────
+    /**
+     * Return all pending (un-ACKed) hashes for a session in insertion order (SI-002).
+     */
+    async getPending(sessionId) {
+        return this.#loadPending(sessionId);
+    }
+    /**
+     * Return the stored relay ACK for a hash, or undefined if not yet ACKed.
+     */
+    async getAck(hashHex) {
+        return this.#loadAck(hashHex);
+    }
+    /**
+     * Return the total number of pending hashes for a session.
+     */
+    async depth(sessionId) {
+        const pending = await this.#loadPending(sessionId);
+        return pending.length;
+    }
+    // ─── Depth polling (AC-006, DB-001) ──────────────────────────────────────
+    /**
+     * Poll the total queue depth across all sessions.
+     *
+     * If depth > 0: logs client.hashqueue.depth at INFO with { agentId, depth }.
+     * If depth > 0 and oldest entry is older than hashQueueMaxAgeMs: additionally logs
+     *   client.hashqueue.stale at WARN with { agentId, depth, oldestHashAge } (DB-001).
+     *
+     * Called externally on a 30-second interval while the agent is running.
+     * Test-friendly: call directly without waiting.
+     */
+    async pollDepth() {
+        const allPending = await this.#loadAllPending();
+        const depth = allPending.length;
+        if (depth === 0)
+            return;
+        // DB-001: compute oldest age before logging so it appears in the depth event
+        const now = Date.now();
+        let oldest = now;
+        for (const entry of allPending) {
+            if (entry.enqueuedAt < oldest) {
+                oldest = entry.enqueuedAt;
+            }
+        }
+        const oldestHashAge = now - oldest;
+        this.#logger.info("client.hashqueue.depth", {
+            agentId: this.#agentId,
+            depth,
+            oldestHashAge,
+        });
+        if (oldestHashAge > this.#hashQueueMaxAgeMs) {
+            this.#logger.warn("client.hashqueue.stale", {
+                agentId: this.#agentId,
+                depth,
+                oldestHashAge,
+            });
+        }
+    }
+    // ─── Error handlers ────────────────────────────────────────────────────────
+    /**
+     * Handle a re-submission rejection from the new relay.
+     *
+     * Logs client.relay.resubmit.rejected at ERROR with { agentId, sessionId, hashHex, reason }.
+     * The hash remains in the pending queue (DB-002: operator must resolve manually).
+     *
+     * @returns the reason string (for caller convenience)
+     */
+    async handleResubmitRejection(sessionId, hashHex, reason) {
+        this.#logger.error("client.relay.resubmit.rejected", {
+            agentId: this.#agentId,
+            sessionId,
+            hashHex,
+            reason,
+        });
+        // Hash stays in queue — no state mutation
+        return reason;
+    }
+    // ─── Private storage helpers ───────────────────────────────────────────────
+    async #loadPending(sessionId) {
+        const raw = await this.#store.get(pendingKey(sessionId));
+        if (raw === undefined)
+            return [];
+        try {
+            return JSON.parse(Buffer.from(raw).toString("utf8"));
+        }
+        catch {
+            return [];
+        }
+    }
+    async #savePending(sessionId, entries) {
+        const raw = Buffer.from(JSON.stringify(entries), "utf8");
+        await this.#store.set(pendingKey(sessionId), new Uint8Array(raw));
+    }
+    async #loadAck(hashHex) {
+        const raw = await this.#store.get(ackKey(hashHex));
+        if (raw === undefined)
+            return undefined;
+        try {
+            const stored = JSON.parse(Buffer.from(raw).toString("utf8"));
+            return {
+                relayId: stored.relayId,
+                relayPubkey: new Uint8Array(Buffer.from(stored.relayPubkeyHex, "hex")),
+                sequenceNumber: stored.sequenceNumber,
+                timestamp: stored.timestamp,
+                signature: new Uint8Array(Buffer.from(stored.signatureHex, "hex")),
+            };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async #saveAck(hashHex, ack) {
+        const stored = {
+            relayId: ack.relayId,
+            relayPubkeyHex: Buffer.from(ack.relayPubkey).toString("hex"),
+            sequenceNumber: ack.sequenceNumber,
+            timestamp: ack.timestamp,
+            signatureHex: Buffer.from(ack.signature).toString("hex"),
+        };
+        const raw = Buffer.from(JSON.stringify(stored), "utf8");
+        await this.#store.set(ackKey(hashHex), new Uint8Array(raw));
+    }
+    async #addToSessionsIndex(sessionId) {
+        const raw = await this.#store.get(SESSIONS_INDEX_KEY);
+        let sessions = [];
+        if (raw !== undefined) {
+            try {
+                sessions = JSON.parse(Buffer.from(raw).toString("utf8"));
+            }
+            catch {
+                sessions = [];
+            }
+        }
+        if (!sessions.includes(sessionId)) {
+            sessions.push(sessionId);
+            const newRaw = Buffer.from(JSON.stringify(sessions), "utf8");
+            await this.#store.set(SESSIONS_INDEX_KEY, new Uint8Array(newRaw));
+        }
+    }
+    async #loadAllPending() {
+        const raw = await this.#store.get(SESSIONS_INDEX_KEY);
+        if (raw === undefined)
+            return [];
+        let sessions = [];
+        try {
+            sessions = JSON.parse(Buffer.from(raw).toString("utf8"));
+        }
+        catch {
+            return [];
+        }
+        const all = [];
+        for (const sessionId of sessions) {
+            const pending = await this.#loadPending(sessionId);
+            all.push(...pending);
+        }
+        return all;
+    }
+}
+//# sourceMappingURL=agent-hash-queue.js.map

package/dist/agent-hash-queue.js.map

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

package/dist/backup-key-derivation.d.ts

@@ -0,0 +1,37 @@
+/**
+ * backup-key-derivation.ts — HKDF derivation of the cloud backup encryption key.
+ *
+ * PERSIST-011: backup_key = HKDF-SHA256(ikm=identity_key, salt=none,
+ *              info='backup-key' || agent_id, length=32)
+ *
+ * Security invariants (PERSIST-011 SI-001):
+ *   - identity_key is passed in by the caller; it is NEVER stored here.
+ *   - The returned backup_key is NEVER logged or persisted by this function.
+ *   - This function has no side effects — pure transformation only.
+ *
+ * Key independence (AC-001):
+ *   - backup_key and db_key use distinct info strings:
+ *       db_key:     info = 'local-db-key\x00' + agentId
+ *       backup_key: info = 'backup-key\x00' + agentId
+ *   - For the same identity_key and agentId, backup_key != db_key.
+ *   - Losing one key does not compromise the other.
+ *
+ * RFC reference: RFC 5869 (HKDF). Node.js implementation: crypto.hkdfSync.
+ */
+/**
+ * Derive a 32-byte cloud backup encryption key from the agent's identity_key.
+ *
+ * @param identityKey - The agent's long-term root key (32 bytes). Never stored or logged.
+ * @param agentId     - The stable agent identifier. Binds the key to a specific agent.
+ * @returns           - A 32-byte Uint8Array suitable for use as an AES-256-GCM key.
+ *
+ * Security: The backup_key is deterministic — same inputs always produce the same output.
+ * This is intentional: the client must re-derive the key on every backup/restore without
+ * storing it, using only the identity_key (which is stored separately, protected
+ * by the OS keychain or equivalent).
+ *
+ * The null-byte separator between the literal and agentId prevents prefix-collision
+ * attacks where two different (literal, agentId) pairs produce the same concatenation.
+ */
+export declare function deriveBackupKey(identityKey: Uint8Array, agentId: string): Uint8Array;
+//# sourceMappingURL=backup-key-derivation.d.ts.map

package/dist/backup-key-derivation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup-key-derivation.d.ts","sourceRoot":"","sources":["../src/backup-key-derivation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,CAYpF"}