instar 1.2.67 → 1.2.69

package/dist/server/specReviewRoutes.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Spec-review HTTP routes — the standards-conformance gate surface.
+ *
+ *   POST /spec/conformance-check   — check a spec against the constitution → report
+ *   GET  /spec/conformance-metrics — observability funnel (runs, per-standard flags)
+ *
+ * Signal-only (spec §4): returns a report; never blocks. Operator/skill-callable;
+ * classified INTERNAL (build-time tool, not an agent-discoverable runtime capability).
+ *
+ * Spec: docs/specs/standards-conformance-gate.md §3, §5.
+ */
+import { Router } from 'express';
+import type { IntelligenceProvider } from '../core/types.js';
+export declare function createSpecReviewRoutes(deps: {
+    intelligence: IntelligenceProvider | null;
+    /** Path to docs/STANDARDS-REGISTRY.md (the constitution). */
+    registryPath: string;
+    /** Directory specs are read from; specPath inputs are resolved within it (no traversal). */
+    specsDir: string;
+    /** Where to persist conformance metrics. */
+    stateDir: string;
+    /** Master switch; default true. When false, routes 503-stub. */
+    enabled?: boolean;
+    /** Model tier override (default 'capable'). */
+    model?: 'fast' | 'balanced' | 'capable';
+}): Router;
+/** Exposed for the CLI (no HTTP): run a conformance check on raw markdown. */
+export declare function runConformanceCheck(markdown: string, registryMarkdown: string, intelligence: IntelligenceProvider | null, model?: 'fast' | 'balanced' | 'capable'): Promise<{
+    report: import("../core/reviewers/standards-conformance.js").ConformanceReport;
+    registryCanary: import("../core/StandardsRegistryParser.js").RegistryCanaryResult;
+}>;
+//# sourceMappingURL=specReviewRoutes.d.ts.map

package/dist/server/specReviewRoutes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"specReviewRoutes.d.ts","sourceRoot":"","sources":["../../src/server/specReviewRoutes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAIjC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAsC7D,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,YAAY,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAC1C,6DAA6D;IAC7D,YAAY,EAAE,MAAM,CAAC;IACrB,4FAA4F;IAC5F,QAAQ,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;CACzC,GAAG,MAAM,CAiET;AAED,8EAA8E;AAC9E,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,gBAAgB,EAAE,MAAM,EACxB,YAAY,EAAE,oBAAoB,GAAG,IAAI,EACzC,KAAK,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;;;GAOxC"}

package/dist/server/specReviewRoutes.js

@@ -0,0 +1,120 @@
+/**
+ * Spec-review HTTP routes — the standards-conformance gate surface.
+ *
+ *   POST /spec/conformance-check   — check a spec against the constitution → report
+ *   GET  /spec/conformance-metrics — observability funnel (runs, per-standard flags)
+ *
+ * Signal-only (spec §4): returns a report; never blocks. Operator/skill-callable;
+ * classified INTERNAL (build-time tool, not an agent-discoverable runtime capability).
+ *
+ * Spec: docs/specs/standards-conformance-gate.md §3, §5.
+ */
+import { Router } from 'express';
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadStandardsRegistry, parseStandardsRegistry, runRegistryCanary } from '../core/StandardsRegistryParser.js';
+import { StandardsConformanceReviewer } from '../core/reviewers/standards-conformance.js';
+function emptyMetrics() {
+    return { runs: 0, degraded: 0, findings_total: 0, by_standard: {}, last_run_at: null };
+}
+function loadMetrics(file) {
+    try {
+        if (fs.existsSync(file)) {
+            const m = JSON.parse(fs.readFileSync(file, 'utf-8'));
+            return { ...emptyMetrics(), ...m, by_standard: m.by_standard ?? {} };
+        }
+    }
+    catch { /* corrupt → fresh */ }
+    return emptyMetrics();
+}
+function saveMetrics(file, m) {
+    try {
+        const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+        fs.writeFileSync(tmp, JSON.stringify(m, null, 2));
+        fs.renameSync(tmp, file);
+    }
+    catch (err) {
+        console.error(`[specReviewRoutes] metrics save failed: ${err}`);
+    }
+}
+export function createSpecReviewRoutes(deps) {
+    const router = Router();
+    const enabled = deps.enabled !== false;
+    const metricsFile = path.join(deps.stateDir, 'spec-conformance-metrics.json');
+    const reviewer = new StandardsConformanceReviewer(deps.intelligence, { model: deps.model });
+    if (!enabled) {
+        router.use('/spec', (_req, res) => res.status(503).json({ error: 'spec conformance gate disabled' }));
+        return router;
+    }
+    /** Resolve a caller-supplied specPath safely within specsDir (block traversal). */
+    function resolveSpecPath(specPath) {
+        const resolved = path.resolve(deps.specsDir, specPath);
+        const base = path.resolve(deps.specsDir);
+        if (resolved !== base && !resolved.startsWith(base + path.sep))
+            return null;
+        return resolved;
+    }
+    router.post('/spec/conformance-check', async (req, res) => {
+        let markdown;
+        if (typeof req.body?.markdown === 'string' && req.body.markdown.trim()) {
+            markdown = req.body.markdown;
+        }
+        else if (typeof req.body?.specPath === 'string' && req.body.specPath.trim()) {
+            const p = resolveSpecPath(req.body.specPath);
+            if (!p)
+                return res.status(400).json({ error: 'specPath escapes specsDir' });
+            if (!fs.existsSync(p))
+                return res.status(404).json({ error: 'spec not found' });
+            try {
+                markdown = fs.readFileSync(p, 'utf-8');
+            }
+            catch (err) {
+                return res.status(500).json({ error: `read failed: ${err.message}` });
+            }
+        }
+        else {
+            return res.status(400).json({ error: 'provide markdown or specPath' });
+        }
+        if (typeof markdown !== 'string' || !markdown.trim()) {
+            return res.status(400).json({ error: 'empty spec content' });
+        }
+        // Load + canary the constitution; a drifted/partial registry must not silently
+        // produce a misleadingly-clean report.
+        let articles;
+        try {
+            articles = loadStandardsRegistry(deps.registryPath);
+        }
+        catch (err) {
+            return res.status(503).json({ error: `constitution unreadable: ${err.message}` });
+        }
+        const canary = runRegistryCanary(articles);
+        const report = await reviewer.review(markdown, articles);
+        // Record metrics (best-effort).
+        try {
+            const m = loadMetrics(metricsFile);
+            m.runs += 1;
+            if (report.degraded)
+                m.degraded += 1;
+            m.findings_total += report.findings.length;
+            for (const f of report.findings)
+                m.by_standard[f.standard] = (m.by_standard[f.standard] ?? 0) + 1;
+            m.last_run_at = report.checkedAt;
+            saveMetrics(metricsFile, m);
+        }
+        catch { /* metering best-effort */ }
+        res.json({ report, registryCanary: canary });
+    });
+    router.get('/spec/conformance-metrics', (_req, res) => {
+        res.json({ metrics: loadMetrics(metricsFile) });
+    });
+    return router;
+}
+/** Exposed for the CLI (no HTTP): run a conformance check on raw markdown. */
+export async function runConformanceCheck(markdown, registryMarkdown, intelligence, model) {
+    const articles = parseStandardsRegistry(registryMarkdown);
+    const canary = runRegistryCanary(articles);
+    const reviewer = new StandardsConformanceReviewer(intelligence, { model });
+    const report = await reviewer.review(markdown, articles);
+    return { report, registryCanary: canary };
+}
+//# sourceMappingURL=specReviewRoutes.js.map

package/dist/server/specReviewRoutes.js.map

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

package/dist/threadline/ConversationStore.d.ts

@@ -0,0 +1,158 @@
+/**
+ * ConversationStore — the single source of truth for a Threadline conversation.
+ *
+ * Phase 1 of the Threadline re-assessment (THREADLINE-CONVERSATION-KEYSTONE-SPEC.md).
+ * Collapses the state previously smeared across `ThreadResumeMap`,
+ * `ContextThreadMap`, the in-memory peer-affinity map and `inbox.jsonl` into one
+ * durable record keyed by `threadId`. It is the ONLY place conversation turn
+ * state lives — the one-shot reply worker provably cannot self-police a loop, so
+ * the turn count + novelty hashes must live here, on the conversation.
+ *
+ * Concurrency: every write goes through `mutate(threadId, fn)`, a single-writer
+ * surface modeled on `CommitmentTracker.mutate()` — a per-threadId FIFO queue
+ * plus optimistic CAS on the record's `version`. This is the fix for the
+ * convergence-flagged race where two near-simultaneous inbound messages (or a
+ * live-inject racing a resume) would clobber `turnCount`/`lastOutboundHash` under
+ * the legacy last-writer-wins `load→mutate→persist`.
+ *
+ * Storage: {stateDir}/threadline/conversations.json (server-write-only, atomic
+ * tmp+rename). NOT relay-hosted — authoritative state stays local. The
+ * append-only SharedStateLedger remains the audit trail; this is the live
+ * mutable state it logs transitions from.
+ */
+/**
+ * Conversation lifecycle state. Superset of the legacy `ThreadState`
+ * (`active|idle|resolved|failed|archived`) plus `open` (created, not yet
+ * worked) and `awaiting-reply` (we replied, waiting on the peer). `idle` is
+ * also the warrants-a-reply gate's "suppressed, do not spawn" terminal-ish
+ * state.
+ */
+export type ConversationState = 'open' | 'active' | 'idle' | 'awaiting-reply' | 'resolved' | 'failed' | 'archived';
+/**
+ * The durable conversation record. EXHAUSTIVE against the legacy stores — an
+ * incomplete field list silently drops live data on migration (convergence
+ * finding). Every field the four legacy stores held is preserved here.
+ */
+export interface Conversation {
+    /** Primary key — the Threadline thread id. */
+    threadId: string;
+    /** Monotonic version for optimistic CAS in mutate(). */
+    version: number;
+    /** Conversation participants — self + peer fingerprint(s). */
+    participants: {
+        /** This agent's name/fingerprint (best-effort). */
+        self?: string;
+        /** Remote peer fingerprint(s). */
+        peers: string[];
+    };
+    /** Convenience display handle for the primary remote peer. */
+    remoteAgent?: string;
+    /** Lifecycle state. */
+    state: ConversationState;
+    /** When state became 'resolved' (grace-period clock). */
+    resolvedAt?: string;
+    /** The Claude/Codex session UUID the resume primitive depends on. */
+    sessionUuid?: string;
+    /** The live (or last-known) tmux session bound to this conversation. */
+    boundSessionName?: string;
+    /** Owning Telegram topic (formerly originTopicId). */
+    boundTopicId?: number;
+    /** Originating topic-session name at send time (fast-path resume cache). */
+    originSessionName?: string;
+    /** Spawn mode of the worker handling this conversation. */
+    spawnMode?: 'interactive' | 'pipe';
+    /** Thread subject. */
+    subject?: string;
+    /** A2A contextId mapped to this thread, if any. */
+    contextId?: string;
+    /**
+     * The authenticated agent identity that owns the contextId binding. Dropping
+     * this reopens the session-smuggling vector ContextThreadMap defends.
+     */
+    agentIdentity?: string;
+    pinned: boolean;
+    messageCount: number;
+    machineOrigin?: string;
+    migratedTo?: string;
+    migrateFrom?: string;
+    turnCount: number;
+    lastInboundHash?: string;
+    lastOutboundHash?: string;
+    createdAt: string;
+    savedAt: string;
+    lastActivityAt: string;
+    /** Snapshot of the unified-trust level at last contact. */
+    trustLevel?: string;
+    /** Snapshot of the MoltBridge IQS band at last contact. */
+    iqsBand?: string;
+}
+/** Mutation function: receives a draft clone, returns the next record. */
+export type ConversationMutateFn = (draft: Conversation) => Conversation | Promise<Conversation>;
+export declare class ConversationStore {
+    private filePath;
+    private store;
+    /** Per-threadId FIFO mutate queues — serialize concurrent writers. */
+    private mutateQueues;
+    private mutateRunning;
+    /** Ephemeral verified-only peer-affinity hints (peerFingerprint → hint). */
+    private affinity;
+    constructor(stateDir: string);
+    /** Get a conversation by threadId. Returns null if missing or TTL-expired. */
+    get(threadId: string): Conversation | null;
+    /** True if a (non-expired) conversation exists for the threadId. */
+    has(threadId: string): boolean;
+    /** Find conversations whose peer set includes the given fingerprint/name. */
+    getByParticipant(participant: string): Conversation[];
+    /** Find the conversation bound to a Telegram topic, if any. */
+    getByTopicId(topicId: number): Conversation | null;
+    /** Reverse lookup: conversation owning an A2A contextId (identity-bound). */
+    getByContextId(contextId: string, agentIdentity: string): Conversation | null;
+    /** List active/idle conversations (not resolved/failed/archived). */
+    listActive(): Conversation[];
+    /** Total stored conversations (for monitoring). */
+    size(): number;
+    /**
+     * Single-writer mutate surface. Every write path routes through here so
+     * concurrent writers (the inbound funnel gate, the router resume/spawn, the
+     * relay-send binding stamp) can't clobber each other.
+     *
+     * Contract (mirrors CommitmentTracker.mutate):
+     *  - FIFO queue per threadId, max depth 256.
+     *  - Optimistic CAS on `version`: read → fn(clone) → write iff version
+     *    unchanged, else retry (max 5). On success version is incremented and
+     *    the store is persisted atomically.
+     *  - If the conversation does not exist yet, the fn receives a fresh skeleton
+     *    (state 'open', version 0) so callers can upsert in one call.
+     */
+    mutate(threadId: string, fn: ConversationMutateFn): Promise<Conversation>;
+    private drainMutateQueue;
+    private applyMutationWithCAS;
+    /**
+     * Direct upsert of a full record WITHOUT going through the CAS queue. ONLY
+     * for migration / bulk import where there are no concurrent writers. Runtime
+     * writers MUST use mutate().
+     */
+    importDirect(conversation: Conversation): void;
+    /** Persist after a batch of importDirect calls. */
+    flush(): void;
+    /** Remove a conversation. */
+    remove(threadId: string): void;
+    /**
+     * Record a short-lived, verified-only affinity hint (peer → most-recent
+     * thread). Deliberately NOT persisted (accepted loss on restart). Callers
+     * MUST only call this for VERIFIED peers — an unverified affinity would be a
+     * hijack vector.
+     */
+    recordAffinity(peerFingerprint: string, threadId: string): void;
+    /** Look up a fresh affinity hint, honoring the sliding + absolute windows. */
+    getAffinity(peerFingerprint: string): string | null;
+    /** Prune expired + resolved-past-grace + LRU-overflow (non-pinned). */
+    prune(): void;
+    private skeleton;
+    private isExpired;
+    private pruneIfNeeded;
+    private pruneMap;
+    private loadStore;
+    private saveStore;
+}
+//# sourceMappingURL=ConversationStore.d.ts.map

package/dist/threadline/ConversationStore.d.ts.map

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

package/dist/threadline/ConversationStore.js

@@ -0,0 +1,341 @@
+/**
+ * ConversationStore — the single source of truth for a Threadline conversation.
+ *
+ * Phase 1 of the Threadline re-assessment (THREADLINE-CONVERSATION-KEYSTONE-SPEC.md).
+ * Collapses the state previously smeared across `ThreadResumeMap`,
+ * `ContextThreadMap`, the in-memory peer-affinity map and `inbox.jsonl` into one
+ * durable record keyed by `threadId`. It is the ONLY place conversation turn
+ * state lives — the one-shot reply worker provably cannot self-police a loop, so
+ * the turn count + novelty hashes must live here, on the conversation.
+ *
+ * Concurrency: every write goes through `mutate(threadId, fn)`, a single-writer
+ * surface modeled on `CommitmentTracker.mutate()` — a per-threadId FIFO queue
+ * plus optimistic CAS on the record's `version`. This is the fix for the
+ * convergence-flagged race where two near-simultaneous inbound messages (or a
+ * live-inject racing a resume) would clobber `turnCount`/`lastOutboundHash` under
+ * the legacy last-writer-wins `load→mutate→persist`.
+ *
+ * Storage: {stateDir}/threadline/conversations.json (server-write-only, atomic
+ * tmp+rename). NOT relay-hosted — authoritative state stays local. The
+ * append-only SharedStateLedger remains the audit trail; this is the live
+ * mutable state it logs transitions from.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+// ── Constants ───────────────────────────────────────────────────
+/** Entries older than 7 days are pruned (non-pinned only) — matches legacy TTL. */
+const MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+/** Resolved conversations get a 7-day grace before removal — matches legacy. */
+const RESOLVED_GRACE_MS = 7 * 24 * 60 * 60 * 1000;
+/** Cap before LRU eviction of non-pinned entries — matches ThreadResumeMap. */
+const MAX_ENTRIES = 1000;
+/** Max depth of the per-id mutate queue. Enqueue beyond this rejects. */
+const MUTATE_QUEUE_MAX_DEPTH = 256;
+/** Max CAS retries when the version drifts under an apply. */
+const MUTATE_CAS_MAX_RETRIES = 5;
+// ── Ephemeral verified-only peer-affinity (NOT persisted) ────────
+//
+// The legacy peer-affinity map is a SHORT (10-min sliding / 2-hr absolute),
+// verified-only, deliberately ephemeral hint — promoting it to a durable,
+// unverified binding would reopen a hijack vector (spec §1). We keep it in
+// memory on the store so it is lost on restart by design (accepted loss).
+const AFFINITY_SLIDING_MS = 10 * 60 * 1000;
+const AFFINITY_ABSOLUTE_MS = 2 * 60 * 60 * 1000;
+// ── Implementation ──────────────────────────────────────────────
+export class ConversationStore {
+    filePath;
+    store;
+    /** Per-threadId FIFO mutate queues — serialize concurrent writers. */
+    mutateQueues = new Map();
+    mutateRunning = new Set();
+    /** Ephemeral verified-only peer-affinity hints (peerFingerprint → hint). */
+    affinity = new Map();
+    constructor(stateDir) {
+        const threadlineDir = path.join(stateDir, 'threadline');
+        fs.mkdirSync(threadlineDir, { recursive: true });
+        this.filePath = path.join(threadlineDir, 'conversations.json');
+        this.store = this.loadStore();
+    }
+    // ── Reads (synchronous, from in-memory store) ──────────────────
+    /** Get a conversation by threadId. Returns null if missing or TTL-expired. */
+    get(threadId) {
+        const c = this.store.conversations[threadId];
+        if (!c)
+            return null;
+        if (!c.pinned && this.isExpired(c))
+            return null;
+        return c;
+    }
+    /** True if a (non-expired) conversation exists for the threadId. */
+    has(threadId) {
+        return this.get(threadId) !== null;
+    }
+    /** Find conversations whose peer set includes the given fingerprint/name. */
+    getByParticipant(participant) {
+        const out = [];
+        for (const c of Object.values(this.store.conversations)) {
+            if (c.pinned || !this.isExpired(c)) {
+                if (c.participants.peers.includes(participant) || c.remoteAgent === participant) {
+                    out.push(c);
+                }
+            }
+        }
+        return out;
+    }
+    /** Find the conversation bound to a Telegram topic, if any. */
+    getByTopicId(topicId) {
+        for (const c of Object.values(this.store.conversations)) {
+            if (c.boundTopicId === topicId && (c.pinned || !this.isExpired(c)))
+                return c;
+        }
+        return null;
+    }
+    /** Reverse lookup: conversation owning an A2A contextId (identity-bound). */
+    getByContextId(contextId, agentIdentity) {
+        for (const c of Object.values(this.store.conversations)) {
+            if (c.contextId === contextId && (c.pinned || !this.isExpired(c))) {
+                // Identity binding — prevents session smuggling (ContextThreadMap parity).
+                if (c.agentIdentity && c.agentIdentity !== agentIdentity)
+                    return null;
+                return c;
+            }
+        }
+        return null;
+    }
+    /** List active/idle conversations (not resolved/failed/archived). */
+    listActive() {
+        const out = [];
+        for (const c of Object.values(this.store.conversations)) {
+            if ((c.state === 'active' || c.state === 'idle' || c.state === 'open' || c.state === 'awaiting-reply') &&
+                (c.pinned || !this.isExpired(c))) {
+                out.push(c);
+            }
+        }
+        return out;
+    }
+    /** Total stored conversations (for monitoring). */
+    size() {
+        return Object.keys(this.store.conversations).length;
+    }
+    // ── Writes (single-writer CAS) ─────────────────────────────────
+    /**
+     * Single-writer mutate surface. Every write path routes through here so
+     * concurrent writers (the inbound funnel gate, the router resume/spawn, the
+     * relay-send binding stamp) can't clobber each other.
+     *
+     * Contract (mirrors CommitmentTracker.mutate):
+     *  - FIFO queue per threadId, max depth 256.
+     *  - Optimistic CAS on `version`: read → fn(clone) → write iff version
+     *    unchanged, else retry (max 5). On success version is incremented and
+     *    the store is persisted atomically.
+     *  - If the conversation does not exist yet, the fn receives a fresh skeleton
+     *    (state 'open', version 0) so callers can upsert in one call.
+     */
+    async mutate(threadId, fn) {
+        return new Promise((resolve, reject) => {
+            let queue = this.mutateQueues.get(threadId);
+            if (!queue) {
+                queue = [];
+                this.mutateQueues.set(threadId, queue);
+            }
+            if (queue.length >= MUTATE_QUEUE_MAX_DEPTH) {
+                reject(new Error(`ConversationStore.mutate: queue full for ${threadId} (depth ${queue.length} >= ${MUTATE_QUEUE_MAX_DEPTH})`));
+                return;
+            }
+            queue.push({ fn, resolve, reject });
+            void this.drainMutateQueue(threadId);
+        });
+    }
+    async drainMutateQueue(threadId) {
+        if (this.mutateRunning.has(threadId))
+            return;
+        this.mutateRunning.add(threadId);
+        try {
+            const queue = this.mutateQueues.get(threadId);
+            while (queue && queue.length > 0) {
+                const entry = queue.shift();
+                try {
+                    const result = await this.applyMutationWithCAS(threadId, entry.fn);
+                    entry.resolve(result);
+                }
+                catch (err) {
+                    entry.reject(err instanceof Error ? err : new Error(String(err)));
+                }
+            }
+            if (queue && queue.length === 0)
+                this.mutateQueues.delete(threadId);
+        }
+        finally {
+            this.mutateRunning.delete(threadId);
+        }
+    }
+    async applyMutationWithCAS(threadId, fn) {
+        let attempt = 0;
+        while (attempt <= MUTATE_CAS_MAX_RETRIES) {
+            const current = this.store.conversations[threadId] ?? this.skeleton(threadId);
+            const observedVersion = current.version ?? 0;
+            const draft = { ...current, participants: { ...current.participants, peers: [...current.participants.peers] } };
+            const next = await fn(draft);
+            // CAS: the record's version must not have drifted underneath us.
+            const latest = this.store.conversations[threadId];
+            const latestVersion = latest?.version ?? (latest ? 0 : observedVersion);
+            if (latest && latestVersion !== observedVersion) {
+                attempt++;
+                continue;
+            }
+            const committed = {
+                ...next,
+                threadId,
+                version: observedVersion + 1,
+                savedAt: new Date().toISOString(),
+            };
+            this.store.conversations[threadId] = committed;
+            this.pruneIfNeeded();
+            this.saveStore();
+            return committed;
+        }
+        throw new Error(`ConversationStore.mutate: CAS retry budget exhausted for ${threadId} after ${MUTATE_CAS_MAX_RETRIES} retries`);
+    }
+    /**
+     * Direct upsert of a full record WITHOUT going through the CAS queue. ONLY
+     * for migration / bulk import where there are no concurrent writers. Runtime
+     * writers MUST use mutate().
+     */
+    importDirect(conversation) {
+        const existing = this.store.conversations[conversation.threadId];
+        this.store.conversations[conversation.threadId] = {
+            ...conversation,
+            version: existing ? Math.max(existing.version ?? 0, conversation.version ?? 0) : (conversation.version ?? 0),
+            savedAt: new Date().toISOString(),
+        };
+    }
+    /** Persist after a batch of importDirect calls. */
+    flush() {
+        this.saveStore();
+    }
+    /** Remove a conversation. */
+    remove(threadId) {
+        if (this.store.conversations[threadId]) {
+            delete this.store.conversations[threadId];
+            this.saveStore();
+        }
+    }
+    // ── Ephemeral verified-only peer affinity (in-memory, non-durable) ──
+    /**
+     * Record a short-lived, verified-only affinity hint (peer → most-recent
+     * thread). Deliberately NOT persisted (accepted loss on restart). Callers
+     * MUST only call this for VERIFIED peers — an unverified affinity would be a
+     * hijack vector.
+     */
+    recordAffinity(peerFingerprint, threadId) {
+        const now = Date.now();
+        const existing = this.affinity.get(peerFingerprint);
+        if (existing && existing.threadId === threadId) {
+            existing.lastSeen = now;
+        }
+        else {
+            this.affinity.set(peerFingerprint, { threadId, firstSeen: now, lastSeen: now });
+        }
+    }
+    /** Look up a fresh affinity hint, honoring the sliding + absolute windows. */
+    getAffinity(peerFingerprint) {
+        const hint = this.affinity.get(peerFingerprint);
+        if (!hint)
+            return null;
+        const now = Date.now();
+        if (now - hint.lastSeen > AFFINITY_SLIDING_MS || now - hint.firstSeen > AFFINITY_ABSOLUTE_MS) {
+            this.affinity.delete(peerFingerprint);
+            return null;
+        }
+        return hint.threadId;
+    }
+    // ── Maintenance ────────────────────────────────────────────────
+    /** Prune expired + resolved-past-grace + LRU-overflow (non-pinned). */
+    prune() {
+        this.pruneMap();
+        this.saveStore();
+    }
+    // ── Private helpers ────────────────────────────────────────────
+    skeleton(threadId) {
+        const now = new Date().toISOString();
+        return {
+            threadId,
+            version: 0,
+            participants: { peers: [] },
+            state: 'open',
+            pinned: false,
+            messageCount: 0,
+            turnCount: 0,
+            createdAt: now,
+            savedAt: now,
+            lastActivityAt: now,
+        };
+    }
+    isExpired(c) {
+        const now = Date.now();
+        if (c.state === 'resolved' && c.resolvedAt) {
+            return now - new Date(c.resolvedAt).getTime() > RESOLVED_GRACE_MS;
+        }
+        const ref = c.lastActivityAt || c.savedAt;
+        return now - new Date(ref).getTime() > MAX_AGE_MS;
+    }
+    pruneIfNeeded() {
+        if (Object.keys(this.store.conversations).length > MAX_ENTRIES)
+            this.pruneMap();
+    }
+    pruneMap() {
+        const map = this.store.conversations;
+        // Phase 1: drop expired / resolved-past-grace (non-pinned).
+        for (const key of Object.keys(map)) {
+            const c = map[key];
+            if (c.pinned)
+                continue;
+            if (this.isExpired(c))
+                delete map[key];
+        }
+        // Phase 2: LRU eviction if still over cap.
+        const keys = Object.keys(map);
+        if (keys.length <= MAX_ENTRIES)
+            return;
+        const unpinned = [];
+        for (const key of keys) {
+            const c = map[key];
+            if (c.pinned)
+                continue;
+            unpinned.push({ key, t: new Date(c.lastActivityAt || c.savedAt).getTime() });
+        }
+        unpinned.sort((a, b) => a.t - b.t);
+        const toEvict = keys.length - MAX_ENTRIES;
+        for (let i = 0; i < toEvict && i < unpinned.length; i++) {
+            delete map[unpinned[i].key];
+        }
+    }
+    loadStore() {
+        try {
+            if (fs.existsSync(this.filePath)) {
+                const data = JSON.parse(fs.readFileSync(this.filePath, 'utf-8'));
+                if (data && data.version === 1 && data.conversations && typeof data.conversations === 'object') {
+                    return data;
+                }
+            }
+        }
+        catch {
+            // Corrupted — start fresh.
+        }
+        return { version: 1, conversations: {}, lastModified: new Date().toISOString() };
+    }
+    saveStore() {
+        this.store.lastModified = new Date().toISOString();
+        try {
+            const dir = path.dirname(this.filePath);
+            fs.mkdirSync(dir, { recursive: true });
+            const tmpPath = `${this.filePath}.${process.pid}.tmp`;
+            fs.writeFileSync(tmpPath, JSON.stringify(this.store, null, 2) + '\n');
+            fs.renameSync(tmpPath, this.filePath);
+        }
+        catch {
+            // @silent-fallback-ok — state persistence failure, retried on next write.
+        }
+    }
+}
+//# sourceMappingURL=ConversationStore.js.map