@cello-protocol/daemon 0.0.227 → 0.0.228

package/dist/session-salts.d.ts

@@ -0,0 +1,432 @@
+/**
+ * CELLO Daemon — THE PER-SESSION CONTENT SALT
+ *
+ * Split out of `session-node-manager.ts` by 037-SESSIONCORE, Unit 1. The two sides agree a salt for
+ * this session, and every content hash is taken under it — so a hash from one conversation cannot be
+ * recognised in another, and an observer holding the plaintext cannot confirm a guess by hashing it.
+ *
+ * Moved verbatim, comments included. The operator-facing strings in here are unusually careful and
+ * they must stay that way: several exist specifically to distinguish "your counterparty is on a
+ * build that predates the salt" from "our own write failed", because those have opposite remedies
+ * and people have already been sent the wrong way once.
+ *
+ * ⚠️ THIS CLASS OWNS ELEVEN PER-SESSION SALT MAPS, of which **TEN** were cleared by hand in
+ * `#evictSessionCaches`. One `evictSession` call replaces those ten.
+ *
+ * ⚠️ **`#saltPending` IS THE ELEVENTH AND IT IS NOT ONE OF THEM — DO NOT ADD IT TO `evictSession`.**
+ * It holds a PROMISE that an outbound send is awaiting, and teardown must SETTLE it, not drop it.
+ * The caller does that on the next line (`settleSaltPending(..., "closed")`), which is what lets a
+ * send in flight return `session_torn_down` instead of waiting forever.
+ *
+ * This is not hypothetical: it was added to `evictSession` for tidiness, and because `evictSession`
+ * runs first, `settleSaltPending` then found nothing and returned — so the promise never resolved,
+ * its 5-second timer found nothing either, and `cello_send` hung with no error, no log and no
+ * timeout. The whole suite stayed green, because nothing covers that branch.
+ */
+import type { DaemonDatabase } from "./sqlcipher-db.js";
+import type { Logger, SessionRecord } from "./types.js";
+import type { SessionTree } from "./session-tree.js";
+import type { ActiveSessionEntry } from "./session-node-types.js";
+import { type SaltAgreementFrame } from "./session-salt-agreement.js";
+import { type UnsaltedReason } from "./session-node-types.js";
+import { type ContentHashAlg } from "./wire-content-hash.js";
+import { type ContentEncryptionReason } from "./content-encryption-status.js";
+/** What the salt agreement needs from the manager, stated explicitly rather than handed `this`. */
+export interface SaltContext {
+    readonly logger: Logger;
+    /** A function: the manager opens its database after construction. Re-exposed below as `#db`. */
+    db(): DaemonDatabase | null;
+    sessionKey(agentName: string, sessionId: string): string;
+    requireAgentId(agentName: string): string;
+    /** The live session entry, when one exists. */
+    activeEntry(key: string): ActiveSessionEntry | undefined;
+    getSessionTree(agentName: string, sessionId: string): SessionTree;
+    getSessionRecord(agentName: string, sessionId: string): SessionRecord | null;
+    /** Content held behind an ordering gap — the hash domain has to account for it. */
+    heldContentFor(key: string): Map<number, {
+        contentHashHex: string;
+    }> | undefined;
+    ensureHeldRestored(agentName: string, sessionId: string, opts?: {
+        release: boolean;
+    }): void;
+    /** Put a salt frame on the session's control stream. The stream is the manager's to own. */
+    sendSaltFrame(agentName: string, sessionId: string, correlationId?: string, override?: SaltAgreementFrame): Promise<void>;
+    readonly awaitingAck: Map<string, Map<string, unknown>>;
+    contentEncryptionState(agentName: string, sessionId: string): {
+        key: Uint8Array;
+        reason?: undefined;
+    } | {
+        key: null;
+        reason: ContentEncryptionReason;
+    };
+    freezeSession(agentName: string, sessionId: string, reason: string, narrative: {
+        event: string;
+        observation: string;
+        impact: string;
+        reviveReason: string;
+        reviveGuidance: string;
+    }, correlationId?: string): Promise<void>;
+}
+export declare class SessionSalts {
+    #private;
+    constructor(ctx: SaltContext);
+    /**
+     * cello_list_sessions: every persisted session for one agent, regardless of
+     * status (active, interrupted, sealed, seal_interrupted_pending). Ordered most
+     * recently updated first so the live session surfaces at the top. This is the
+     * discovery surface that the by-id reads (cello_get_transcript /
+     * cello_get_sealed_receipt) depend on — without it an agent has no way to learn
+     * its own session ids after a restart or from a fresh MCP connection.
+     */
+    /**
+     * DOD-M15-REFUSED-INBOUND-SILENT-1, the DECLINED PROTECTION half — a FIELD, not an alert.
+     *
+     * An unsalted session is exactly as verifiable as every session shipped before salting existed,
+     * so there is nothing to interrupt the operator with and no event to fire. What was missing is
+     * STATE: nothing let anyone tell *"unsalted because this build predates the feature"* from
+     * *"unsalted because adoption was refused"* — and only the second says something about their
+     * setup. The session's own status now answers it, which costs nothing per message and cannot
+     * become a flood.
+     *
+     * The raw salt is dropped on the way out rather than passed through. `SELECT *` was handing the
+     * BLOB to a listing surface that has no use for it; the boolean is the whole question a reader of
+     * this list is asking, and shipping key material to answer a yes/no is not a trade worth making.
+     */
+    /**
+     * ⚠️ THE STORED COLUMN IS NOT THE ANSWER ON ITS OWN — 006-CRYPTO finding 3.
+     *
+     * A SUSPENDED salt keeps its bytes on disk deliberately (`DOD-M15-SALTSPLIT-1`: a salt kept is
+     * recoverable, a salt erased is not), while `#saltForHashing` returns null for it and every
+     * message goes out `sha256`. Reading the column alone therefore reported `true` at the exact
+     * moment the session had STOPPED salting — and because the field is emitted only when `false`,
+     * the agent saw nothing at all, which reads as "not unsalted".
+     *
+     * That is precisely the case this field was added for. Its own note above says it exists to tell
+     * *"unsalted because this build predates the feature"* from *"unsalted because adoption was
+     * refused"*, and the refused case was the one it could not report.
+     */
+    saltStatusOf(row: SessionRecord, agentName: string | null): SessionRecord;
+    saltContributionFor(agentName: string, sessionId: string): Uint8Array;
+    /**
+     * Our half for a session, **without minting one** — review F1, and the distinction is the whole
+     * safety of the repair.
+     *
+     * A session that already holds a salt must never mint a fresh half. If it did, the repair would
+     * offer the peer a half the stored salt was NOT derived from, they would compute a different salt,
+     * and both sides would believe they had agreed — silently, which is the one outcome worse than
+     * refusing. So `null` from here means exactly "we hold a salt and the half behind it is gone",
+     * and that is the only state the agreement is allowed to call unrepairable.
+     */
+    ownSaltHalf(agentName: string, sessionId: string): Uint8Array | null;
+    /**
+     * Test seam: force this session's own salt half, so the LOCAL-defect path is reachable.
+     *
+     * `generateSaltContribution` cannot produce a degenerate half, which is the point of it — so the
+     * only way to exercise "our own random source is broken" end-to-end is to stand in for the broken
+     * source. Named `…ForTest` like every other seam, and it writes the same map production writes
+     * rather than a parallel one, so a test cannot pass against state the daemon never reads.
+     *
+     * ⚠️ This block stayed in `session-node-manager.ts` when the method moved here, and ended up
+     * stacked on an unrelated test seam — the fourth found doing that. `#saltContributions` above is
+     * "the same map production writes"; the sentence was true where it was written and unverifiable
+     * where it landed.
+     */
+    setSaltContributionForTest(agentName: string, sessionId: string, contribution: Uint8Array): void;
+    /**
+     * Test seam: drop this session's own half while leaving the stored salt in place — the state every
+     * teardown produces, because `#evictSessionCaches` clears the map and the row survives.
+     *
+     * It clears the SAME map the eviction clears rather than a stand-in, so a test cannot pass against
+     * a state the daemon never reaches. Reproducing it through a real teardown/revive would also drag
+     * in node rebuild and relay reconnection, none of which this is about.
+     */
+    forgetSaltContributionForTest(agentName: string, sessionId: string): void;
+    /**
+     * THE ONE PLACE THAT DECIDES HOW A SESSION'S OUTBOUND CONTENT IS HASHED —
+     * `DOD-M15-SEALWIRE-1` part B2b.
+     *
+     * Returns the hash AND the algorithm that produced it, together, because the two must not be
+     * decided separately. `wire-content-hash.ts` exists for exactly this reason and says so in its own
+     * header: the expression was written out at five call sites, the two added last got it wrong, and
+     * the failure was invisible — *"the send succeeds, `parked: false`, the sender's log says the frame
+     * left, and the receiver discards it at the authenticity check."* It took two real daemons.
+     *
+     * There are FOUR outbound sites (`session-content-handlers.ts`, two in `daemon.ts`,
+     * `document-delivery-transport.ts`). Once salting is switchable, each of them independently
+     * deciding whether to salt is that defect again with a worse failure mode — a message hashed one
+     * way and LABELLED another is refused by every peer, including a correct one.
+     *
+     * ⚠️ ASYNC, AND THAT IS THE POINT — B2b-2 constraint 2, not an implementation detail.
+     *
+     * The agreement is in flight while the operator composes their first message. Hash without waiting
+     * and it comes out unsalted, and that first unsalted hash closes adoption for the LIFE of the
+     * session (Decision #8, unit 1). Every session would fall back permanently while every log line
+     * about it stayed true — the feature present, wired, tested, and never once reached.
+     *
+     * The wait lives HERE rather than at the four call sites for the same reason `contentHashAlg` is a
+     * required parameter rather than a defaulted one: a site that forgets it must fail to compile. A
+     * caller that drops the `await` gets a `Promise` where bytes belong, which is a typecheck error;
+     * a caller that forgot to call a separate `awaitSaltSettled()` would silently send unsalted.
+     */
+    contentHashForSession(agentName: string, sessionId: string, content: Uint8Array): Promise<{
+        hash: Uint8Array;
+        alg: ContentHashAlg;
+    }>;
+    /**
+     * The salt to hash this session's next message under, waiting for a pending agreement if one is
+     * genuinely in flight — B2b-2 constraints 2 and 5.
+     *
+     * Three exits, and the order matters:
+     *
+     *   1. We already hold one. No wait, ever.
+     *   2. Adoption is closed — this session has hashed or leafed something already, so a salt could
+     *      never be adopted now even if one arrived. Waiting would be waiting for a value we would
+     *      then have to refuse.
+     *   3. Nothing is pending. **The park-only case (constraint 5)**: the announcement hangs off
+     *      `onPeerConnect`, an offline counterparty never connects, so no agreement was ever started.
+     *      (An away ack now ARMS one speculatively — see `markSaltPending` — so it reaches exit 4 and
+     *      settles `no_agreement_started` on timeout, which is this same answer by a slower road.) Waiting the full bound there pauses every message to an offline peer and falls
+     *      back anyway — a stall bought for nothing.
+     *
+     * Only a session with an agreement actually in flight waits, and only until it settles or the
+     * bound expires.
+     */
+    saltForHashing(agentName: string, sessionId: string): Promise<{
+        salt: Uint8Array;
+        reason?: undefined;
+    } | {
+        salt: null;
+        reason: UnsaltedReason;
+    }>;
+    /**
+     * Decision #15's fallback announcement — ONCE per session, never per message.
+     *
+     * A warning that fires on every message of every unsalted session is not a signal, it is a reason
+     * to build a filter; and the operator who filters it also filters the one session where it meant
+     * something. Stated once, with what the session actually loses.
+     */
+    announceUnsaltedOnce(agentName: string, sessionId: string, reason: UnsaltedReason): void;
+    /**
+     * Register that a salt agreement is IN FLIGHT for this session, so the first send waits for it.
+     *
+     * Called where we announce our own state — not at session creation. That distinction is
+     * constraint 5: an agreement exists to be waited for only once a frame has actually gone out.
+     */
+    /**
+     * ─── DOD-M15-AWAYSALT-1: WHO IS ALLOWED TO SAY "AN AGREEMENT IS COMING" ────────────────────────
+     *
+     * `saltForHashing` waits for an agreement ONLY when one is marked pending here. For a long time the
+     * only production caller was `#sendSaltFrame`, which fires on peer ATTACH — and that is later than
+     * the inbound session REQUEST which triggers an away auto-reply. So the away ack hashed with
+     * nothing pending, took `NO_AGREEMENT_STARTED`, and hashed UNSALTED.
+     *
+     * One unsalted leaf closes salt adoption for the entire session (`already_hashing`), permanently.
+     * The initiator, meanwhile, derives a salt, cannot erase it (`session.salt.split`,
+     * `suspended_but_unerasable`) and keeps labelling content `hmac-sha256-salt-v1` — which this side
+     * can then only refuse. Every message from the initiator is quarantined
+     * (`content_hash_salt_unavailable`), and the session can never seal.
+     *
+     * Measured 2026-09-07 on session 436c92f4, on the DEFAULT path (initiate to an unattended agent):
+     * the ack hashed at 22:48:03.752, the peer announced at 22:48:04.561 — 0.8s late — and the
+     * operator's first real message was quarantined. Nothing recovers it; the guidance on
+     * `session.salt.split` says to start a new session, and a new session repeats the race.
+     *
+     * So `expectSaltAgreement` on the manager now calls this BEFORE any early hash. It is idempotent
+     * (a second call is a no-op while one is outstanding) and bounded by the same `boundMs` timer as
+     * every other pending agreement, so a counterparty that never announces settles `timeout` and the
+     * content hashes unsalted exactly as it does today — the wait is a delay, never a failure.
+     *
+     * ⚠️ STILL OPEN: this covers the away reply, which is the only content this daemon emits before a
+     * peer can attach. Any FUTURE caller that hashes that early needs the same line, and nothing here
+     * enforces that.
+     */
+    markSaltPending(agentName: string, sessionId: string, boundMs?: number, announced?: boolean): void;
+    /**
+     * WHICH of the four terminal answers the peer actually gave — 006-CRYPTO finding 2.
+     *
+     * The default is the NON-ASSERTING reason, not the most common one. An unknown label means a build
+     * we do not understand, and rendering that as "they had already hashed messages" states something
+     * about a counterparty that may be untrue — which is what sends an operator to raise a
+     * non-problem with them. The label is peer-supplied, so nothing outside the known set is repeated
+     * back as our own diagnosis.
+     *
+     * A missing entry maps to the already-hashing case: `PEER_CLOSED_FIRST` and an absent label both
+     * mean the peer is answering a closure of OURS, and `#saltForHashing` answers that with
+     * `ADOPTION_CLOSED_LOCALLY` one branch earlier — this is only the fallback if it did not.
+     */
+    peerClosedReason(key: string): UnsaltedReason;
+    /** Resolve a pending agreement. Idempotent: the first outcome wins and the timer is cleared. */
+    settleSaltPending(agentName: string, sessionId: string, outcome: "agreed" | "timeout" | "closed" | "persist_failed" | "announce_failed"): void;
+    /**
+     * THIS SESSION'S UNSALTED HASH NEVER BECAME A MESSAGE — release the permanent closure it caused.
+     *
+     * ⚠️ REVIEW FINDING 3, and it is the opposite of the direction the flag was written to defend.
+     * `#hashedWithoutSalt` closes adoption at hash time, because for a session's first message the
+     * leaf is a network round trip away and every frontier count reads zero in between. Correct — but
+     * `cello_send` has three paths that compute the hash and then produce NOTHING: a sibling send
+     * holding the in-flight claim, the frontier moving under the send, and a non-durable send failure
+     * whose bytes go to a queue with no production consumer.
+     *
+     * In all three the session was permanently unsalted for a message that exists nowhere: no leaf, no
+     * wire, no copy at the peer. And B2b-2 made two of them MORE likely on a first message, because
+     * the five-second wait widens the very window the frontier re-check is watching.
+     *
+     * Only safe because it is called on paths that provably sent nothing. It deliberately does NOT
+     * clear `#unsaltedAnnounced`: the announcement was true when it fired and re-announcing on the
+     * retry would be the per-message flood Decision #15 forbids.
+     *
+     * ─── THREE OTHER SITES HASH AND MAY SEND NOTHING, AND ARE EXEMPT ON PURPOSE (pass 2, F8) ──────
+     *
+     * `daemon.ts`'s one-shot rejection and away reply, and `document-delivery-transport.ts`'s frame
+     * send, can all fail after hashing. None of them needs to abandon, and the reason is the same in
+     * each: every one is a REPLY. The inbound message that triggered it has already been leafed on
+     * this side, so `#saltAdoptionClosed` is already closed by the leaf count and would stay closed
+     * whatever this flag said. Calling abandon there would be a no-op that looks like a guarantee.
+     *
+     * Written down rather than left to be re-derived: the next reader's first question is why the
+     * list is three and not six.
+     */
+    abandonUnsaltedHash(agentName: string, sessionId: string): void;
+    /**
+     * PUBLIC read of a session's agreed salt — `DOD-M15-SEALWIRE-1` part B2a.
+     *
+     * `content-park.ts` runs a SECOND, independent content-hash verifier (the park signature does not
+     * cover the envelope content, so it checks before `ingestReceivedContent` is ever reached), and it
+     * hardcoded `sha256`. It needs the salt to verify a v3 envelope, and it is outside this class.
+     *
+     * Read-only and cache-backed, so exposing it adds no way to CHANGE the salt from outside — the
+     * only writer remains `#persistSessionSalt`, behind the one-salt-per-session predicate.
+     */
+    /**
+     * IS THIS SESSION ACTUALLY PROTECTED BY ITS SALT RIGHT NOW — pass 2, F3.
+     *
+     * Distinct from `getSessionContentSalt`, which is POSSESSION and is what the verifier needs: a
+     * message parked before suspension was hashed under this salt and must still be checkable against
+     * it, so that accessor must keep answering with the bytes.
+     *
+     * This one answers the OPERATOR's question, and it is a different question. A suspended session
+     * holds a salt it will not use, so every hash it produces is `sha256` — reporting `contentSalted:
+     * true` there is not a gap, it is an affirmatively false security claim on the surface whose own
+     * comment reads *"a security property must not be inferable from a gap."* Same predicate
+     * `#saltForHashing` uses, so the flag cannot drift from the behaviour it describes.
+     */
+    isContentSaltActive(agentName: string, sessionId: string): boolean;
+    /**
+     * This session's agreed salt, or null. Reads the durable row through a cache, because Decision #8
+     * persists it for exactly one reason: *"a restart silently splits the transcript"* if the lookup
+     * misses and a fresh salt is minted.
+     *
+     * A read failure returns null WITH a log rather than throwing — except the bare `!this.#db` guard,
+     * which is this file's convention at 60+ sites and only reachable during shutdown. Null means "we
+     * hold no salt", which drives the agreement to offer a contribution — and against a peer that does
+     * hold one that is a named, loud `salt_state_divergent` refusal. So the degraded path ends in a
+     * diagnosis, not in a session that quietly hashes under the wrong value.
+     *
+     * ⚠️ THIS PARAGRAPH SPENT A UNIT STRANDED 180 LINES AWAY, directly above `contentHashForSession`
+     * and followed by that method's own block — so a reader hovering the hash decision got prose about
+     * salt read failures. Harmless and exactly the kind of drift that makes a comment stop being read.
+     */
+    getSessionSalt(agentName: string, sessionId: string): Uint8Array | null;
+    /**
+     * Is this session past the point where a salt can be adopted? — Decision #8, part B2b-2.
+     *
+     * ⚠️ THE PREDICATE IS "HAS ANYTHING BEEN HASHED", NOT "IS THERE A LEAF" — review F5. A leaf is
+     * APPENDED after `await sendContent(...)` returns, so a message can be hashed, put on the wire, and
+     * still be invisible to `tree.size()`. Adopting inside that window makes leaf 0 unsalted and the
+     * rest salted — the exact split this exists to prevent, with the guard green.
+     *
+     * ⚠️ HELD CONTENT COUNTS, AND MUST BE HYDRATED FIRST — review F6. `#ensureHeldRestored` is lazy and
+     * is not called at session-node creation, so a revived session whose first inbound frame is the
+     * salt frame reads a frontier that excludes durable `held_content` rows — rows already hashed
+     * unsalted, which `#releaseHeld` will append moments later. Every other frontier reader in this
+     * file hydrates first, for this reason. `release: false`, because a salt frame must never deliver
+     * messages as a side effect.
+     *
+     * ⚠️ "CANNOT TELL" IS CLOSED, NOT OPEN. `#requireAgentId` throws for a retired agent, and inferring
+     * "zero leaves" from a failure to count them is how a guard becomes a formality. The cost of
+     * refusing is an unsalted session; the cost of permitting is a transcript neither rule can verify.
+     */
+    saltAdoptionClosed(agentName: string, sessionId: string): {
+        closed: boolean;
+        label: string;
+        leafCount: number;
+        why: string;
+    };
+    /**
+     * Persist the agreed salt, and DO NOT ANNOUNCE ONE WE FAILED TO STORE.
+     *
+     * The caller sends its fingerprint only if this returns true. A salt held in memory and not on
+     * disk would confirm agreement to the counterparty and then be gone at the next restart — turning
+     * a loud `salt_state_divergent` refusal, which is the whole point of Decision #10, into the silent
+     * split it exists to prevent, one restart later.
+     *
+     * ⚠️ SECOND ORPHAN OF THE SAME KIND. This paragraph was stranded above `#saltAdoptionClosed` and
+     * followed by that method's own block, exactly like the `#getSessionSalt` one re-homed in the
+     * previous pass — which walked straight past this one sixty lines below it. Two in one file is not
+     * coincidence: inserting a method between a doc block and its subject leaves no error, no lint,
+     * and no test, so the drift is invisible until someone reads for it.
+     */
+    persistSessionSalt(agentName: string, sessionId: string, salt: Uint8Array): boolean;
+    /**
+     * DROP AN UNSPENT SALT — `DOD-M15-SALTSPLIT-1`. The second writer of `content_salt`, and the only
+     * one that clears it.
+     *
+     * Reached when the counterparty tells us it can never adopt a salt for this session. Keeping ours
+     * would mean every message we send from here is refused by them with
+     * `content_hash_salt_unavailable` — a conversation that dies while looking merely quiet, which is
+     * the failure this exists to prevent.
+     *
+     * ⚠️ THE ADOPTION CHECK IS REPEATED HERE ON PURPOSE, not because the caller is untrusted.
+     *
+     * The caller has already computed `adoption`, so this looks redundant — and it is, for today's one
+     * call site. It stays because the cost of a future caller getting it wrong is a transcript that no
+     * single rule can verify: leaves hashed under a salt that has just been erased, with nothing
+     * recording that they were. A guard whose failure mode is silent and permanent belongs next to the
+     * destructive act, not only at the place that currently decides to perform it. Same reasoning that
+     * made `placeOwnLeaf`'s authorship parameter required rather than optional.
+     *
+     * Returns true only if a salt was actually cleared.
+     */
+    /**
+     * SUSPEND, don't destroy — `DOD-M15-SALTSPLIT-1`, the authorization argument. Returns true if a
+     * salt is now suspended (or already was).
+     *
+     * This is the frame handler's entry point. It runs the same two refusals as the erase below —
+     * a spent salt and one mid-flight are not ours to set aside either, because the messages already
+     * hashed under them would become unverifiable the moment we stop using it — and where they do not
+     * fire it records the suspension instead of doing anything irreversible.
+     */
+    suspendSalt(agentName: string, sessionId: string, correlationId?: string): boolean;
+    /** Un-suspend: the peer answered with a fingerprint matching the salt we kept. */
+    resumeSalt(agentName: string, sessionId: string, correlationId?: string): void;
+    discardUnspentSalt(agentName: string, sessionId: string, correlationId?: string): boolean;
+    /** Apply one inbound salt-agreement frame. The verdict is the pure function's; this executes it. */
+    handleSaltFrame(agentName: string, sessionId: string, frame: SaltAgreementFrame, correlationId?: string): Promise<void>;
+    /**
+     * Forget every salt fact this module holds for one session.
+     *
+     * ⚠️ ELEVEN MAPS BEHIND ONE CALL, and that is the point. These were eleven of the twenty-four
+     * per-session containers the manager's cache eviction cleared by hand — so forgetting a session
+     * meant knowing every map that might hold a piece of it, and adding a twelfth meant remembering to
+     * add a twelfth delete. Missing one leaves a per-session entry alive for the life of the process.
+     * The list of what to forget now lives beside the code that fills them.
+     */
+    evictSession(agentName: string, sessionId: string): void;
+    /**
+     * The pair the agreement reasons over: our salt, and the half that goes with it.
+     *
+     * Minting is deliberate and conditional. With NO salt we are certain to need a half — to offer, or
+     * to derive with — so minting here is what makes the exchange work at all. WITH a salt we must
+     * never mint; see `#ownSaltHalf`.
+     */
+    saltState(agentName: string, sessionId: string): {
+        ownSalt: Uint8Array | null;
+        ownContribution: Uint8Array | null;
+    };
+    /**
+     * ONE mapping from a settled outcome to the operator-facing reason, so the send that WAITED and the
+     * send that arrived afterwards cannot disagree about what happened.
+     */
+    reasonForOutcome(key: string, outcome: "timeout" | "closed" | "persist_failed" | "announce_failed"): UnsaltedReason;
+}
+//# sourceMappingURL=session-salts.d.ts.map

package/dist/session-salts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-salts.d.ts","sourceRoot":"","sources":["../src/session-salts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAGlE,OAAO,EAIL,KAAK,kBAAkB,EACxB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAqC,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAChG,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,gCAAgC,CAAC;AAExC,mGAAmG;AACnG,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,gGAAgG;IAChG,EAAE,IAAI,cAAc,GAAG,IAAI,CAAC;IAC5B,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IACzD,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1C,+CAA+C;IAC/C,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAAC;IACzD,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,WAAW,CAAC;IAClE,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAAC;IAC7E,mFAAmF;IACnF,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE;QAAE,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,SAAS,CAAC;IACjF,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC5F,4FAA4F;IAC5F,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1H,QAAQ,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxD,sBAAsB,CACpB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB;QAAE,GAAG,EAAE,UAAU,CAAC;QAAC,MAAM,CAAC,EAAE,SAAS,CAAA;KAAE,GAAG;QAAE,GAAG,EAAE,IAAI,CAAC;QAAC,MAAM,EAAE,uBAAuB,CAAA;KAAE,CAAC;IAC5F,aAAa,CACX,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,EAC/G,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED,qBAAa,YAAY;;gBAGX,GAAG,EAAE,WAAW;IAsK5B;;;;;;;OAOG;IACH;;;;;;;;;;;;;OAaG;IACH;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,GAAG,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,aAAa;IAwBzE,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,UAAU;IASrE;;;;;;;;;OASG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAGpE;;;;;;;;;;;;OAYG;IACH,0BAA0B,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,UAAU,GAAG,IAAI;IAGhG;;;;;;;OAOG;IACH,6BAA6B,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAGzE;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACG,qBAAqB,CACzB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,UAAU,GAClB,OAAO,CAAC;QAAE,IAAI,EAAE,UAAU,CAAC;QAAC,GAAG,EAAE,cAAc,CAAA;KAAE,CAAC;IAoIrD;;;;;;;;;;;;;;;;;;OAkBG;IACG,cAAc,CAClB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;QAAE,IAAI,EAAE,UAAU,CAAC;QAAC,MAAM,CAAC,EAAE,SAAS,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,IAAI,CAAC;QAAC,MAAM,EAAE,cAAc,CAAA;KAAE,CAAC;IAwG7F;;;;;;OAMG;IACH,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,IAAI;IAaxF;;;;;OAKG;IACH;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,SAAyB,EAAE,SAAS,UAAQ,GAAG,IAAI;IAiChH;;;;;;;;;;;;OAYG;IACH,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc;IAU7C,gGAAgG;IAChG,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,gBAAgB,GAAG,iBAAiB,GAAG,IAAI;IAU9I;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAmB/D;;;;;;;;;OASG;IACH;;;;;;;;;;;;OAYG;IACH,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IAIlE;;;;;;;;;;;;;;OAcG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAsCvE;;;;;;;;;;;;;;;;;;OAkBG;IACH,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE;IAqC5H;;;;;;;;;;;;;OAaG;IACH,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO;IA6GnF;;;;;;;;;;;;;;;;;;;OAmBG;IACH;;;;;;;;OAQG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO;IAgClF,kFAAkF;IAClF,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI;IA0C9E,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO;IA4GzF,oGAAoG;IAC9F,eAAe,CACnB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,kBAAkB,EACzB,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC;IA+RhB;;;;;;;;OAQG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAcxD;;;;;;OAMG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC;QAAC,eAAe,EAAE,UAAU,GAAG,IAAI,CAAA;KAAE;IASnH;;;OAGG;IACH,gBAAgB,CACd,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,SAAS,GAAG,QAAQ,GAAG,gBAAgB,GAAG,iBAAiB,GACnE,cAAc;CAMlB"}