@cello-protocol/daemon 0.0.227 → 0.0.229

package/dist/session-salt-agreement.js

@@ -0,0 +1,472 @@
+/**
+ * THE SALT AGREEMENT STATE MACHINE — `DOD-M15-SEALWIRE-1` bullet 6, part A.
+ * Decisions Carried #8 (both sides contribute, one salt per session, persisted) and #10 (a mismatch
+ * must be loud).
+ *
+ * ⚠️ PART A OF THE SALT WORK, AND THE SPLIT IS DELIBERATE. This module and its caller AGREE a salt
+ * and store it.
+ *
+ * **NO SENDER SALTS YET**, which is what makes an unanswered agreement free: a peer on an older
+ * build that never replies costs nothing today. (An earlier revision of this line said
+ * `wire-content-hash.ts` is untouched — that is no longer true. Part B1 shipped the RECEIVE half:
+ * it reads a `content_hash_alg` off the frame and can verify a salted hash. The outbound half, part
+ * B2, is what moves the send sites onto `saltedContentHash` and holds the first send until the salt
+ * is agreed — and from that moment an unanswered agreement IS a session that cannot send.)
+ *
+ * ─── The frame, and why exactly one field is present ───────────────────────────────────────────
+ *
+ * One frame type carries the whole agreement, and WHICH FIELD IS PRESENT IS THE SENDER'S STATE:
+ *
+ *   `contribution` (32 bytes) → "I hold no salt for this session. Here is my half."
+ *   `fingerprint`  (8 bytes)  → "I already hold a salt. Here is a one-way digest of it."
+ *
+ * Never both, never neither. That is not tidiness: a peer that sends both is claiming to be in two
+ * states at once, and whichever field this machine read first would decide the outcome — a sender
+ * that can pick the branch is a sender that can steer the agreement. Both malformed shapes are
+ * refused rather than resolved.
+ *
+ * ─── The four combinations ─────────────────────────────────────────────────────────────────────
+ *
+ *                          peer sent CONTRIBUTION            peer sent FINGERPRINT
+ *   we hold NO salt        derive, persist, announce ours    REPAIR: re-offer our half
+ *   we HOLD a salt         REPAIR: re-offer our half         compare → confirmed | ✗ MISMATCH
+ *                          (✗ DIVERGENT if our half is gone)
+ *
+ * ⚠️ THE OFF-DIAGONAL CELLS USED TO FREEZE THE SESSION, AND THAT WAS WRONG — review F1, and the
+ * justification written here for it was **false**.
+ *
+ * It said the salt "cannot be repaired by retrying… neither party keeps the inputs once it has the
+ * output." We DO keep our input: `#saltContributions` holds our half for the life of the session
+ * node, and `deriveSessionSalt` sorts its two arguments — so a side that holds a salt can simply
+ * re-send its own half and the peer derives **byte-identical** bytes.
+ *
+ * That mattered because the off-diagonal is not the exotic state the old text described. It is
+ * reached by ANY of:
+ *   - one side's connect-time announce failing (`#sendSaltFrame` logs and gives up until the next
+ *     connect) while the other's lands;
+ *   - one side's persist failing, so it re-offers a contribution while the other has stored one;
+ *   - a teardown between the two derives.
+ * **A single dropped frame therefore destroyed a live session** — a refusal that breaks availability
+ * to defend a value nothing has consumed yet. Repairing costs one frame and always converges.
+ *
+ * The cell is genuinely unrepairable in exactly one case, and the code now CHECKS it rather than
+ * assuming it: we hold a salt read back from the row, and our half is **gone** — evicted by a
+ * teardown, or never in this process at all after a restart. `ownContribution` is `null` there, and
+ * only there, because the caller never mints a fresh half for a session that already has a salt.
+ * Minting one would be worse than freezing: the peer would derive a DIFFERENT salt from it and both
+ * sides would believe they had agreed.
+ *
+ * ─── Why a refusal, and why it has to be loud ──────────────────────────────────────────────────
+ *
+ * Decision #10 exists because a salt disagreement is the least debuggable failure this system can
+ * produce, and `wire-content-hash.ts`'s own header says why: the send SUCCEEDS, the sender's log
+ * says the frame left, and the receiver discards before anything about it is logged. It cost two
+ * live daemons to find once. Every branch here therefore ends in a decision — converge or stop —
+ * and never in "keep going and see".
+ *
+ * ─── Where the named reasons live, and why NOT in `refusal-reasons.ts` ─────────────────────────
+ *
+ * An earlier acceptance criterion of mine said to add these to `REFUSAL_REASONS`. That was wrong,
+ * and following it would have put them somewhere no caller could raise them: `recordRefusal`
+ * refuses an inbound session REQUEST — the decision made *before* a session exists, whose audience
+ * is `cello_inbox` and whose guidance is written for someone deciding whether to accept a stranger.
+ * A salt disagreement happens on an ESTABLISHED session, mid-flight, and its response is to tear
+ * that session down. Different moment, different reader, different verb.
+ *
+ * The shape is copied on purpose, because the shape is the part that was right: a CLOSED set of
+ * reasons plus a TOTAL guidance map, so a reason cannot be added without something for the operator
+ * to do. `refusal-reasons.ts` records what a free-form `reason: string` permitted — a new code
+ * slipping past every test in the milestone's own guard file — and this file inherits that lesson
+ * without inheriting its union.
+ */
+import { deriveSessionSalt, saltFingerprint, SALT_CONTRIBUTION_BYTES } from "@cello-protocol/crypto";
+import { extractErrorMessage } from "./error-message.js";
+function isAllZero(b) {
+    let acc = 0;
+    for (const x of b)
+        acc |= x;
+    return acc === 0;
+}
+/**
+ * WHY a side cannot adopt — a wire value, so it is a named constant rather than a literal typed out
+ * at each site. Two refusals reach the same terminal state and want different operator responses:
+ * `already_hashing` is the session working as designed and the fix is to start a new one;
+ * `frontier_unreadable` is local storage trouble and starting a new session will not fix it.
+ */
+export const SALT_ADOPTION_LABELS = {
+    ALREADY_HASHING: "already_hashing",
+    FRONTIER_UNREADABLE: "frontier_unreadable",
+    PEER_CLOSED_FIRST: "peer_closed_first",
+    /**
+     * The two sides cannot converge and both must stop — 006-CRYPTO finding 1.
+     *
+     * We hold no salt, the peer holds one, and it has answered our half with its fingerprint twice.
+     * A latched salt-holder never re-offers its half, so we can never derive; without this the two
+     * sides repair at each other for the life of the session.
+     *
+     * Closing adoption rather than freezing, because nothing has been hashed under the salt and there
+     * are no sender salts yet: Decision #8's terminal state is that both sides stay unsalted and both
+     * KNOW, which is exactly as verifiable as every session shipped before the salt existed. Freezing
+     * a healthy conversation to defend a value nothing has consumed is the defect review F1 removed.
+     */
+    EXCHANGE_STALLED: "exchange_stalled",
+};
+/** The CLOSED set of reasons a salt disagreement stops a session. */
+export const SALT_FREEZE_REASONS = {
+    /** Both sides hold a salt and the digests differ. */
+    FINGERPRINT_MISMATCH: "salt_fingerprint_mismatch",
+    /** We hold a salt and our own half is gone, so the peer cannot be brought back to it. */
+    STATE_DIVERGENT: "salt_state_divergent",
+    /** The peer's contribution was all-zero, the wrong length, or our own echoed back. */
+    CONTRIBUTION_DEGENERATE: "salt_contribution_degenerate",
+    /**
+     * OUR OWN half is degenerate — a broken or patched random source on THIS machine.
+     *
+     * Separate from `CONTRIBUTION_DEGENERATE` because the two send the operator to different places,
+     * and collapsing them undid a fix one layer down (review F3). `session-salt.ts` deliberately
+     * refuses our own all-zero half with *"this is a LOCAL defect… not something the peer did"*,
+     * precisely so the operator whose machine is broken is not told their counterparty did it — and
+     * mapping both throws to one peer-blaming reason handed that accusation straight back.
+     */
+    OWN_CONTRIBUTION_DEGENERATE: "salt_own_contribution_degenerate",
+    /** The frame carried both fields or neither, so the sender's state is unreadable. */
+    FRAME_MALFORMED: "salt_frame_malformed",
+};
+/**
+ * What the operator should DO, per reason. Typed as a TOTAL map, so a reason added without guidance
+ * fails to compile.
+ *
+ * ⚠️ EVERY VERB HERE MUST BE ONE THE READER CAN PERFORM. A frozen session is not retryable — that
+ * is what freezing means — so none of these may say "try again on this session". The move is always
+ * a NEW session, and for the divergent cases it is worth saying plainly that nothing is broken and
+ * nobody did anything wrong: one side's record simply did not survive.
+ */
+export const SALT_FREEZE_GUIDANCE = {
+    [SALT_FREEZE_REASONS.FINGERPRINT_MISMATCH]: "STOPPED ON PURPOSE. You and your counterparty ended up with different values for this " +
+        "session's content salt, so from here every message either of you sent would be discarded by " +
+        "the other with nothing said about it. Nothing was lost and nothing was tampered with. Two " +
+        "things cause it: one of you is running an older build, or one side restarted midway through " +
+        "opening the session and came back without the half it had already sent. Check the log for " +
+        "session.salt.persist.failed or session.salt.announce.failed on either machine — if you see " +
+        "one, it was the restart and there is nothing to fix. Otherwise compare versions. Either way, " +
+        "start a new session.",
+    [SALT_FREEZE_REASONS.STATE_DIVERGENT]: "STOPPED ON PURPOSE. This side holds the session's content salt but no longer holds the random " +
+        "half it was built from, so your counterparty — who is starting the agreement over — cannot be " +
+        "brought back to the same value. This happens when a daemon restarts after the salt was stored " +
+        "but before both sides had confirmed it. Nothing is broken and neither of you did anything " +
+        "wrong. Start a new session; the transcript of this one is unaffected and still readable.",
+    [SALT_FREEZE_REASONS.OWN_CONTRIBUTION_DEGENERATE]: "STOPPED ON PURPOSE, AND THE PROBLEM IS ON THIS MACHINE — not your counterparty's. The random " +
+        "half this side generated for the session's content salt came out empty or the wrong size, " +
+        "which means the random source this daemon is using is broken or has been modified. Do not " +
+        "raise this with your counterparty; they did nothing. Check this machine's CELLO build and its " +
+        "system random source before opening another session, because every session it opens has the " +
+        "same defect.",
+    [SALT_FREEZE_REASONS.CONTRIBUTION_DEGENERATE]: "STOPPED ON PURPOSE. Your counterparty's half of this session's content salt was empty, the " +
+        "wrong size, or a copy of your own. Accepting it would have meant one side alone deciding a " +
+        "value whose entire purpose is that neither side can — and the effect would be that anyone " +
+        "relaying your messages could confirm guesses at what short ones said. This can be a broken or " +
+        "modified build on their side, so raise it with them OUT OF BAND before opening a new session.",
+    [SALT_FREEZE_REASONS.FRAME_MALFORMED]: "STOPPED ON PURPOSE. Your counterparty's salt-agreement message did not say which state they " +
+        "were in — it claimed both at once, or neither — so there was no way to answer it that was not " +
+        "a guess. Nothing was accepted. A build mismatch is the ordinary cause; confirm what they are " +
+        "running, then start a new session.",
+};
+/**
+ * The longest `adoptionClosed` label this build will read — 006-CRYPTO finding 6.
+ *
+ * Every label CELLO sends is under twenty characters. The cap is not about memory; it is about a
+ * peer-chosen string reaching an operator inside a sentence that reads as CELLO's own diagnosis.
+ */
+export const SALT_ADOPTION_LABEL_MAX = 64;
+const KNOWN_ADOPTION_LABELS = new Set(Object.values(SALT_ADOPTION_LABELS));
+/** Space, the lowest printable code point. Anything below it is a control character. */
+const FIRST_PRINTABLE = 0x20;
+/** DEL, and the C1 control block that follows it. */
+const DEL = 0x7f;
+const LAST_C1 = 0x9f;
+/**
+ * RENDER A PEER-SUPPLIED LABEL — 006-CRYPTO finding 6.
+ *
+ * The peer chooses these bytes, and they were interpolated straight into a `detail` the operator
+ * reads. Measured: a label containing newlines produced a detail carrying what looked like a second
+ * log line — `the counterparty cannot adopt a salt for this session (` then a blank line, then
+ * `session.salt.agreed reason=ok` — so a counterparty could write text that reads as CELLO
+ * reporting agreement at the exact moment it reported the opposite.
+ *
+ * A KNOWN label is rendered verbatim: it is our own vocabulary and the operator should see it. An
+ * unknown one is marked unrecognised and stripped of control characters, because the operator still
+ * needs to see WHAT was sent — `PEER_CLOSED_UNSPECIFIED`'s guidance sends them here to read it — but
+ * must not read it as our conclusion. Sanitising rather than dropping: a label we refuse to show at
+ * all is a diagnosis nobody can complete.
+ *
+ * Filtered by CODE POINT rather than by a regex character class, deliberately. Writing the class
+ * needs control characters in the source, and a raw NUL in a `.ts` file makes `grep` classify the
+ * whole file as binary and report no matches in it — which reads exactly like "this symbol is not
+ * used anywhere". This file paid for that lesson while the fix was being written.
+ */
+export function renderPeerAdoptionLabel(label) {
+    if (KNOWN_ADOPTION_LABELS.has(label))
+        return label;
+    const printable = Array.from(label)
+        .map((ch) => {
+        const cp = ch.codePointAt(0) ?? 0;
+        return cp < FIRST_PRINTABLE || (cp >= DEL && cp <= LAST_C1) ? " " : ch;
+    })
+        .join("")
+        .slice(0, SALT_ADOPTION_LABEL_MAX);
+    return `unrecognised reason, as sent: "${printable}"`;
+}
+function digestsEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    return Buffer.from(a).equals(Buffer.from(b));
+}
+/**
+ * The frame this side should send, given its own state. Called on every counterparty connect, so it
+ * must be a pure function of the state and NOT mint anything.
+ *
+ * ⚠️ `ownContribution` IS MINTED ONCE PER SESSION BY THE CALLER, and this is where that requirement
+ * is visible. A fresh contribution per reconnect would have both sides re-deriving against a moving
+ * value, the fingerprints would never settle, and the symptom — a session that reconnects and still
+ * disagrees — reads as a network fault rather than a bug here.
+ */
+export function ownSaltFrame(state) {
+    if (state.ownSalt)
+        return { fingerprint: saltFingerprint(state.ownSalt) };
+    /**
+     * `null` — nothing to announce, and the caller must say so rather than invent a half.
+     *
+     * Review F15: `ownContribution` was typed non-null here, so the daemon satisfied it by calling
+     * the MINTING accessor — which minted for a session that already held a salt, on the one state
+     * `null` exists to name. Taking the nullable type is what forces the caller to pass `#saltState`
+     * and makes minting a decision rather than a side effect of a parameter list.
+     *
+     * Reaching here at all means we hold neither a salt nor a half, which `#saltState` does not
+     * produce; it is a real defect if seen, not a state to paper over with a fresh contribution.
+     */
+    if (!state.ownContribution)
+        return null;
+    return { contribution: state.ownContribution };
+}
+/**
+ * `isTimingSafeEqual` was the name; constant time is NOT required here and never was.
+ *
+ * Review F13: nothing pinned the constant-time property and nothing needs it — both operands are
+ * 8-byte one-way digests that the two sides have already exchanged in the clear, so there is no
+ * secret for a timing signal to leak. A name asserting a property nothing checks is the same defect
+ * as a comment asserting one, so the name says what the function does instead.
+ *
+ * The LENGTH check is the load-bearing half and is pinned by a test: a differing width IS a
+ * disagreement, and comparing a common prefix would let two sides that agree on half their digest
+ * call it a match.
+ */
+/**
+ * OUR OWN half, checked before it is used — review F3.
+ *
+ * `deriveSessionSalt` refuses four conditions and TWO OF THEM ARE LOCAL: our own wrong length and
+ * our own all-zero. A single `catch` around it mapped all four to one peer-blaming reason, which
+ * handed the operator an out-of-band accusation of their counterparty for a broken RNG on their own
+ * machine — undoing, at the guidance layer, the exact fix `session-salt.ts` added for it.
+ *
+ * Checking here means the primitive's throw can only ever be about the PEER's half by the time it
+ * is caught. It also kills a mutant the tests could not see: swapping the two arguments in the
+ * derive call left every reason code and every message-regex passing while every degenerate refusal
+ * blamed the wrong party.
+ */
+function ownHalfDefect(ownContribution) {
+    if (ownContribution.length !== SALT_CONTRIBUTION_BYTES) {
+        return `our own salt contribution is ${ownContribution.length} bytes rather than ${SALT_CONTRIBUTION_BYTES}. This is a LOCAL defect, not something the peer did.`;
+    }
+    if (isAllZero(ownContribution)) {
+        return "our own salt contribution is all zeros, so this side contributed nothing. This is a LOCAL defect — a broken or patched random source — not something the peer did.";
+    }
+    return null;
+}
+/**
+ * Decide what an inbound salt frame means. See the four-cell table in the header.
+ *
+ * `ownContribution` is `null` ONLY in the one state that cannot be repaired: we hold a salt read
+ * back from the row and the half it was built from is gone. The caller never mints a fresh half for
+ * a session that already has a salt — minting one would let us "repair" the peer onto a DIFFERENT
+ * salt, with both sides believing they had agreed.
+ */
+export function onPeerSaltFrame(state) {
+    const hasContribution = state.frame.contribution instanceof Uint8Array;
+    const hasFingerprint = state.frame.fingerprint instanceof Uint8Array;
+    const hasClosed = typeof state.frame.adoptionClosed === "string";
+    /**
+     * THE PEER HAS CLOSED ADOPTION — terminal for both, and it takes precedence over every other
+     * branch, including the malformed-shape check below. A peer that can never adopt is not offering a
+     * contribution and not comparing a fingerprint; there is nothing left to agree.
+     *
+     * We answer once IFF we have not already closed ourselves, so the exchange ends rather than
+     * echoing. Both sides then hold no salt and both KNOW it, which is the whole point — the failure
+     * this replaces was two sides reaching opposite verdicts with nothing on the wire saying so.
+     */
+    if (hasClosed) {
+        return {
+            action: "adoption_closed",
+            // NOT "they have already hashed content" — that is only one of their two reasons, and the
+            // label they sent says which. Asserting the wrong one about a counterparty is how an operator
+            // ends up asking a peer to change something that was never the problem.
+            // RENDERED, not interpolated — 006-CRYPTO finding 6. The peer chooses this string, and it is
+            // landing inside a sentence the operator reads as ours.
+            detail: `the counterparty cannot adopt a salt for this session (${renderPeerAdoptionLabel(state.frame.adoptionClosed)}); neither side will use one`,
+            ...(state.ownAdoption?.closed ? {} : { announce: { adoptionClosed: SALT_ADOPTION_LABELS.PEER_CLOSED_FIRST } }),
+        };
+    }
+    /**
+     * WE have closed adoption. Say so instead of deriving, whatever the peer sent — otherwise we
+     * refuse silently, they adopt, and every message they send afterwards is unverifiable here.
+     *
+     * ⚠️ `&& !state.ownSalt` — `DOD-M15-SALTSPLIT-1` review pass 1, HIGH-1. WITHOUT IT THIS BRANCH
+     * ANNOUNCES THAT WE HOLD NO SALT WHILE WE ARE HOLDING ONE.
+     *
+     * "Adoption closed" means *"I cannot adopt a NEW salt"*. It was being tested before `ownSalt`, so
+     * a side that had agreed salt S and then leafed a message answered a matching `fingerprint(S)`
+     * with `adoption_closed: already_hashing` — a frame the receiver reads as *"the peer has none"*.
+     * Once `SALTSPLIT-1` taught the receiver to discard on that frame, the receiver erased **its own
+     * copy of the same salt**, and a working session became one where every message is refused. The
+     * fix made things worse than the defect on that path, which is why the correction is here at the
+     * producer and not as a new check at each receiver.
+     *
+     * The rule underneath it: **a side that already HOLDS a salt has nothing to adopt, so the adoption
+     * question does not apply to it at all.** It falls through to the `state.ownSalt` block below,
+     * which answers a contribution with a repair and a fingerprint with match-or-mismatch — the
+     * correct answers for a salt-holder, and the ones it could never reach before.
+     *
+     * Deliberately NOT moved above the malformed-frame guard: the `ownSalt` block reads
+     * `hasContribution`/`hasFingerprint` and relies on exactly one of them being set.
+     *
+     * A legacy peer on an older build can still send the misleading frame, and a fixed side would
+     * still discard on it. Accepted rather than defended against with a wire field: we are pre-launch
+     * with no external installs, and the standing rule here is to re-derive against an empty database
+     * rather than carry compatibility for a state nobody is in.
+     */
+    if (state.ownAdoption?.closed && !state.ownSalt) {
+        return {
+            action: "adoption_closed",
+            // The LABEL and the WHY, in that order: the label is the word an operator scans for, the why
+            // is the counts (or the error) behind it. A detail carrying only counts is unreadable, and one
+            // carrying only the label cannot be checked against the session it describes.
+            detail: `this side cannot adopt a salt for this session (${state.ownAdoption.label}: ${state.ownAdoption.why}), so no salt is adopted; telling the peer so they do not adopt one either`,
+            announce: { adoptionClosed: state.ownAdoption.label },
+        };
+    }
+    if (hasContribution === hasFingerprint) {
+        return {
+            action: "freeze",
+            reason: SALT_FREEZE_REASONS.FRAME_MALFORMED,
+            detail: hasContribution
+                ? "the peer's salt frame carried BOTH a contribution and a fingerprint, so it claims to hold a salt and to be starting fresh at the same time; whichever field we read first would decide the outcome"
+                : "the peer's salt frame carried neither a contribution nor a fingerprint, so it says nothing about which state the peer is in",
+        };
+    }
+    if (state.ownSalt) {
+        if (hasContribution) {
+            // THE REPAIR (review F1). The peer is starting over; ours is a one-way function of two halves
+            // and `deriveSessionSalt` SORTS them, so re-sending our half lands them on byte-identical
+            // bytes. Freezing here destroyed live sessions over a single dropped frame.
+            if (!state.ownContribution) {
+                return {
+                    action: "freeze",
+                    reason: SALT_FREEZE_REASONS.STATE_DIVERGENT,
+                    detail: "we hold this session's salt but no longer hold the half it was built from — a teardown or a restart evicted it — so the peer, who is starting over, cannot be brought back to the same value. " +
+                        "Offering a freshly minted half instead would put them on a DIFFERENT salt with both sides believing they had agreed.",
+                };
+            }
+            if (state.alreadyRepairedAgainstPeerHalf) {
+                // TERMINATION (review F14). We have already sent our half in answer to this exact one; the
+                // peer is not short of it. Answering with our fingerprint instead makes their next step
+                // terminal — `confirmed` or `FINGERPRINT_MISMATCH` — instead of another contribution.
+                return {
+                    action: "repair",
+                    frame: { fingerprint: saltFingerprint(state.ownSalt) },
+                    detail: "we have already answered this exact peer half with ours, so a second identical repair would loop; sending our fingerprint instead moves the peer to a terminal answer",
+                };
+            }
+            return {
+                action: "repair",
+                frame: { contribution: state.ownContribution },
+                detail: "the peer is starting the agreement over; re-sending our half lands them on the salt we already hold",
+            };
+        }
+        if (digestsEqual(saltFingerprint(state.ownSalt), state.frame.fingerprint)) {
+            return { action: "confirmed" };
+        }
+        return {
+            action: "freeze",
+            reason: SALT_FREEZE_REASONS.FINGERPRINT_MISMATCH,
+            // BOTH DIGESTS IN HEX (review F5). This printed only lengths, so in the ordinary case — two
+            // 8-byte digests that differ — the operator was told "ours is 8 bytes, theirs was 8", which
+            // reads as an equality. Both values are one-way, public, and already crossed the wire.
+            detail: `the peer's salt fingerprint does not match ours: ours ${Buffer.from(saltFingerprint(state.ownSalt)).toString("hex")}, ` +
+                `theirs ${Buffer.from(state.frame.fingerprint).toString("hex")}. Every message from here would be discarded unread by one side or the other.`,
+            // The peer holds everything needed to run this same comparison and has not been given our
+            // side of it. Without this it learns nothing — the session simply stops answering.
+            notifyPeer: { fingerprint: saltFingerprint(state.ownSalt) },
+        };
+    }
+    // From here we hold no salt, so we are going to use our own half — check it before the primitive
+    // does, so a local defect cannot be reported as the peer's (review F3).
+    if (!state.ownContribution) {
+        return {
+            action: "freeze",
+            reason: SALT_FREEZE_REASONS.OWN_CONTRIBUTION_DEGENERATE,
+            detail: "this side holds neither a salt nor a contribution for the session, so it has nothing to agree with",
+        };
+    }
+    const localDefect = ownHalfDefect(state.ownContribution);
+    if (localDefect) {
+        return { action: "freeze", reason: SALT_FREEZE_REASONS.OWN_CONTRIBUTION_DEGENERATE, detail: localDefect };
+    }
+    if (hasFingerprint) {
+        /**
+         * TERMINATION FOR THE SALTLESS SIDE — 006-CRYPTO finding 1, and it is F14's missing mirror.
+         *
+         * We have already answered this exact fingerprint with our half. A salt-holder that has latched
+         * our half (F14) answers every further offer with its fingerprint and NEVER re-offers its own —
+         * so we can never derive, and repairing again just buys another round trip. Two healthy daemons
+         * reach this after one failed persist plus a reconnect, and then trade frames for the life of
+         * the session, one new stream and one INFO line each per iteration.
+         *
+         * Closing adoption rather than freezing: nothing has been hashed under a salt on this side, no
+         * send site consumes one yet, and Decision #8's terminal state for "a side that cannot adopt" is
+         * that BOTH stay unsalted and both KNOW. Freezing a working conversation to defend a value
+         * nothing has consumed is precisely the defect review F1 removed.
+         */
+        if (state.alreadyRepairedAgainstPeerFingerprint) {
+            return {
+                action: "adoption_closed",
+                detail: "we hold no salt and have already answered this exact peer fingerprint with our half; a peer that holds a salt does not re-offer its own, " +
+                    "so this side can never derive it and repairing again would loop. Neither side will use a salt for this session.",
+                announce: { adoptionClosed: SALT_ADOPTION_LABELS.EXCHANGE_STALLED },
+            };
+        }
+        // THE MIRROR REPAIR. They hold a salt, we do not. Re-offering our half is what prompts them to
+        // send theirs back, and then we derive the value they already have. The FIRST one always
+        // happens — the latch above fires only on a repeat, or a saltless side would never ask at all.
+        return {
+            action: "repair",
+            frame: { contribution: state.ownContribution },
+            detail: "the peer already holds a salt and we do not; re-offering our half is what asks them for theirs",
+        };
+    }
+    try {
+        // The primitive owns every rule about the PEER's half — length, all-zero, reflection — and owns
+        // the WORDING too. Its refusals explain what a zero contribution means for both parties;
+        // replacing that with a code of our own would be exit-point substitution (Invariant 2),
+        // destroying the only explanation that exists at the only moment anyone will read it. Our own
+        // half was cleared above, so anything thrown here is about theirs.
+        const salt = deriveSessionSalt(state.ownContribution, state.frame.contribution);
+        return { action: "derive_and_announce", salt, fingerprint: saltFingerprint(salt) };
+    }
+    catch (err) {
+        return {
+            action: "freeze",
+            reason: SALT_FREEZE_REASONS.CONTRIBUTION_DEGENERATE,
+            detail: extractErrorMessage(err),
+        };
+    }
+}
+//# sourceMappingURL=session-salt-agreement.js.map

package/dist/session-salt-agreement.js.map

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