instar 1.3.731 → 1.3.733

package/dist/core/ConversationRegistry.js

@@ -0,0 +1,1438 @@
+/**
+ * ConversationRegistry — durable, channel-agnostic conversation identity
+ * (docs/specs/durable-conversation-identity.md §3, increment 1: registry +
+ * crash-proof journal + eager mint foundation).
+ *
+ * The registry is the JOIN TABLE between canonical key (string), structured
+ * tuple, and minted NEGATIVE numeric id (§2). It is SPARSE: Telegram positive
+ * ids are NEVER registered (a positive id IS its own identity, forever);
+ * only minted (non-Telegram) conversations live here.
+ *
+ * Durability model (§3.3/§3.4 — the WAL rule):
+ *   - The id is assigned SYNCHRONOUSLY in-memory (probe included) against the
+ *     authoritative cache + reverse index, so the id RETURNED always equals
+ *     the id that will PERSIST — no misdelivery window.
+ *   - A PROBED or durable-binding-forced mint append+fsyncs ONE journal line
+ *     to `<stateDir>/conversation-registry.jsonl` (the §3.4 journal-path PIN:
+ *     stateDir ROOT, beside shared-state.jsonl — the one shape the deployed
+ *     BackupManager.expandGlob actually expands, R3-C4) BEFORE the id is
+ *     handed to the caller.
+ *   - A pure speculative non-probed mint appends its audit line WITHOUT fsync
+ *     (§3.4 fsync discipline; §8 audit completeness) — its candidate re-mints
+ *     deterministically for free after a crash.
+ *   - The O(N) full-store JSON snapshot (`<stateDir>/state/conversation-registry.json`)
+ *     is BATCHED off the hot path with a SIZE-ADAPTIVE interval (§3.4 —
+ *     the CommitmentTracker 2026-06-21 freeze precedent), and moves to an
+ *     off-loop write past the pinned trigger (>20k entries / >2MB).
+ *
+ * Increment scope note: the §3.5/§3.5.1 replication merge, the §3.5.2 bind-pin
+ * overlay WRITERS, and the §5.0(a) E1 dedup WRITERS land in their own §6.1
+ * increments. The journal op ENUM, replay application, and snapshot
+ * completeness for those ops ship NOW (§3.4 record framing is frozen), so a
+ * later increment's records — and a rollback across one — replay correctly.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { SafeFsExecutor } from './SafeFsExecutor.js';
+import { candidateIdForRoutingKey, canonicalKeyFor, parseCanonicalKey, routingKeyForTuple, SLACK_WORKSPACE_ID_RE, tupleForRoutingKey, tupleKeyFor, walkDisplacement, WORKSPACE_PLACEHOLDER, } from './conversationIdentity.js';
+/** §3.4 record framing — ONE self-contained JSON object per line. FROZEN op enum. */
+export const JOURNAL_OPS = [
+    'mint',
+    'alias',
+    'reachability',
+    'bind-pin',
+    'bind-release',
+    'ambiguous-send',
+    'send-retire',
+    'send-intent',
+    'send-intent-resolved',
+];
+/** §5.0(a) pinned E1 constants (R3-M1/R7-M2). Exported for the §10 tests. */
+export const AMBIGUOUS_DEDUP_TTL_MS = 604800000; // 7 days — safety bound ONLY, never the suppression mechanism (logical lane)
+export const CONTENT_HASH_DEDUP_WINDOW_MS = 900000; // 15 min — the fallback lane's WINDOW (mirrors the Telegram exact-duplicate window)
+/** §5.0(a) pathological TRIPWIRE, not a correctness bound (R4-M2/R5-minor-1):
+ *  reached-with-all-live raises ONE aggregated attention item while the new
+ *  entry is STILL journaled + retained — nothing is ever dropped. */
+export const AMBIGUOUS_SENDS_HARD_CAP = 1000;
+/** §5.1 reachability flap dampening (R3-minor). */
+export const REACHABILITY_FLAP_THRESHOLD = 3;
+export const REACHABILITY_FLAP_WINDOW_MS = 86400000; // 24h
+const ENTRY_CEILING = 50000; // §3.4 JSON-store design ceiling
+const ENTRY_THRESHOLD = 40000; // 80% of ceiling — the pinned tripwire (R3-minor)
+const FILE_BYTES_THRESHOLD = 8 * 1024 * 1024; // 80% of ~10MB
+const OFFLOOP_ENTRY_TRIGGER = 20000; // §3.4 pinned off-loop flush trigger
+const OFFLOOP_BYTES_TRIGGER = 2 * 1024 * 1024;
+const PENDING_MINT_MAX = 1000; // §3.6 pinned
+const BREAKER_MAX_TRACKED_CHANNELS = 512; // bounded budget-state map (§3.3, R3-minor)
+export class ConversationRegistry {
+    d;
+    snapshotPath;
+    journalPath;
+    // ── Authoritative in-memory cache + synchronous indexes (§3.4 1–2) ──
+    conversations = new Map(); // canonical key → entry
+    byId = new Map(); // id→entry reverse index
+    byTuple = new Map(); // tupleKey → entry
+    aliases = new Map(); // loserId → winnerId (one hop)
+    // ── Derived indexes (§3.4 3–5) — rebuilt at boot, maintained at assign time ──
+    reservedCanonicals = new Map(); // cand → owning tupleKey
+    displacedAssignments = new Map(); // offset → owning tupleKey (GLOBAL — R4-C1)
+    candClaimants = new Map(); // cand → claimant tupleKeys
+    // ── §5.0(a)/§3.5.2 journal-applied state (writers: §6.1 increment 2) ──
+    bindPins = new Map();
+    ambiguousSends = new Map();
+    sendIntents = new Map();
+    /** R9-minor-1: parseable send-intent lines with the lane field STRIPPED —
+     *  resolved toward RETRY at replay, surfaced once (never a suppressor). */
+    missingLaneIntents = 0;
+    /** §5.1 reachability flap tracking (in-memory, advisory — R3-minor). */
+    reachabilityFlips = new Map();
+    workspacePin = null;
+    // ── Journal state ──
+    seqCounter = 0;
+    snapshotHighWaterSeq = 0;
+    journalFd = null;
+    journalBytes = 0;
+    journalLines = 0;
+    /** Unknown-op skip-and-preserve set (R8-minor-2) → snapshot-flush SUSPENSION (R9-M1/R10-M1). */
+    unappliedUnknownOps = [];
+    // ── Snapshot batching ──
+    snapshotTimer = null;
+    snapshotDirty = false;
+    lastSnapshotBytes = 0;
+    batchDepth = 0; // adoption-pass batched-save window (§6.2)
+    flushInFlight = false;
+    // ── Breaker + degradation state ──
+    breakerWindows = new Map();
+    breakerEpisodes = 0;
+    pendingMints = new Map();
+    pendingMintDrops = 0;
+    // ── Observability ──
+    lastMintAt = null;
+    durabilityIncidents = 0;
+    snapshotQuarantinedAt = null;
+    journalQuarantinedAt = null;
+    adoptionState = null;
+    loaded = false;
+    constructor(deps) {
+        this.d = deps;
+        this.snapshotPath = path.join(deps.stateDir, 'state', 'conversation-registry.json');
+        this.journalPath = path.join(deps.stateDir, 'conversation-registry.jsonl');
+    }
+    now() {
+        return (this.d.now ?? (() => new Date()))();
+    }
+    log(line) {
+        try {
+            this.d.log?.(line);
+        }
+        catch {
+            /* observability never gates */
+        }
+    }
+    attention(dedupeKey, title, body) {
+        try {
+            this.d.onAttention?.(dedupeKey, title, body);
+        }
+        catch {
+            /* attention is observability — never gates identity or delivery */
+        }
+    }
+    recordingEnabled() {
+        try {
+            return this.d.isRecordingEnabled ? this.d.isRecordingEnabled() !== false : true;
+        }
+        catch {
+            return true;
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Boot: snapshot load + journal replay (§3.4 WAL crash-consistency contract)
+    // ─────────────────────────────────────────────────────────────────────────
+    /** Idempotent boot-time load: snapshot, then journal tail replay in global
+     *  `seq` order across rotated files (§6.2 recovery order 1–2). */
+    load() {
+        if (this.loaded)
+            return;
+        this.loaded = true;
+        try {
+            fs.mkdirSync(path.join(this.d.stateDir, 'state'), { recursive: true });
+        }
+        catch {
+            /* exists */
+        }
+        this.loadSnapshot();
+        this.replayJournal();
+        this.rebuildDerivedIndexes();
+        this.applyAliasAssignmentFilter(); // R6-M3 pin 2: the disjointness invariant holds at every BOOT fixpoint
+        this.convertOrphanedSendIntents(); // R8-M1 lane-scoped boot conversion (staged post-compose, fsynced before serving — R9-low-3/R10-minor-1)
+        this.pruneSendGuardState();
+        if (this.missingLaneIntents > 0) {
+            this.attention('conversation-registry:missing-lane-intent', 'Conversation registry: send-intent record(s) with a stripped lane field', `${this.missingLaneIntents} parseable send-intent journal record(s) carried no lane discriminator (R9-minor-1). Each was resolved toward RETRY (content-hash treatment — loss is never silent, never a suppressor). This indicates a serialization bug worth a look.`);
+        }
+        if (this.unappliedUnknownOps.length > 0) {
+            const first = this.unappliedUnknownOps[0];
+            const kinds = [...new Set(this.unappliedUnknownOps.map((u) => u.op))].join(', ');
+            this.attention('conversation-registry:unknown-op', 'Conversation registry journal holds records from a newer version', `${this.unappliedUnknownOps.length} journal record(s) with unrecognized op kind(s) [${kinds}] were skipped-and-preserved (version skew, not corruption — R8-minor-2). SNAPSHOT FLUSHING IS SUSPENDED (R9-M1/R10-M1): the on-disk snapshot stays the pre-skew one (high-water ${this.snapshotHighWaterSeq}, first unapplied seq ${first.seq}) until a recognizing version re-upgrades and replays them in position. Journal retention grows for the suspension's duration.`);
+        }
+        // Resolve the config workspace pin (source 1 — authoritative when present).
+        const configPin = this.readConfigPin();
+        if (configPin) {
+            this.workspacePin = { value: configPin, source: 'config', confirmedLocally: true };
+        }
+    }
+    readConfigPin() {
+        try {
+            const v = this.d.getConfigWorkspacePin?.();
+            return v && SLACK_WORKSPACE_ID_RE.test(v) ? v : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    loadSnapshot() {
+        if (!fs.existsSync(this.snapshotPath))
+            return;
+        try {
+            const raw = JSON.parse(fs.readFileSync(this.snapshotPath, 'utf-8'));
+            if (!raw || typeof raw !== 'object' || raw.version !== 1)
+                throw new Error('unrecognized snapshot shape');
+            this.snapshotHighWaterSeq = typeof raw.snapshotHighWaterSeq === 'number' ? raw.snapshotHighWaterSeq : 0;
+            this.seqCounter = this.snapshotHighWaterSeq;
+            if (raw.workspacePin && typeof raw.workspacePin.value === 'string')
+                this.workspacePin = raw.workspacePin;
+            for (const [key, entry] of Object.entries(raw.conversations ?? {})) {
+                if (!entry || typeof entry.id !== 'number' || !(entry.id < 0) || !Number.isSafeInteger(entry.id))
+                    continue; // id<0 clamp on every write (§3.3)
+                this.indexEntry(key, entry);
+            }
+            for (const [loser, winner] of Object.entries(raw.aliases ?? {})) {
+                const l = Number(loser);
+                if (Number.isSafeInteger(l) && l < 0 && typeof winner === 'number' && winner < 0)
+                    this.aliases.set(l, winner);
+            }
+            for (const [id, pin] of Object.entries(raw.bindPins ?? {})) {
+                const n = Number(id);
+                if (Number.isSafeInteger(n) && pin && Array.isArray(pin.tuple) && typeof pin.refcount === 'number') {
+                    this.bindPins.set(n, { tuple: pin.tuple, refcount: pin.refcount });
+                }
+            }
+            for (const [k, v] of Object.entries(raw.ambiguousSends ?? {})) {
+                if (v && typeof v.recordedAt === 'string') {
+                    this.ambiguousSends.set(k, {
+                        recordedAt: v.recordedAt,
+                        ...(v.lane === 'logical' || v.lane === 'content-hash' ? { lane: v.lane } : {}),
+                    });
+                }
+            }
+            for (const [k, v] of Object.entries(raw.sendIntents ?? {})) {
+                if (v && (v.lane === 'logical' || v.lane === 'content-hash') && typeof v.seq === 'number')
+                    this.sendIntents.set(k, v);
+            }
+            this.lastSnapshotBytes = fs.statSync(this.snapshotPath).size;
+        }
+        catch (err) {
+            // Corrupt-file quarantine-aside (§3.6 — the TopicPlacementPinStore
+            // pattern): preserve aside, ONE deduped attention item, rebuild from the
+            // journal (a journal-only rebuild replays every retained file from empty
+            // state in global seq order — §3.4 rotation note).
+            const aside = `${this.snapshotPath}.corrupt-${Date.now()}`;
+            try {
+                fs.renameSync(this.snapshotPath, aside);
+            }
+            catch {
+                /* best-effort — the report below still fires */
+            }
+            this.snapshotQuarantinedAt = this.now().toISOString();
+            this.snapshotHighWaterSeq = 0;
+            this.seqCounter = 0;
+            this.attention('conversation-registry:snapshot-corrupt', 'Conversation registry snapshot was corrupt — quarantined aside', `state/conversation-registry.json failed to parse (${err instanceof Error ? err.message : String(err)}) and was preserved at ${aside}. Rebuilding from the journal (§6.2 recovery order: backup restore is the PRIMARY path if the journal is also damaged).`);
+        }
+    }
+    /** Retained journal files in replay order: rotated (ascending epoch) then live. */
+    journalFiles() {
+        const dir = this.d.stateDir;
+        const base = path.basename(this.journalPath);
+        let names = [];
+        try {
+            names = fs.readdirSync(dir).filter((n) => n.startsWith(`${base}.`) && /\.\d+$/.test(n));
+        }
+        catch {
+            names = [];
+        }
+        const rotated = names
+            .map((n) => ({ n, epoch: Number(n.slice(base.length + 1)) }))
+            .sort((a, b) => a.epoch - b.epoch)
+            .map((x) => path.join(dir, x.n));
+        return fs.existsSync(this.journalPath) ? [...rotated, this.journalPath] : rotated;
+    }
+    replayJournal() {
+        const files = this.journalFiles();
+        if (files.length === 0)
+            return;
+        // Torn-tail handling (§3.4): a crash mid-append leaves the LIVE file's last
+        // line unterminated — only a fully-written, newline-terminated line is a
+        // committed record. The torn tail is DISCARDED (truncated) so later appends
+        // can never fuse onto an uncommitted fragment.
+        if (fs.existsSync(this.journalPath)) {
+            try {
+                const buf = fs.readFileSync(this.journalPath);
+                if (buf.length > 0 && buf[buf.length - 1] !== 0x0a) {
+                    const lastNl = buf.lastIndexOf(0x0a);
+                    fs.truncateSync(this.journalPath, lastNl === -1 ? 0 : lastNl + 1);
+                    this.log('[conversation-registry] discarded torn journal tail (uncommitted record)');
+                }
+            }
+            catch {
+                /* read failure falls through to the per-line handling below */
+            }
+        }
+        const records = [];
+        let halted = false;
+        for (const file of files) {
+            if (halted)
+                break;
+            let content;
+            try {
+                content = fs.readFileSync(file, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            const lines = content.split('\n');
+            for (let i = 0; i < lines.length; i++) {
+                const line = lines[i];
+                if (line.length === 0)
+                    continue;
+                let rec;
+                try {
+                    rec = JSON.parse(line);
+                    if (!rec || typeof rec.seq !== 'number' || typeof rec.op !== 'string')
+                        throw new Error('malformed record');
+                }
+                catch {
+                    // NON-tail corruption fails CLOSED (R7-minor-3): a newline-TERMINATED
+                    // line failing parse is a storage lie, never skipped — HALT the replay
+                    // into the quarantine-aside path + attention + durability incident.
+                    const aside = `${file}.corrupt-${Date.now()}`;
+                    try {
+                        fs.renameSync(file, aside);
+                    }
+                    catch {
+                        /* preserve best-effort */
+                    }
+                    this.journalQuarantinedAt = this.now().toISOString();
+                    this.durabilityIncidents++; // §3.7 broadened SQLite-migration trigger input
+                    this.attention('conversation-registry:journal-corrupt', 'Conversation registry journal corruption — replay halted', `A committed (newline-terminated) journal record in ${path.basename(file)} failed to parse at line ${i + 1}. The file was preserved aside at ${aside}; replay halted at that point (records before it are applied). This counts as a DURABILITY INCIDENT (§3.7 — evaluate the SQLite migration). Backup restore is the primary recovery path (§6.2).`);
+                    halted = true;
+                    break;
+                }
+                records.push({ rec, file });
+            }
+        }
+        records.sort((a, b) => a.rec.seq - b.rec.seq); // single global seq order (R3-M14)
+        let maxSeq = this.snapshotHighWaterSeq;
+        for (const { rec } of records) {
+            if (rec.seq > maxSeq)
+                maxSeq = rec.seq;
+            if (rec.seq <= this.snapshotHighWaterSeq)
+                continue; // snapshot already incorporates it
+            this.applyJournalRecord(rec);
+        }
+        // Boot counter resumes from the max seen — never 0/1 (R3-M14).
+        this.seqCounter = Math.max(this.seqCounter, maxSeq);
+        this.journalBytes = fs.existsSync(this.journalPath) ? fs.statSync(this.journalPath).size : 0;
+        this.journalLines = 0;
+        if (fs.existsSync(this.journalPath)) {
+            try {
+                const content = fs.readFileSync(this.journalPath, 'utf-8');
+                this.journalLines = content.length === 0 ? 0 : content.split('\n').filter((l) => l.length > 0).length;
+            }
+            catch {
+                /* count is rotation bookkeeping only */
+            }
+        }
+    }
+    /** Idempotent, seq-ordered application (§3.4) — safe to re-run any number of times. */
+    applyJournalRecord(rec) {
+        if (!JOURNAL_OPS.includes(rec.op)) {
+            // UNKNOWN-op tolerance (R8-minor-2): version skew, not corruption — skip
+            // the application, PRESERVE the line (append-only; never rewritten), and
+            // suspend snapshot flushing (R9-M1/R10-M1) until a recognizing version
+            // applies it. The deduped attention item is raised once after replay.
+            this.unappliedUnknownOps.push({ seq: rec.seq, op: rec.op });
+            return;
+        }
+        switch (rec.op) {
+            case 'mint': {
+                if (typeof rec.id !== 'number' || !(rec.id < 0) || !Array.isArray(rec.tuple))
+                    return;
+                const tuple = { platform: 'slack', channelId: rec.tuple[1], threadTs: rec.tuple[2] ?? null };
+                const tKey = tupleKeyFor(tuple);
+                const existing = this.byTuple.get(tKey);
+                if (existing) {
+                    // Re-apply / metadata upgrade (the `_`→teamId upgrade is journaled as
+                    // op:"mint" with the rewritten key — §3.1): same tuple, refreshed key.
+                    if (rec.key && rec.key !== canonicalKeyFor(tuple, existing.workspaceId)) {
+                        const parsed = parseCanonicalKey(rec.key);
+                        if (parsed && parsed.workspaceId !== existing.workspaceId) {
+                            this.conversations.delete(canonicalKeyFor(tuple, existing.workspaceId));
+                            existing.workspaceId = parsed.workspaceId;
+                            this.conversations.set(rec.key, existing);
+                        }
+                    }
+                    return; // idempotent
+                }
+                const parsed = rec.key ? parseCanonicalKey(rec.key) : null;
+                const entry = {
+                    id: rec.id,
+                    platform: 'slack',
+                    workspaceId: parsed?.workspaceId ?? WORKSPACE_PLACEHOLDER,
+                    channelId: tuple.channelId,
+                    threadTs: tuple.threadTs,
+                    mintedAt: rec.ts,
+                    mintedBy: rec.hlc?.node ?? 'unknown',
+                    origin: rec.origin ?? 'adopted-legacy-hash',
+                    reachability: 'ok',
+                    hlc: rec.hlc ?? { physical: Date.parse(rec.ts) || 0, logical: 0, node: 'unknown' },
+                };
+                this.indexEntry(canonicalKeyFor(tuple, entry.workspaceId), entry);
+                return;
+            }
+            case 'alias': {
+                if (typeof rec.id === 'number' && typeof rec.target === 'number')
+                    this.aliases.set(rec.id, rec.target);
+                return;
+            }
+            case 'reachability': {
+                if (typeof rec.id !== 'number' || !rec.reachability)
+                    return;
+                const entry = this.byId.get(rec.id);
+                if (entry)
+                    entry.reachability = rec.reachability;
+                return;
+            }
+            case 'bind-pin': {
+                if (typeof rec.id !== 'number' || !Array.isArray(rec.tuple))
+                    return;
+                const existing = this.bindPins.get(rec.id);
+                if (existing)
+                    existing.refcount = rec.refcount ?? existing.refcount + 1;
+                else
+                    this.bindPins.set(rec.id, { tuple: rec.tuple, refcount: rec.refcount ?? 1 });
+                return;
+            }
+            case 'bind-release': {
+                if (typeof rec.id !== 'number')
+                    return;
+                const pin = this.bindPins.get(rec.id);
+                if (!pin)
+                    return;
+                pin.refcount = rec.refcount ?? pin.refcount - 1;
+                if (pin.refcount <= 0)
+                    this.bindPins.delete(rec.id);
+                return;
+            }
+            case 'ambiguous-send': {
+                if (typeof rec.conversationId !== 'number' || !rec.logicalSendId)
+                    return;
+                this.ambiguousSends.set(`${rec.conversationId}|${rec.logicalSendId}`, {
+                    recordedAt: rec.ts,
+                    ...(rec.lane === 'logical' || rec.lane === 'content-hash' ? { lane: rec.lane } : {}),
+                });
+                this.sendIntents.delete(`${rec.conversationId}|${rec.logicalSendId}`);
+                return;
+            }
+            case 'send-retire': {
+                if (typeof rec.conversationId !== 'number' || !rec.logicalSendId)
+                    return;
+                this.ambiguousSends.delete(`${rec.conversationId}|${rec.logicalSendId}`);
+                this.sendIntents.delete(`${rec.conversationId}|${rec.logicalSendId}`);
+                return;
+            }
+            case 'send-intent': {
+                if (typeof rec.conversationId !== 'number' || !rec.logicalSendId)
+                    return;
+                // Malformed/unknown lane resolves toward RETRY (content-hash treatment)
+                // — R9-minor-1/R10-low-2 (loss-is-never-silent picks retry). Counted so
+                // the post-replay boot pass can raise ONE deduped attention item.
+                if (rec.lane !== 'logical' && rec.lane !== 'content-hash')
+                    this.missingLaneIntents++;
+                const lane = rec.lane === 'logical' ? 'logical' : 'content-hash';
+                this.sendIntents.set(`${rec.conversationId}|${rec.logicalSendId}`, { lane, seq: rec.seq });
+                return;
+            }
+            case 'send-intent-resolved': {
+                if (typeof rec.conversationId !== 'number' || !rec.logicalSendId)
+                    return;
+                this.sendIntents.delete(`${rec.conversationId}|${rec.logicalSendId}`);
+                return;
+            }
+        }
+    }
+    indexEntry(key, entry) {
+        this.conversations.set(key, entry);
+        this.byId.set(entry.id, entry);
+        this.byTuple.set(tupleKeyFor({ platform: 'slack', channelId: entry.channelId, threadTs: entry.threadTs }), entry);
+    }
+    /** Derived indexes 3–5 (§3.4) — pure functions of the entry set, rebuilt at boot. */
+    rebuildDerivedIndexes() {
+        this.reservedCanonicals.clear();
+        this.displacedAssignments.clear();
+        this.candClaimants.clear();
+        for (const entry of this.conversations.values()) {
+            const tuple = { platform: 'slack', channelId: entry.channelId, threadTs: entry.threadTs };
+            const cand = candidateIdForRoutingKey(routingKeyForTuple(tuple));
+            const tKey = tupleKeyFor(tuple);
+            let claimants = this.candClaimants.get(cand);
+            if (!claimants) {
+                claimants = new Set();
+                this.candClaimants.set(cand, claimants);
+            }
+            claimants.add(tKey);
+            if (entry.id === cand)
+                this.reservedCanonicals.set(cand, tKey);
+            else
+                this.displacedAssignments.set(entry.id, tKey);
+        }
+    }
+    /** R5-C1/R6-M3: the assignment-beats-alias filter re-run over composed state —
+     *  an alias shadowing a reserved canonical or an assigned displacement offset
+     *  is dropped exactly as it would be at ingest. */
+    applyAliasAssignmentFilter() {
+        for (const aliasId of [...this.aliases.keys()]) {
+            if (this.reservedCanonicals.has(aliasId) || this.displacedAssignments.has(aliasId)) {
+                this.aliases.delete(aliasId);
+            }
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Journal append (§3.4 — dedicated single-writer discipline, G3)
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Append ONE newline-terminated record. `seq` assignment and the byte-write
+     * happen atomically per record under a synchronous append (Node's
+     * single-threaded sync I/O IS the append mutex — no interleaving is
+     * possible), satisfying the §3.4 G3 single-writer contract.
+     */
+    appendJournal(rec, opts) {
+        const seq = ++this.seqCounter;
+        const line = `${JSON.stringify({ seq, ...rec, ts: this.now().toISOString() })}\n`;
+        this.rotateJournalIfNeeded(Buffer.byteLength(line));
+        if (this.journalFd === null) {
+            const created = !fs.existsSync(this.journalPath);
+            this.journalFd = fs.openSync(this.journalPath, 'a');
+            if (created)
+                this.fsyncDir(); // directory entry durable on file creation (§3.4)
+        }
+        fs.writeSync(this.journalFd, line);
+        this.journalBytes += Buffer.byteLength(line);
+        this.journalLines += 1;
+        if (opts.fsync && !(this.d.isJournalFsyncDisabled?.() ?? false)) {
+            try {
+                fs.fsyncSync(this.journalFd);
+            }
+            catch {
+                /* macOS platform footnote (§3.4): cheap-fsync is the deliberate choice */
+            }
+        }
+        return seq;
+    }
+    fsyncDir() {
+        try {
+            const dirFd = fs.openSync(this.d.stateDir, 'r');
+            try {
+                fs.fsyncSync(dirFd);
+            }
+            finally {
+                fs.closeSync(dirFd);
+            }
+        }
+        catch {
+            /* @silent-fallback-ok — directory fsync is best-effort, platform-dependent (§3.4 macOS footnote); the record append itself is the durability authority */
+        }
+    }
+    rotateJournalIfNeeded(incomingBytes) {
+        const rotateBytes = this.d.journalRotateBytes ?? 8388608;
+        const rotateLines = this.d.journalRotateLines ?? 50000;
+        if (this.journalBytes + incomingBytes <= rotateBytes && this.journalLines < rotateLines)
+            return;
+        if (!fs.existsSync(this.journalPath))
+            return;
+        if (this.journalFd !== null) {
+            try {
+                fs.fsyncSync(this.journalFd);
+            }
+            catch {
+                /* @silent-fallback-ok — pre-rotation fsync is best-effort; every durable record already fsynced at append time (§3.3 WAL rule) */
+            }
+            fs.closeSync(this.journalFd);
+            this.journalFd = null;
+        }
+        // Unique all-digit suffix (two rotations can land in one millisecond; the
+        // suffix must keep matching the retained-file scan + the backup glob).
+        let suffix = Date.now();
+        while (fs.existsSync(`${this.journalPath}.${suffix}`))
+            suffix++;
+        const rotatedPath = `${this.journalPath}.${suffix}`;
+        fs.renameSync(this.journalPath, rotatedPath);
+        this.fsyncDir();
+        this.journalBytes = 0;
+        this.journalLines = 0;
+        this.pruneRotatedJournals();
+    }
+    /**
+     * Prune ONLY fully-superseded rotated files: every record ≤ the PERSISTED
+     * snapshot high-water, older than the 7-day retention floor (§8 — a recovery
+     * requirement), and containing no unapplied unknown-op record (R8-minor-2).
+     * Under snapshot suspension the persisted high-water stays pre-skew, so every
+     * file the eventual re-upgrade needs is retained MECHANICALLY (R10-M1).
+     */
+    pruneRotatedJournals() {
+        const persistedHighWater = this.readPersistedHighWater();
+        const retentionFloorMs = 7 * 24 * 60 * 60 * 1000;
+        const unknownSeqs = new Set(this.unappliedUnknownOps.map((u) => u.seq));
+        for (const file of this.journalFiles()) {
+            if (file === this.journalPath)
+                continue;
+            try {
+                const stat = fs.statSync(file);
+                if (this.now().getTime() - stat.mtimeMs < retentionFloorMs)
+                    continue;
+                const content = fs.readFileSync(file, 'utf-8');
+                let maxSeq = 0;
+                let hasUnknown = false;
+                for (const line of content.split('\n')) {
+                    if (!line)
+                        continue;
+                    try {
+                        const rec = JSON.parse(line);
+                        if (typeof rec.seq === 'number' && rec.seq > maxSeq)
+                            maxSeq = rec.seq;
+                        if (!JOURNAL_OPS.includes(rec.op) || unknownSeqs.has(rec.seq))
+                            hasUnknown = true;
+                    }
+                    catch {
+                        hasUnknown = true; // @silent-fallback-ok — fails toward RETENTION: a file we cannot fully read is never pruned (§3.4)
+                    }
+                }
+                if (!hasUnknown && maxSeq > 0 && maxSeq <= persistedHighWater) {
+                    SafeFsExecutor.safeUnlinkSync(file, { operation: 'conversation-registry journal rotation prune (fully-superseded rotated file — §3.4)' });
+                }
+            }
+            catch {
+                /* @silent-fallback-ok — prune is hygiene; a failed prune retains the file (the safe direction), never gates identity */
+            }
+        }
+    }
+    readPersistedHighWater() {
+        try {
+            const raw = JSON.parse(fs.readFileSync(this.snapshotPath, 'utf-8'));
+            return typeof raw?.snapshotHighWaterSeq === 'number' ? raw.snapshotHighWaterSeq : 0;
+        }
+        catch {
+            // @silent-fallback-ok — an unreadable snapshot reads as high-water 0, so the
+            // prune rule supersedes NOTHING (fails toward retaining every journal file).
+            return 0;
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Snapshot (batched, size-adaptive — §3.4)
+    // ─────────────────────────────────────────────────────────────────────────
+    scheduleSnapshot() {
+        this.snapshotDirty = true;
+        if (this.batchDepth > 0)
+            return; // batched-save window (§6.2 adoption pass)
+        if (this.unappliedUnknownOps.length > 0)
+            return; // SUSPENSION (R9-M1/R10-M1)
+        if (this.snapshotTimer)
+            return;
+        const base = this.d.snapshotBaseIntervalMs ?? 2000;
+        const step = this.d.snapshotAdaptiveStep ?? 5000;
+        const max = this.d.snapshotMaxIntervalMs ?? 60000;
+        const interval = Math.min(Math.max(base * Math.ceil(Math.max(this.conversations.size, 1) / step), base), max);
+        this.snapshotTimer = setTimeout(() => {
+            this.snapshotTimer = null;
+            void this.flushSnapshot();
+        }, interval);
+        this.snapshotTimer.unref?.();
+    }
+    /** Force a flush now (shutdown/tests). Honors the unknown-op suspension. */
+    async flushSnapshot() {
+        if (this.flushInFlight)
+            return;
+        if (this.unappliedUnknownOps.length > 0)
+            return; // pre-skew snapshot stays put (R10-M1)
+        this.flushInFlight = true;
+        try {
+            const shape = {
+                version: 1,
+                snapshotHighWaterSeq: this.seqCounter,
+                ...(this.workspacePin ? { workspacePin: this.workspacePin } : {}),
+                conversations: Object.fromEntries(this.conversations),
+                aliases: Object.fromEntries([...this.aliases].map(([k, v]) => [String(k), v])),
+                bindPins: Object.fromEntries([...this.bindPins].map(([k, v]) => [String(k), v])),
+                ambiguousSends: Object.fromEntries(this.ambiguousSends),
+                sendIntents: Object.fromEntries(this.sendIntents),
+            };
+            const serialized = JSON.stringify(shape, null, 2);
+            const tmp = `${this.snapshotPath}.tmp`;
+            if (this.conversations.size > OFFLOOP_ENTRY_TRIGGER || this.lastSnapshotBytes > OFFLOOP_BYTES_TRIGGER) {
+                // §3.4 pinned off-loop trigger: async write of the pre-serialized buffer.
+                await fs.promises.writeFile(tmp, serialized);
+                await fs.promises.rename(tmp, this.snapshotPath);
+            }
+            else {
+                fs.writeFileSync(tmp, serialized);
+                fs.renameSync(tmp, this.snapshotPath);
+            }
+            this.snapshotHighWaterSeq = shape.snapshotHighWaterSeq;
+            this.lastSnapshotBytes = Buffer.byteLength(serialized);
+            this.snapshotDirty = false;
+            this.maybeRaiseGrowthTripwire();
+        }
+        catch (err) {
+            this.log(`[conversation-registry] snapshot flush failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        finally {
+            this.flushInFlight = false;
+        }
+    }
+    maybeRaiseGrowthTripwire() {
+        if (this.conversations.size >= ENTRY_THRESHOLD || this.lastSnapshotBytes >= FILE_BYTES_THRESHOLD) {
+            this.attention('conversation-registry:growth-threshold', 'Conversation registry approaching its JSON-store ceiling', `entryCount=${this.conversations.size} (ceiling ~${ENTRY_CEILING}) / fileSizeBytes=${this.lastSnapshotBytes}. The §11.10 append-journal-as-primary / SQLite migration must land BEFORE the ceiling (scalability-G2).`);
+        }
+    }
+    /** Batched-save window for the adoption pass / bursts (§3.4/§6.2): one flush. */
+    beginBatch() {
+        this.batchDepth++;
+    }
+    endBatch() {
+        this.batchDepth = Math.max(0, this.batchDepth - 1);
+        if (this.batchDepth === 0 && this.snapshotDirty)
+            this.scheduleSnapshot();
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Mint (§3.3)
+    // ─────────────────────────────────────────────────────────────────────────
+    /** §3.3 `candidateCollides` — pure O(1) lookups, never a live-tuple scan:
+     *  (a) reserved canonical of a DIFFERENT tuple; (b) alias table; (c) the
+     *  GLOBAL displaced-assignment set (R4-C1). */
+    candidateCollides(id, tKey) {
+        const reserved = this.reservedCanonicals.get(id);
+        if (reserved !== undefined && reserved !== tKey)
+            return true;
+        if (this.aliases.has(id))
+            return true;
+        const displaced = this.displacedAssignments.get(id);
+        if (displaced !== undefined && displaced !== tKey)
+            return true;
+        return false;
+    }
+    /** Resolve the fleet workspace pin (§3.1 order: config → stored candidate). */
+    resolvedWorkspacePin() {
+        const configPin = this.readConfigPin();
+        if (configPin)
+            return { value: configPin, confirmedLocally: true };
+        return this.workspacePin;
+    }
+    /**
+     * Workspace admission for a mint (§3.1). Returns the workspaceId to record
+     * (concrete or `_`), or 'refused' on the per-machine multi-workspace gate.
+     */
+    admitWorkspace() {
+        let observed;
+        try {
+            observed = this.d.getLocalWorkspaceId?.();
+        }
+        catch {
+            // @silent-fallback-ok — a throwing workspace source degrades to the `_`
+            // placeholder (upgrades in place later, §3.1) — never a blocked mint.
+            observed = undefined;
+        }
+        if (!observed || !SLACK_WORKSPACE_ID_RE.test(observed))
+            return WORKSPACE_PLACEHOLDER;
+        const pin = this.resolvedWorkspacePin();
+        if (!pin) {
+            // First concrete LOCAL observation writes the candidate and is immediately
+            // confirmed for it — self-corroboration is the designed single-machine /
+            // first-machine path (R6-minor-5).
+            this.workspacePin = { value: observed, source: 'local-observed', confirmedLocally: true };
+            this.scheduleSnapshot();
+            return observed;
+        }
+        if (pin.value !== observed && pin.confirmedLocally) {
+            this.attention('conversation-registry:multi-workspace', 'Second Slack workspace refused (multi-workspace-unsupported)', `A mint arrived authenticated to workspace ${observed}, but this fleet's pin is ${pin.value}. Phase 1 supports exactly ONE Slack workspace (§3.1); Slack Connect / multi-workspace identity is Phase 7.1. Check conversationIdentity.workspacePin.`);
+            return 'refused';
+        }
+        return observed;
+    }
+    /** Breaker window state for a channel — bounded map with stale-window eviction (§3.3, R3-minor). */
+    breakerWindow(channelId) {
+        const windowMs = this.d.breaker?.windowMs ?? 600000;
+        const nowMs = this.now().getTime();
+        let w = this.breakerWindows.get(channelId);
+        if (!w || nowMs - w.windowStartMs >= windowMs) {
+            w = { windowStartMs: nowMs, speculative: 0, durable: 0, episodeNotified: false };
+            if (!this.breakerWindows.has(channelId) && this.breakerWindows.size >= BREAKER_MAX_TRACKED_CHANNELS) {
+                // Evict the stalest window — never a monotonic map (Bounded Blast Radius).
+                let oldest = null;
+                let oldestStart = Infinity;
+                for (const [k, v] of this.breakerWindows) {
+                    if (v.windowStartMs < oldestStart) {
+                        oldestStart = v.windowStartMs;
+                        oldest = k;
+                    }
+                }
+                if (oldest)
+                    this.breakerWindows.delete(oldest);
+            }
+            this.breakerWindows.set(channelId, w);
+        }
+        return w;
+    }
+    /**
+     * Speculative (inbound-triggered) get-or-create mint (§6.3 eager mint).
+     * NEVER throws and never blocks delivery — every failure degrades toward
+     * "no durable id" or a collision-checked read (§3.6).
+     */
+    mintForInbound(routingKey, opts) {
+        this.load();
+        const tuple = tupleForRoutingKey(routingKey);
+        if (!tuple)
+            return { id: null, created: false, registered: false, degraded: 'unparseable-key' };
+        return this.mintTuple(tuple, { durableBinding: false, label: opts?.label, origin: undefined });
+    }
+    /**
+     * Durable-binding-forced mint (§3.3 breaker carve-out): registered REGARDLESS
+     * of the speculative budget, journal line fsynced BEFORE the id returns (the
+     * WAL rule). Its OWN higher budget yields a typed capacity refusal at the
+     * cap — never a silent drop (adversarial-B).
+     */
+    mintForDurableBinding(routingKey, opts) {
+        this.load();
+        const tuple = tupleForRoutingKey(routingKey);
+        if (!tuple)
+            return { ok: false, error: 'unparseable-key' };
+        if (!this.recordingEnabled()) {
+            // R2-integration-§9: an unjournaled bind would be unresolvable after a
+            // restart — refuse, typed + loud. Positive Telegram binds are unaffected
+            // (they never reach the registry).
+            this.attention('conversation-registry:recording-disabled-bind', 'Durable bind on a minted conversation refused — recording is disabled', 'conversationIdentity.recording.enabled is false (the emergency kill-switch). A durable-state open on a MINTED id is refused while recording is off (typed conversation-recording-disabled): an unjournaled bind would silently die on restart. Re-enable recording to restore minted binds.');
+            return { ok: false, error: 'conversation-recording-disabled' };
+        }
+        const existing = this.byTuple.get(tupleKeyFor(tuple));
+        if (existing) {
+            this.maybeUpgradeWorkspace(existing);
+            // WAL rule at durable-bind time (§3.3): a pre-existing SPECULATIVE entry
+            // rode the batched snapshot only — its journal line may not exist yet. A
+            // durable binding is not re-derivable after a crash, so ensure the entry
+            // is durably journaled NOW (idempotent op:"mint" re-apply; fsynced)
+            // BEFORE the id is handed to the binding.
+            this.appendJournal({
+                op: 'mint',
+                key: canonicalKeyFor(tuple, existing.workspaceId),
+                tuple: [tuple.platform, tuple.channelId, tuple.threadTs],
+                id: existing.id,
+                origin: existing.origin,
+                hlc: existing.hlc,
+            }, { fsync: true });
+            return { ok: true, id: existing.id, created: false };
+        }
+        const w = this.breakerWindow(tuple.channelId);
+        const durableCap = this.d.breaker?.durableBindingPerWindow ?? 50;
+        if (w.durable >= durableCap) {
+            this.attention('conversation-registry:durable-capacity', 'Durable-binding mint budget exhausted for a channel', `Channel ${tuple.channelId} exceeded ${durableCap} durable-binding registrations in the window. The binding-open is refused with a typed conversation-registration-capacity error — never a silent drop (§3.3 adversarial-B).`);
+            return { ok: false, error: 'conversation-registration-capacity' };
+        }
+        const res = this.mintTuple(tuple, { durableBinding: true, label: opts?.label });
+        if (res.id === null || !res.registered) {
+            if (res.degraded === 'multi-workspace-unsupported')
+                return { ok: false, error: 'multi-workspace-unsupported' };
+            return { ok: false, error: 'mint-failure' };
+        }
+        w.durable++;
+        return { ok: true, id: res.id, created: res.created };
+    }
+    /** §3.1 in-place `_`→teamId upgrade — LOCAL authenticated source ONLY. */
+    maybeUpgradeWorkspace(entry) {
+        if (entry.workspaceId !== WORKSPACE_PLACEHOLDER)
+            return;
+        const admitted = this.admitWorkspace();
+        if (admitted === 'refused' || admitted === WORKSPACE_PLACEHOLDER)
+            return;
+        const tuple = { platform: 'slack', channelId: entry.channelId, threadTs: entry.threadTs };
+        const oldKey = canonicalKeyFor(tuple, entry.workspaceId);
+        this.conversations.delete(oldKey);
+        entry.workspaceId = admitted;
+        const newKey = canonicalKeyFor(tuple, admitted);
+        this.conversations.set(newKey, entry);
+        // Journaled (§3.1) as an idempotent op:"mint" re-apply with the rewritten
+        // key (the op enum has no distinct upgrade op — §3.4/R6-low-2 precedent).
+        this.appendJournal({
+            op: 'mint',
+            key: newKey,
+            tuple: [tuple.platform, tuple.channelId, tuple.threadTs],
+            id: entry.id,
+            origin: entry.origin,
+            hlc: entry.hlc,
+        }, { fsync: false });
+        this.scheduleSnapshot();
+        this.log(`[conversation-registry] workspace upgraded in place: ${oldKey} → ${newKey} (id ${entry.id})`);
+    }
+    mintTuple(tuple, opts) {
+        const tKey = tupleKeyFor(tuple);
+        const existing = this.byTuple.get(tKey);
+        if (existing) {
+            this.maybeUpgradeWorkspace(existing);
+            if (opts.label && opts.label !== existing.label) {
+                existing.label = opts.label; // write-on-change (§3.4 G4)
+                this.scheduleSnapshot();
+            }
+            // §5.1 reachability auto-clear: an authenticated inbound on the tuple is
+            // positive evidence the conversation is reachable again (re-invited /
+            // un-archived channel is never stuck).
+            if (existing.reachability === 'unreachable')
+                this.setReachability(existing.id, 'ok');
+            return { id: existing.id, created: false, registered: true };
+        }
+        const routingKey = routingKeyForTuple(tuple);
+        const candidate = candidateIdForRoutingKey(routingKey);
+        const workspace = this.admitWorkspace();
+        if (workspace === 'refused') {
+            return { id: null, created: false, registered: false, degraded: 'multi-workspace-unsupported' };
+        }
+        if (!this.recordingEnabled()) {
+            // D1 degradation (§3.6): behavior-identical to legacy hashing — candidate
+            // + collision-checked read (B6), NO durable write, NO journal fsync.
+            return { id: this.collisionCheckedRead(candidate, tKey), created: false, registered: false, degraded: 'recording-disabled' };
+        }
+        if (!opts.durableBinding) {
+            const w = this.breakerWindow(tuple.channelId);
+            const cap = this.d.breaker?.speculativePerWindow ?? 200;
+            if (w.speculative >= cap) {
+                // The breaker DROPS speculative registrations to NOWHERE (zero pending
+                // state) — the candidate re-mints for free on a later inbound. Delivery
+                // still proceeds on a collision-checked read (B6).
+                this.breakerEpisodes++;
+                if (!w.episodeNotified) {
+                    w.episodeNotified = true;
+                    this.attention('conversation-registry:mint-breaker', 'Mint-rate breaker engaged for a channel', `Channel ${tuple.channelId} exceeded ${cap} new speculative conversation registrations in the window. Further inbound registrations this window are dropped (they re-mint later); delivery is unaffected (§3.3 Bounded Blast Radius).`);
+                }
+                return { id: this.collisionCheckedRead(candidate, tKey), created: false, registered: false, degraded: 'breaker-dropped' };
+            }
+            w.speculative++;
+        }
+        const walk = walkDisplacement(candidate, (id) => this.candidateCollides(id, tKey));
+        if (!walk.ok) {
+            // Probe overflow (astronomically unlikely) degrades to the §3.6
+            // pending-mint path — never a silently-un-ingestable id.
+            const key = canonicalKeyFor(tuple, workspace);
+            if (!this.pendingMints.has(key)) {
+                if (this.pendingMints.size >= PENDING_MINT_MAX)
+                    this.pendingMintDrops++;
+                else
+                    this.pendingMints.set(key, { firstAt: this.now().toISOString() });
+            }
+            return { id: null, created: false, registered: false, degraded: 'probe-overflow' };
+        }
+        const probed = walk.probes > 0;
+        const nowIso = this.now().toISOString();
+        const machineId = this.safeMachineId();
+        const entry = {
+            id: walk.id,
+            platform: 'slack',
+            workspaceId: workspace,
+            channelId: tuple.channelId,
+            threadTs: tuple.threadTs,
+            mintedAt: nowIso,
+            mintedBy: machineId,
+            // A fresh non-probed local mint's id IS the legacy-hash id — the honest
+            // origin within the frozen §3.4 enum; probed mints are 'minted-probed'.
+            origin: opts.origin ?? (probed ? 'minted-probed' : 'adopted-legacy-hash'),
+            reachability: 'ok',
+            hlc: { physical: this.now().getTime(), logical: 0, node: machineId },
+            ...(opts.label ? { label: opts.label } : {}),
+        };
+        const key = canonicalKeyFor(tuple, workspace);
+        // Synchronous assignment: authoritative cache + reverse + tuple index +
+        // derived occupancy — the id RETURNED equals the id that will PERSIST.
+        this.indexEntry(key, entry);
+        let claimants = this.candClaimants.get(candidate);
+        if (!claimants) {
+            claimants = new Set();
+            this.candClaimants.set(candidate, claimants);
+        }
+        claimants.add(tKey);
+        if (!probed)
+            this.reservedCanonicals.set(candidate, tKey);
+        else
+            this.displacedAssignments.set(walk.id, tKey);
+        // WAL rule (§3.3): a PROBED or durable-binding-forced mint append+fsyncs
+        // ONE journal line BEFORE the id is returned (not re-derivable after a
+        // crash). A pure SPECULATIVE non-probed mint performs NO synchronous
+        // journal write — it rides the batched snapshot only (§3.4 fsync
+        // discipline; its candidate re-mints deterministically for free).
+        if (probed || opts.durableBinding) {
+            this.appendJournal({
+                op: 'mint',
+                key,
+                tuple: [tuple.platform, tuple.channelId, tuple.threadTs],
+                id: entry.id,
+                origin: entry.origin,
+                hlc: entry.hlc,
+            }, { fsync: true });
+        }
+        this.pendingMints.delete(key);
+        this.lastMintAt = nowIso;
+        this.scheduleSnapshot();
+        return { id: entry.id, created: true, registered: true };
+    }
+    safeMachineId() {
+        try {
+            return this.d.machineId() || 'unknown';
+        }
+        catch {
+            return 'unknown';
+        }
+    }
+    /**
+     * B6 collision-checked read for degraded paths (breaker-drop / recording-off):
+     * never delivers on a raw candidate occupied by a DIFFERENT tuple — resolves
+     * via the same key-derived probe for the READ ONLY (no registration).
+     */
+    collisionCheckedRead(candidate, tKey) {
+        const walk = walkDisplacement(candidate, (id) => this.candidateCollides(id, tKey));
+        return walk.ok ? walk.id : candidate;
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Resolution (§2/§8)
+    // ─────────────────────────────────────────────────────────────────────────
+    /** `resolve(id)`: positive → Telegram pass-through; negative → registry
+     *  lookup, aliases followed exactly ONE hop; unknown → null. */
+    resolve(id) {
+        this.load();
+        if (!Number.isSafeInteger(id) || id === 0)
+            return null;
+        if (id > 0)
+            return { platform: 'telegram', topicId: id, passThrough: true };
+        const aliasTarget = this.aliases.get(id);
+        const entry = this.byId.get(aliasTarget ?? id);
+        if (!entry)
+            return null;
+        return {
+            platform: 'slack',
+            id: entry.id,
+            key: canonicalKeyFor({ platform: 'slack', channelId: entry.channelId, threadTs: entry.threadTs }, entry.workspaceId),
+            channelId: entry.channelId,
+            threadTs: entry.threadTs,
+            workspaceId: entry.workspaceId,
+            origin: entry.origin,
+            reachability: entry.reachability,
+            ...(entry.label !== undefined ? { label: entry.label } : {}),
+            ...(aliasTarget !== undefined ? { aliasOf: aliasTarget } : {}),
+        };
+    }
+    /** Forward lookup by canonical key OR transport sessionKey — mints NOTHING (§8). */
+    resolveByKey(keyOrSessionKey) {
+        this.load();
+        if (/^\d+$/.test(keyOrSessionKey)) {
+            return { platform: 'telegram', topicId: Number(keyOrSessionKey), passThrough: true };
+        }
+        const parsed = parseCanonicalKey(keyOrSessionKey);
+        const tuple = parsed?.tuple ?? tupleForRoutingKey(keyOrSessionKey);
+        if (!tuple)
+            return null;
+        const entry = this.byTuple.get(tupleKeyFor(tuple));
+        return entry ? this.resolve(entry.id) : null;
+    }
+    /**
+     * §4 READ-ONLY id for a routing key (integration-nit): the existing entry's
+     * id, else the B6 collision-checked candidate — NEVER a registration. A pure
+     * comparison callsite must not acquire a get-or-create WRITE side-effect.
+     */
+    readIdForRoutingKey(routingKey) {
+        this.load();
+        const tuple = tupleForRoutingKey(routingKey);
+        if (!tuple)
+            return null;
+        const tKey = tupleKeyFor(tuple);
+        const existing = this.byTuple.get(tKey);
+        if (existing)
+            return existing.id;
+        return this.collisionCheckedRead(candidateIdForRoutingKey(routingKey), tKey);
+    }
+    /**
+     * `idForSessionKey` — GET-OR-CREATE (§6.0 #12, a named mint chokepoint).
+     * Positive numeric session keys pass through; Slack routing keys mint.
+     */
+    idForSessionKey(sessionKey) {
+        this.load();
+        if (/^\d+$/.test(sessionKey))
+            return Number(sessionKey);
+        return this.mintForInbound(sessionKey).id;
+    }
+    /** Read-only inventory for GET /conversations (§8). */
+    list(opts) {
+        this.load();
+        const limit = Math.max(1, Math.min(opts?.limit ?? 500, 5000));
+        const out = [];
+        for (const [key, entry] of this.conversations) {
+            if (opts?.platform && entry.platform !== opts.platform)
+                continue;
+            out.push({ key, entry });
+            if (out.length >= limit)
+                break;
+        }
+        return out;
+    }
+    aliasTable() {
+        this.load();
+        return Object.fromEntries([...this.aliases].map(([k, v]) => [String(k), v]));
+    }
+    entryCount() {
+        this.load();
+        return this.conversations.size;
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Bind-pin overlay (§3.5.2 — increment 2 writers)
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Record a durable bind on a minted id (§3.5.2 property 2/4): the pin binds
+     * the id to the TUPLE it resolves to AT BIND TIME, refcounted per live
+     * binding, journaled (`op:"bind-pin"`, fsynced — the bind's own WAL line).
+     * Returns the bind-time tuple (the caller denormalizes it as `boundTuple`
+     * onto the binding record — property 5), or null when the id is unresolvable.
+     */
+    bindPin(id) {
+        this.load();
+        const entry = this.byId.get(this.aliases.get(id) ?? id);
+        if (!entry)
+            return null;
+        const tuple = ['slack', entry.channelId, entry.threadTs];
+        const pin = this.bindPins.get(id);
+        const refcount = pin ? pin.refcount + 1 : 1;
+        if (pin)
+            pin.refcount = refcount;
+        else
+            this.bindPins.set(id, { tuple, refcount });
+        this.appendJournal({ op: 'bind-pin', id, tuple, refcount }, { fsync: true });
+        this.scheduleSnapshot();
+        return { platform: 'slack', channelId: entry.channelId, threadTs: entry.threadTs };
+    }
+    /** Release one refcount on a bind-pin (`op:"bind-release"`, §3.5.2 property 4).
+     *  The pin is released only at ZERO — a commitment closing never strands a
+     *  still-live sibling binding on the same id. No-op on a missing pin. */
+    bindRelease(id) {
+        this.load();
+        const pin = this.bindPins.get(id);
+        if (!pin)
+            return;
+        const refcount = pin.refcount - 1;
+        this.appendJournal({ op: 'bind-release', id, refcount }, { fsync: true });
+        if (refcount <= 0)
+            this.bindPins.delete(id);
+        else
+            pin.refcount = refcount;
+        this.scheduleSnapshot();
+    }
+    /** The live bind-pin tuple for an id (delivery-time overlay read — §3.5.2 property 3). */
+    getBindPinTuple(id) {
+        this.load();
+        const pin = this.bindPins.get(id);
+        if (!pin)
+            return null;
+        return { platform: 'slack', channelId: pin.tuple[1], threadTs: pin.tuple[2] ?? null };
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // E1 ambiguous-outcome idempotency guard state (§5.0(a) — increment 2 writers)
+    // ─────────────────────────────────────────────────────────────────────────
+    sendGuardKey(conversationId, logicalSendId) {
+        return `${conversationId}|${logicalSendId}`;
+    }
+    /**
+     * Durable SEND-INTENT (R6-M1): appended+fsynced BEFORE the transport send,
+     * stamped with the caller's lane (R8-M1 — the boot-conversion discriminator,
+     * never inferred from the id's shape at boot).
+     */
+    recordSendIntent(conversationId, logicalSendId, lane) {
+        this.load();
+        const seq = this.appendJournal({ op: 'send-intent', conversationId, logicalSendId, lane }, { fsync: true });
+        this.sendIntents.set(this.sendGuardKey(conversationId, logicalSendId), { lane, seq });
+        this.scheduleSnapshot();
+    }
+    /**
+     * Record the E1 suppressor entry — ONLY on a likely-posted outcome (success
+     * or ambiguous/ack-lost; NEVER a clean transient failure — R2-security-NEW-3).
+     * Durable (`op:"ambiguous-send"`, fsynced — R4-M2); resolves the pair's
+     * send-intent. The in-memory map is the loaded image of this durable state.
+     */
+    recordLikelyPosted(conversationId, logicalSendId, lane) {
+        this.load();
+        this.pruneSendGuardState();
+        const key = this.sendGuardKey(conversationId, logicalSendId);
+        this.appendJournal({ op: 'ambiguous-send', conversationId, logicalSendId, lane }, { fsync: true });
+        this.ambiguousSends.set(key, { recordedAt: this.now().toISOString(), lane });
+        this.sendIntents.delete(key);
+        if (this.ambiguousSends.size > AMBIGUOUS_SENDS_HARD_CAP) {
+            // Pathological tripwire (R4-M2 scoped per R5-minor-1): loud, aggregated,
+            // and the new entry is STILL journaled + retained — nothing dropped, so a
+            // silent eviction can never re-open the double-post.
+            this.attention('conversation-registry:send-guard-cap', 'E1 send-guard entry population exceeded its pathological tripwire', `${this.ambiguousSends.size} unretired/unexpired ambiguous-send entries exceed the ${AMBIGUOUS_SENDS_HARD_CAP} cap (§5.0(a)). Live entries are bounded by open beacon commitments (~maxActiveBeacons) by construction — this population means an upstream cap was raised or a retirement path is broken. No entry was evicted or dropped.`);
+        }
+        this.scheduleSnapshot();
+    }
+    /** Retire a logical send (`op:"send-retire"` — delivered outcome advanced the
+     *  seq, or the commitment closed). Idempotent; also resolves the intent. */
+    retireSend(conversationId, logicalSendId) {
+        this.load();
+        const key = this.sendGuardKey(conversationId, logicalSendId);
+        if (!this.ambiguousSends.has(key) && !this.sendIntents.has(key))
+            return;
+        this.appendJournal({ op: 'send-retire', conversationId, logicalSendId }, { fsync: true });
+        this.ambiguousSends.delete(key);
+        this.sendIntents.delete(key);
+        this.scheduleSnapshot();
+    }
+    /** Resolve a send-intent WITHOUT a suppressor (`op:"send-intent-resolved"`) —
+     *  the clean-transient-failure path (positive evidence the message never
+     *  posted), so the retry is NOT suppressed (R2-security-NEW-3/R6-M1). */
+    resolveSendIntent(conversationId, logicalSendId) {
+        this.load();
+        const key = this.sendGuardKey(conversationId, logicalSendId);
+        if (!this.sendIntents.has(key))
+            return;
+        this.appendJournal({ op: 'send-intent-resolved', conversationId, logicalSendId }, { fsync: true });
+        this.sendIntents.delete(key);
+        this.scheduleSnapshot();
+    }
+    /**
+     * The E1 suppression read (§5.0(a) R3-M1/R7-M2): the LOGICAL lane is
+     * retirement-based (an unretired entry suppresses whenever the re-fire
+     * arrives, bounded only by the 7-day TTL backstop); the CONTENT-HASH lane is
+     * WINDOW-based (a windowless caller has nothing to retire — outside the
+     * 15-min window the same text delivers again).
+     */
+    isSendSuppressed(conversationId, logicalSendId, lane) {
+        this.load();
+        const entry = this.ambiguousSends.get(this.sendGuardKey(conversationId, logicalSendId));
+        if (!entry)
+            return false;
+        const age = this.now().getTime() - Date.parse(entry.recordedAt);
+        if (!Number.isFinite(age))
+            return false;
+        return lane === 'content-hash' ? age < CONTENT_HASH_DEDUP_WINDOW_MS : age < AMBIGUOUS_DEDUP_TTL_MS;
+    }
+    /** Prune RETIRED/EXPIRED stragglers only (never a live unretired logical
+     *  entry below its TTL — R4-M2 second arm). An expired content-hash entry
+     *  prunes exactly like a retired one (R7-M2). */
+    pruneSendGuardState() {
+        const nowMs = this.now().getTime();
+        let pruned = false;
+        for (const [key, entry] of this.ambiguousSends) {
+            const age = nowMs - Date.parse(entry.recordedAt);
+            if (!Number.isFinite(age))
+                continue;
+            const horizon = entry.lane === 'content-hash' ? CONTENT_HASH_DEDUP_WINDOW_MS : AMBIGUOUS_DEDUP_TTL_MS;
+            if (age > horizon) {
+                this.ambiguousSends.delete(key);
+                pruned = true;
+            }
+        }
+        if (pruned)
+            this.scheduleSnapshot();
+    }
+    /**
+     * R8-M1 lane-scoped boot conversion of crash-orphaned send-intents: an intent
+     * that is the LAST word for its (conversationId, logicalSendId) PAIR (R7-M3
+     * composite keying — replay already resolved every superseded pair) resolves
+     * BY ITS RECORDED LANE: `logical` (beacon) converts into an ambiguous-send
+     * suppressor (the outcome is genuinely unknown and the beacon has a next
+     * tick); `content-hash` resolves toward RETRY (the suppressed send IS the
+     * message — replay appends the missing send-intent-resolved durably, so the
+     * verdict is decided once, not re-decided every boot). Staged appends land
+     * POST-compose, fsynced before the registry begins serving (R9-low-3 /
+     * R10-minor-1).
+     */
+    convertOrphanedSendIntents() {
+        if (this.sendIntents.size === 0)
+            return;
+        for (const [key, intent] of [...this.sendIntents]) {
+            const sep = key.indexOf('|'); // conversationId prefix is numeric — the FIRST '|' always delimits (§3.4)
+            if (sep <= 0) {
+                this.sendIntents.delete(key);
+                continue;
+            }
+            const conversationId = Number(key.slice(0, sep));
+            const logicalSendId = key.slice(sep + 1);
+            if (!Number.isSafeInteger(conversationId) || !logicalSendId) {
+                this.sendIntents.delete(key);
+                continue;
+            }
+            if (intent.lane === 'logical') {
+                this.appendJournal({ op: 'ambiguous-send', conversationId, logicalSendId, lane: 'logical' }, { fsync: true });
+                this.ambiguousSends.set(key, { recordedAt: this.now().toISOString(), lane: 'logical' });
+            }
+            else {
+                this.appendJournal({ op: 'send-intent-resolved', conversationId, logicalSendId }, { fsync: true });
+            }
+            this.sendIntents.delete(key);
+        }
+        this.scheduleSnapshot();
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Reachability (§5.1 — increment 2 writer)
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Flip an entry's LOCAL-authoritative reachability (§5.1). IDEMPOTENT
+     * (already-in-state → no write) and journaled WITHOUT fsync — it rides the
+     * same batched flush, so a mass event coalesces into one write, never an
+     * O(N) write storm on the failure path (scalability-F2). Returns whether the
+     * state changed and whether the conversation is in the R3-minor FLAP-DAMPENED
+     * state (>3 flips in 24h — the caller coalesces its dead-letter attention
+     * into one per-window flap item instead of one per episode).
+     */
+    setReachability(id, state) {
+        this.load();
+        const entry = this.byId.get(this.aliases.get(id) ?? id);
+        if (!entry)
+            return { changed: false, dampened: false };
+        const nowMs = this.now().getTime();
+        const cutoff = nowMs - REACHABILITY_FLAP_WINDOW_MS;
+        const flips = (this.reachabilityFlips.get(entry.id) ?? []).filter((t) => t > cutoff);
+        if (entry.reachability === state) {
+            this.reachabilityFlips.set(entry.id, flips);
+            return { changed: false, dampened: flips.length > REACHABILITY_FLAP_THRESHOLD };
+        }
+        flips.push(nowMs);
+        this.reachabilityFlips.set(entry.id, flips);
+        entry.reachability = state;
+        this.appendJournal({ op: 'reachability', id: entry.id, reachability: state }, { fsync: false });
+        this.scheduleSnapshot();
+        return { changed: true, dampened: flips.length > REACHABILITY_FLAP_THRESHOLD };
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Adoption pass (§6.2)
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Idempotent boot-time ensure: pre-register channel-level conversations from
+     * the channel registry with their legacy-hash ids, inside ONE batched-save
+     * window. GATED to channels with ≥1 authorized-sender message on record
+     * (security-B8) — an auto-join channel mints lazily on its first authorized
+     * inbound instead. A pre-population CONVENIENCE, not a recovery requirement.
+     */
+    runAdoptionPass(channels, hasAuthorizedTraffic) {
+        this.load();
+        let adopted = 0;
+        let skippedUnauthorized = 0;
+        this.beginBatch();
+        try {
+            for (const ch of channels) {
+                let authorized = false;
+                try {
+                    authorized = hasAuthorizedTraffic(ch.channelId);
+                }
+                catch {
+                    authorized = false; // fail toward not-pre-minting (it mints lazily later)
+                }
+                if (!authorized) {
+                    skippedUnauthorized++;
+                    continue;
+                }
+                const res = this.mintForInbound(ch.channelId, ch.name ? { label: ch.name } : undefined);
+                if (res.created)
+                    adopted++;
+            }
+        }
+        finally {
+            this.endBatch();
+        }
+        this.adoptionState = { ranAt: this.now().toISOString(), adopted, skippedUnauthorized };
+        this.log(`[conversation-registry] adoption pass: ${adopted} adopted, ${skippedUnauthorized} skipped (no authorized traffic)`);
+        return { adopted, skippedUnauthorized };
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Health (§8 — the e2e "feature is alive" target)
+    // ─────────────────────────────────────────────────────────────────────────
+    health() {
+        this.load();
+        const byOrigin = {};
+        const byPlatform = {};
+        for (const entry of this.conversations.values()) {
+            byOrigin[entry.origin] = (byOrigin[entry.origin] ?? 0) + 1;
+            byPlatform[entry.platform] = (byPlatform[entry.platform] ?? 0) + 1;
+        }
+        let fileSizeBytes = 0;
+        try {
+            fileSizeBytes = fs.existsSync(this.snapshotPath) ? fs.statSync(this.snapshotPath).size : 0;
+        }
+        catch {
+            /* observability */
+        }
+        let retainedJournalBytes = 0;
+        try {
+            for (const f of this.journalFiles())
+                retainedJournalBytes += fs.statSync(f).size;
+        }
+        catch {
+            /* observability */
+        }
+        return {
+            // Resident-heap honesty (§3.4): entryCount is the heap axis — resident
+            // heap is plausibly 5–10× fileSizeBytes at the 100k envelope.
+            entryCount: this.conversations.size,
+            fileSizeBytes,
+            byPlatform,
+            byOrigin,
+            aliasCount: this.aliases.size,
+            lastMintAt: this.lastMintAt,
+            adoptionPass: this.adoptionState,
+            recordingEnabled: this.recordingEnabled(),
+            workspacePin: this.workspacePin ? { value: this.workspacePin.value, source: this.workspacePin.source } : null,
+            mintBudget: {
+                channelsTracked: this.breakerWindows.size,
+                breakerEpisodes: this.breakerEpisodes,
+            },
+            pendingMints: { count: this.pendingMints.size, dropped: this.pendingMintDrops },
+            quarantine: {
+                snapshotQuarantinedAt: this.snapshotQuarantinedAt,
+                journalQuarantinedAt: this.journalQuarantinedAt,
+                durabilityIncidents: this.durabilityIncidents,
+            },
+            // §5.0(a)/§3.5.2 increment-2 observability.
+            sendGuard: {
+                unretiredEntries: this.ambiguousSends.size,
+                unresolvedIntents: this.sendIntents.size,
+                bindPins: this.bindPins.size,
+            },
+            // Snapshot-suspension observability (R11-low-1).
+            snapshotSuspended: this.unappliedUnknownOps.length > 0,
+            firstUnappliedUnknownSeq: this.unappliedUnknownOps[0]?.seq ?? null,
+            unappliedUnknownCount: this.unappliedUnknownOps.length,
+            retainedJournalBytes,
+            ceiling: {
+                entryCeiling: ENTRY_CEILING,
+                thresholdReached: this.conversations.size >= ENTRY_THRESHOLD || fileSizeBytes >= FILE_BYTES_THRESHOLD,
+            },
+            seq: { counter: this.seqCounter, snapshotHighWaterSeq: this.snapshotHighWaterSeq },
+        };
+    }
+    /** Close file handles + flush (shutdown/tests). */
+    async close() {
+        if (this.snapshotTimer) {
+            clearTimeout(this.snapshotTimer);
+            this.snapshotTimer = null;
+        }
+        await this.flushSnapshot();
+        if (this.journalFd !== null) {
+            try {
+                fs.fsyncSync(this.journalFd);
+                fs.closeSync(this.journalFd);
+            }
+            catch {
+                /* @silent-fallback-ok — shutdown teardown; durable records were fsynced at append time */
+            }
+            this.journalFd = null;
+        }
+    }
+}
+//# sourceMappingURL=ConversationRegistry.js.map