@cello-protocol/daemon 0.0.227 → 0.0.228

package/dist/sealed-leaf-set.js

@@ -0,0 +1,122 @@
+/**
+ * THE LEAF SET THE DIRECTORY NOTARIZED — recovered from the seal frame, checked against the signed
+ * root, and kept so a message can later be proved to sit under it.
+ *
+ * ─── WHY THIS EXISTS AND WHY THE LOCAL TREE CANNOT DO THE JOB ─────────────────────────────────
+ *
+ * The daemon's `SessionTree` is NOT the tree the certified root covers, and the difference is not a
+ * rounding error:
+ *
+ *   - the certified root is `merkleRoot` over **every** leaf's content hash in the relay's canonical
+ *     order, **control leaves included** (`directory-node.ts` — "THE CERTIFIED ROOT —
+ *     client-reproducible, and the one every signature below binds");
+ *   - `SessionTree` holds **content leaves only**. Nothing appends a SEAL ctrl leaf to it —
+ *     `submitSealLeaf` deliberately computes its root without mutating the durable tree, and the
+ *     inbound handler routes a counterparty ctrl leaf to the auto-acknowledge path, never to an
+ *     append.
+ *
+ * So `SessionTree.rootHex()` equals the SEAL payload's `final_root` (the root over the non-ctrl
+ * leaves, which is what each party signs), and it does **not** equal `sealed_root`. An audit path
+ * built from the local tree therefore lands on a root no certificate names — which is precisely the
+ * "a proof against your own root proves nothing" trap, reached by accident rather than by design.
+ *
+ * ─── WHAT MAKES THE STORED SET TRUSTWORTHY ────────────────────────────────────────────────────
+ *
+ * It is never stored on the directory's word. `recordSealedLeafSet` rebuilds the Merkle root over
+ * the hashes and refuses unless it reproduces the `sealed_root` the FROST signature covers. A
+ * directory that reorders, adds, drops or alters a single leaf produces a different root and the set
+ * is refused — so what lands on disk is, by construction, the leaf set the consortium signed.
+ *
+ * ⚠️ THE PARAGRAPH THAT USED TO SIT HERE OVERSTATED IT, and it is rewritten rather than deleted
+ * because it is what a future reader would have reasoned from. It said: *"the hashes come out of
+ * `structure1_cbor`, each leaf's participant-signed to-be-signed bytes; `reDeriveFrontiers` has
+ * already verified those signatures on this same array before we are called, so the content hashes
+ * are the senders' own, not the directory's."*
+ *
+ * **That holds on the BILATERAL path only.** There, `seal-coordinator.ts` returns outright when
+ * `reDeriveFrontiers` fails, so nothing unverified reaches this module. On the UNILATERAL path
+ * `checkUnilateralFrontier` deliberately never rejects — a forged or cross-session leaf yields
+ * `leaves_invalid`, the frontier is corrected DOWN to zero, and the seal proceeds rather than
+ * dead-ending — and those same leaves are then handed here.
+ *
+ * **What is true on EVERY path is the root comparison below, and it is the load-bearing one.** A
+ * leaf set only lands if it reproduces the FROST-signed `sealed_root`, so forged leaves cannot enter
+ * the store unless they hash to a root the consortium already signed. The per-leaf signature check is
+ * a second, path-dependent line of defence, not the guarantee — and stating it as the guarantee is
+ * exactly the shape `DOD-M15-CLAIM-COMMENTS-1` exists to catch.
+ *
+ * The hashes still come out of `structure1_cbor`, each leaf's to-be-signed bytes — that part was
+ * always accurate, and it is why the hashes are the ones a sender's signature would cover.
+ *
+ * Crypto refs: RFC 6962 §2.1 (Merkle hash trees).
+ */
+import { decodeStructure1 } from "@cello-protocol/protocol-types";
+import { rootOverLeafHashes } from "./inclusion-proof.js";
+/**
+ * Every leaf's content hash, hex, in the order the directory certified.
+ *
+ * Structure 1 TBS is `[version, content_hash, sender_pubkey, session_id, last_seen_seq, timestamp]`,
+ * plus `last_seen_hash` at index 6 on a v2 claim (020-ACKHASH). Index 1 is the content hash in both,
+ * and it is the same value the directory feeds to `buildMerkleTree`. Decoded here rather than taken
+ * from any other field so the hashes are the ones the sender's signature actually covers.
+ *
+ * Returns null on ANY undecodable or wrong-width leaf rather than skipping it. Skipping would build
+ * a SHORTER leaf set that still hashes to something, and that something would then be compared to
+ * the certified root — a comparison that fails for the right reason today and would silently start
+ * passing the moment a dropped leaf happened to be the last one.
+ */
+export function sealedLeafHashesFromSignedLeaves(leaves) {
+    // AN EMPTY SET IS NOT A LEAF SET — the guard belongs here, not in the caller that happens to have
+    // one. `[]` yields a root of sha256("") (RFC 6962 §2.1's empty tree), so a certificate whose root
+    // were ever that value would "verify" against zero leaves, be stored as zero rows, and log
+    // `leafCount: 0` as a success. Unreachable today only because `parseFrontierLeaves` filters empty
+    // arrays upstream — which is a property of the caller, not of this function.
+    if (leaves.length === 0)
+        return null;
+    const hashes = [];
+    for (const leaf of leaves) {
+        // `length < 2` before 020-ACKHASH, which read index 1 out of an array of ANY length — a shape
+        // this build cannot name would have contributed a leaf hash to a set compared against a
+        // certified root. An unnamed layout now returns null, exactly as an undecodable leaf does.
+        const s1 = decodeStructure1(leaf.structure1_cbor);
+        if (!s1.ok)
+            return null;
+        hashes.push(Buffer.from(s1.fields.contentHash).toString("hex"));
+    }
+    return hashes;
+}
+/** Why a candidate leaf set was not accepted as the notarized one. */
+export const SEALED_LEAF_SET_REASONS = {
+    /** A leaf's Structure 1 bytes did not decode, or carried no 32-byte content hash. */
+    LEAVES_MALFORMED: "sealed_leaves_malformed",
+    /** The Merkle root over these hashes is not the root the certificate is signed over. */
+    ROOT_DISAGREES: "sealed_leaves_root_disagrees",
+};
+/**
+ * Recover the certified leaf set from the seal frame's signed leaves, and prove it against the
+ * certified root before handing it back.
+ *
+ * The root comparison is the ONLY thing that makes the result usable, so it is not optional and not
+ * a warning: a set that does not reproduce `sealedRootHex` is refused outright.
+ */
+export function certifiedLeafSetFrom(leaves, sealedRootHex) {
+    const hashes = sealedLeafHashesFromSignedLeaves(leaves);
+    if (hashes === null) {
+        return {
+            ok: false,
+            reason: SEALED_LEAF_SET_REASONS.LEAVES_MALFORMED,
+            detail: `one of the ${leaves.length} signed leaves carried no decodable 32-byte content hash at Structure 1 index 1`,
+        };
+    }
+    const recomputed = rootOverLeafHashes(hashes);
+    const expected = sealedRootHex.toLowerCase();
+    if (recomputed !== expected) {
+        return {
+            ok: false,
+            reason: SEALED_LEAF_SET_REASONS.ROOT_DISAGREES,
+            detail: `${hashes.length} leaves hash to ${recomputed}, and the certificate is signed over ${expected}`,
+        };
+    }
+    return { ok: true, leafHashes: hashes };
+}
+//# sourceMappingURL=sealed-leaf-set.js.map

package/dist/sealed-leaf-set.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sealed-leaf-set.js","sourceRoot":"","sources":["../src/sealed-leaf-set.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG1D;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gCAAgC,CAAC,MAAmC;IAClF,kGAAkG;IAClG,kGAAkG;IAClG,2FAA2F;IAC3F,kGAAkG;IAClG,6EAA6E;IAC7E,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;QAC1B,8FAA8F;QAC9F,wFAAwF;QACxF,2FAA2F;QAC3F,MAAM,EAAE,GAAG,gBAAgB,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;QAClD,IAAI,CAAC,EAAE,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC;QACxB,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;IAClE,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,sEAAsE;AACtE,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,qFAAqF;IACrF,gBAAgB,EAAE,yBAAyB;IAC3C,wFAAwF;IACxF,cAAc,EAAE,8BAA8B;CACtC,CAAC;AASX;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAClC,MAAmC,EACnC,aAAqB;IAErB,MAAM,MAAM,GAAG,gCAAgC,CAAC,MAAM,CAAC,CAAC;IACxD,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,uBAAuB,CAAC,gBAAgB;YAChD,MAAM,EAAE,cAAc,MAAM,CAAC,MAAM,iFAAiF;SACrH,CAAC;IACJ,CAAC;IACD,MAAM,UAAU,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC9C,MAAM,QAAQ,GAAG,aAAa,CAAC,WAAW,EAAE,CAAC;IAC7C,IAAI,UAAU,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,uBAAuB,CAAC,cAAc;YAC9C,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,mBAAmB,UAAU,wCAAwC,QAAQ,EAAE;SACxG,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;AAC1C,CAAC"}

package/dist/send-claims.d.ts

@@ -0,0 +1,56 @@
+/**
+ * "Somebody is sending on this session RIGHT NOW" — the half a frontier check cannot cover.
+ *
+ * A send claims its session before it goes to the wire and releases it after. Between those two
+ * points the message exists nowhere a reader can see it: no leaf, no transcript row, nothing in the
+ * tree. Any check that asks "has anyone spoken here?" by reading state answers NO for the whole
+ * round trip, which on a slow link is seconds.
+ *
+ * It lived inside `session-content-handlers.ts` as a private map, where `cello_send` used it to stop
+ * two connections appending at the same frontier. It is out here because a SECOND reader now needs
+ * the same fact for a sharper reason: `away-inbox-oneshot.ts` decides whether to END a session, and
+ * "nobody has spoken" read at the wrong moment closes and seals a conversation the operator is in
+ * the middle of replying to.
+ *
+ * ⚠️ CREATED PER DAEMON AND PASSED IN — never a module-level singleton. Tests start several daemons
+ * in one process, and a shared map would let one daemon's in-flight send answer another's question.
+ */
+/**
+ * How long a claim is honored before a sibling may proceed anyway.
+ *
+ * `finally` covers throw and reject. It does NOT cover a promise that NEVER SETTLES, and
+ * `sendContent` awaits `node.newStream` and `stream.close` with no timeout or abort signal — only
+ * the relay submit is bounded. With an unbounded claim, one hung libp2p stream would refuse every
+ * sibling send on that conversation until the daemon restarted, behind guidance that says "wait a
+ * moment" forever. Trading a permanent outage for a small chance of a duplicate is the wrong way
+ * round: the defect is a bad conversation, the wedge is a dead one.
+ *
+ * Generous relative to the honest worst case (~30 s of bounded relay retries plus an unbounded
+ * stream tail), so it expires hangs rather than races.
+ */
+export declare const SEND_CLAIM_TTL_MS = 60000;
+export interface SendClaims {
+    /**
+     * A SENT message reached the wire and its transcript row did NOT land. The leaf is committed, so
+     * the conversation is intact; this side's readable copy is what is missing. Lives here because it
+     * is the same kind of fact as a claim — something true about this process's sends that no reader
+     * of the durable record can see — and both readers of this object need it.
+     */
+    noteRowMissing(agentName: string, sessionId: string): void;
+    /**
+     * True when this side is known to have said something the transcript cannot show. A reader asking
+     * "did a human speak here" must then answer "cannot tell", never "nobody spoke" — only one of
+     * those ends a session.
+     */
+    rowMissing(agentName: string, sessionId: string): boolean;
+    /** Claim the session for a send that is about to go to the wire. */
+    claim(agentName: string, sessionId: string): void;
+    /** Release it. Call from a `finally` so a throw cannot wedge the session into permanent refusal. */
+    release(agentName: string, sessionId: string): void;
+    /** When the live claim was made, or `undefined` if there is none within the TTL. */
+    claimedAt(agentName: string, sessionId: string): number | undefined;
+    /** Is a send on the wire for this session right now? */
+    held(agentName: string, sessionId: string): boolean;
+}
+export declare function createSendClaims(now?: () => number): SendClaims;
+//# sourceMappingURL=send-claims.d.ts.map

package/dist/send-claims.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"send-claims.d.ts","sourceRoot":"","sources":["../src/send-claims.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB,QAAS,CAAC;AAExC,MAAM,WAAW,UAAU;IACzB;;;;;OAKG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3D;;;;OAIG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1D,oEAAoE;IACpE,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClD,oGAAoG;IACpG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACpD,oFAAoF;IACpF,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACpE,wDAAwD;IACxD,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;CACrD;AAED,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAM,MAAiB,GAAG,UAAU,CAiBzE"}

package/dist/send-claims.js

@@ -0,0 +1,50 @@
+/**
+ * "Somebody is sending on this session RIGHT NOW" — the half a frontier check cannot cover.
+ *
+ * A send claims its session before it goes to the wire and releases it after. Between those two
+ * points the message exists nowhere a reader can see it: no leaf, no transcript row, nothing in the
+ * tree. Any check that asks "has anyone spoken here?" by reading state answers NO for the whole
+ * round trip, which on a slow link is seconds.
+ *
+ * It lived inside `session-content-handlers.ts` as a private map, where `cello_send` used it to stop
+ * two connections appending at the same frontier. It is out here because a SECOND reader now needs
+ * the same fact for a sharper reason: `away-inbox-oneshot.ts` decides whether to END a session, and
+ * "nobody has spoken" read at the wrong moment closes and seals a conversation the operator is in
+ * the middle of replying to.
+ *
+ * ⚠️ CREATED PER DAEMON AND PASSED IN — never a module-level singleton. Tests start several daemons
+ * in one process, and a shared map would let one daemon's in-flight send answer another's question.
+ */
+/**
+ * How long a claim is honored before a sibling may proceed anyway.
+ *
+ * `finally` covers throw and reject. It does NOT cover a promise that NEVER SETTLES, and
+ * `sendContent` awaits `node.newStream` and `stream.close` with no timeout or abort signal — only
+ * the relay submit is bounded. With an unbounded claim, one hung libp2p stream would refuse every
+ * sibling send on that conversation until the daemon restarted, behind guidance that says "wait a
+ * moment" forever. Trading a permanent outage for a small chance of a duplicate is the wrong way
+ * round: the defect is a bad conversation, the wedge is a dead one.
+ *
+ * Generous relative to the honest worst case (~30 s of bounded relay retries plus an unbounded
+ * stream tail), so it expires hangs rather than races.
+ */
+export const SEND_CLAIM_TTL_MS = 60_000;
+export function createSendClaims(now = Date.now) {
+    const claims = new Map();
+    const rowHoles = new Set();
+    // NUL-joined: neither an agent name nor a session id can contain it, so no pair of distinct
+    // (agent, session) can collide on one key.
+    const key = (agentName, sessionId) => `${agentName}\u0000${sessionId}`;
+    return {
+        claim(agentName, sessionId) { claims.set(key(agentName, sessionId), now()); },
+        release(agentName, sessionId) { claims.delete(key(agentName, sessionId)); },
+        claimedAt(agentName, sessionId) {
+            const at = claims.get(key(agentName, sessionId));
+            return at !== undefined && now() - at < SEND_CLAIM_TTL_MS ? at : undefined;
+        },
+        held(agentName, sessionId) { return this.claimedAt(agentName, sessionId) !== undefined; },
+        noteRowMissing(agentName, sessionId) { rowHoles.add(key(agentName, sessionId)); },
+        rowMissing(agentName, sessionId) { return rowHoles.has(key(agentName, sessionId)); },
+    };
+}
+//# sourceMappingURL=send-claims.js.map

package/dist/send-claims.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"send-claims.js","sourceRoot":"","sources":["../src/send-claims.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC;AA0BxC,MAAM,UAAU,gBAAgB,CAAC,MAAoB,IAAI,CAAC,GAAG;IAC3D,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IACnC,4FAA4F;IAC5F,2CAA2C;IAC3C,MAAM,GAAG,GAAG,CAAC,SAAiB,EAAE,SAAiB,EAAU,EAAE,CAAC,GAAG,SAAS,SAAS,SAAS,EAAE,CAAC;IAC/F,OAAO;QACL,KAAK,CAAC,SAAS,EAAE,SAAS,IAAI,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;QAC7E,OAAO,CAAC,SAAS,EAAE,SAAS,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3E,SAAS,CAAC,SAAS,EAAE,SAAS;YAC5B,MAAM,EAAE,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC;YACjD,OAAO,EAAE,KAAK,SAAS,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,iBAAiB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;QAC7E,CAAC;QACD,IAAI,CAAC,SAAS,EAAE,SAAS,IAAI,OAAO,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,SAAS,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC;QACzF,cAAc,CAAC,SAAS,EAAE,SAAS,IAAI,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;QACjF,UAAU,CAAC,SAAS,EAAE,SAAS,IAAI,OAAO,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;KACrF,CAAC;AACJ,CAAC"}

package/dist/session-assignment-parser.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Session assignment parsing.
+ *
+ * Decodes a raw CBOR-decoded `assignment` object (from a directory
+ * `session_assignment` frame) into a typed SessionAssignment. **Shape-validates ONLY** — it checks
+ * that a signature is 64 bytes, never that it is correct. The logic lives here in the daemon
+ * because the daemon must NOT import the core/client stack.
+ *
+ * ⚠️ DOD-M15-CLAIM-COMMENTS-1 — THIS HEADER NAMED A CHECK THAT DID NOT EXIST. It read: *"the
+ * FROST/single signature is verified downstream by the transport/session layer against the
+ * directory's pinned key."* There was no such site anywhere in the tree —
+ * `buildSessionEstablishmentTbs` was called to SIGN and nowhere to verify — so every caller of this
+ * parser was relying on a verification the sentence invented.
+ *
+ * Verification now exists, in exactly one place: `assignment-verify.ts`, called by
+ * `outbound-sessions.ts` on the initiator path, which REFUSES the session when it fails. Two
+ * corrections to the old sentence while the record is open: it is not verified by "the
+ * transport/session layer", and it is not "the directory's pinned key" — the FROST signature is by
+ * the INITIATOR's own threshold group key, which is why the verifier compares `signer_pubkey`
+ * against this agent's persisted `primaryPubkey` before trusting it.
+ *
+ * **The responder verifies it too** (`verifyInboundAssignment`, `DOD-M15-RESPONDER-VERIFY-1`), and
+ * 038-KEYBIND changed what that is worth on FIRST CONTACT. The old sentence here said the responder
+ * *"can only prove the signature holds over the assignment's own recomputed contents — which catches
+ * tampering but cannot authenticate a directory"*, and that was accurate: with no pin it verified
+ * against `signer_pubkey`, a field of the frame under verification.
+ *
+ * The frame now carries `participant_a_key_binding` — a signature by the INITIATOR's own K_local
+ * naming their group key. The responder checks that FIRST and verifies the threshold signature under
+ * the key it proved, so a directory can no longer name a group key of its choosing. What first
+ * contact still cannot tell you is whether `participant_a` is who you think: the identity key itself
+ * is the out-of-band value, and no field on this frame can vouch for it.
+ */
+import type { SessionAssignment } from "@cello-protocol/protocol-types";
+/**
+ * A dead field that arrived PRESENT-BUT-MALFORMED — `DOD-M15-DEAD-WIRE-FIELD-1` review F3.
+ *
+ * Tolerating these is right (nothing reads them, no signature covers them), but discarding the fact
+ * silently is not: this parse is the ONLY place in the system where evidence that a directory is
+ * emitting junk in them can exist, because no signature covers them and no consumer sees them.
+ *
+ * ABSENT is deliberately NOT reported. Once the bilateral half removes the field, absent is the
+ * designed normal case, and a signal that fires on the normal case is not a signal.
+ */
+export type ToleratedField = "participant.multiaddrs" | "participant.peer_id";
+/**
+ * Decode a raw CBOR-decoded object (frame["assignment"]) into a typed SessionAssignment.
+ * Returns null if any required field is missing or malformed.
+ */
+export declare function parseSessionAssignment(raw: Record<string, unknown>, 
+/**
+ * Called for each dead field that arrived PRESENT-BUT-MALFORMED. Optional so the parser keeps no
+ * logger dependency — it is a pure shape-validator, as its header says. Callers that have a
+ * logger (the inbound and outbound session paths) pass one; the rest are unaffected.
+ */
+onTolerated?: (field: ToleratedField) => void): SessionAssignment | null;
+export interface DiscoveryLookupResultParsed {
+    state: "online" | "offline" | "unknown_agent";
+    /** Non-empty only when state = "online" (length 1 until the k>1 homing knob lands). */
+    owningNodeIds: string[];
+}
+/**
+ * Decode a `discovery_lookup_result` frame. Shape-validates the 3-state answer; returns null on an
+ * unrecognized state (never fabricates one). A malformed/missing owning_node_ids defaults to [] — the
+ * negotiator treats online-with-no-owner as not-actionable (retry), never dials a fabricated node.
+ */
+export declare function parseDiscoveryLookupResult(frame: Record<string, unknown>): DiscoveryLookupResultParsed | null;
+/**
+ * Map a `discovery_lookup_error` frame's reason to a stable code. The directory returns this on a DB
+ * error during the lookup — a RETRYABLE condition, never a fabricated authoritative offline/unknown.
+ * Unknown reasons collapse to the same retryable "lookup_failed".
+ */
+export declare function discoveryLookupErrorReason(_frame: Record<string, unknown>): string;
+/**
+ * Map a raw `session_request_error` frame's reason to a stable negotiator reason code.
+ * Distinct cause → distinct code; an unknown reason collapses to directory_unreachable.
+ */
+export declare function sessionRequestErrorReason(frame: Record<string, unknown>): string;
+/**
+ * The guidance returned with a `session_request_error`. Most reasons share one sentence; the M16
+ * channel refusals get their own, because "ensure the counterparty is registered and online" is
+ * the wrong advice for an identity that is online and simply never converses.
+ */
+export declare function sessionRequestErrorGuidance(reason: string): string;
+/**
+ * The receiver's wire boundary, validated ONCE here so downstream code can never
+ * observe an invalid moniker. Absent ≠ invalid: an absent field is an older client
+ * (silent, rejected: false); a present-but-invalid value means the sender runs
+ * modified code (rejected: true — the caller logs `moniker.rejected`, never the raw
+ * value). Reject, never strip: the value is returned verbatim or null, never repaired.
+ */
+export declare function extractOfferedMoniker(raw: Record<string, unknown>): {
+    offeredMoniker: string | null;
+    rejected: boolean;
+    /** Set ONLY when rejected — WHAT was wrong, for moniker.rejected (never the raw value). */
+    reason?: "not_string" | "length" | "charset";
+};
+/**
+ * Defense-in-depth re-validation of the initiator's own outbound name. Returns
+ * undefined (field OMITTED from the wire, never an empty string) when there is no
+ * name or the stored value somehow fails validation.
+ */
+export declare function resolveOutboundMoniker(outboundName: string | null): string | undefined;
+//# sourceMappingURL=session-assignment-parser.d.ts.map

package/dist/session-assignment-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-assignment-parser.d.ts","sourceRoot":"","sources":["../src/session-assignment-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAcxE;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,GAAG,wBAAwB,GAAG,qBAAqB,CAAC;AAkE9E;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;AAC5B;;;;GAIG;AACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GAC5C,iBAAiB,GAAG,IAAI,CAqH1B;AAID,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,QAAQ,GAAG,SAAS,GAAG,eAAe,CAAC;IAC9C,uFAAuF;IACvF,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,2BAA2B,GAAG,IAAI,CAK7G;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAIlF;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAgChF;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAQlE;AAMD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IACnE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,EAAE,OAAO,CAAC;IAClB,2FAA2F;IAC3F,MAAM,CAAC,EAAE,YAAY,GAAG,QAAQ,GAAG,SAAS,CAAC;CAC9C,CAeA;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAGtF"}