instar 1.2.37 → 1.2.39

package/dist/core/TopicIntentArcCheck.js

@@ -0,0 +1,146 @@
+/**
+ * TopicIntentArcCheck — Layer 3 of the Topic Intent Layer.
+ *
+ * Pre-send classifier that scans an agent's draft reply against the
+ * topic's current tentative + settled items. Fires signals (not blocks)
+ * when the draft would:
+ *   - Act on a tentative item without conversational confirmation
+ *   - Contradict an item already at authoritative tier
+ *
+ * Per spec v14 sections "How the agent asks for confirmation" and
+ * "Authority on send" — ArcCheck is SIGNAL-only. The existing outbound
+ * gate retains authority. The fired signal includes a suggested rewrite
+ * hint, but never blocks. The agent itself decides whether to redraft.
+ *
+ * Per `feedback_gate_latency_vs_client_timeout`: ArcCheck is designed
+ * to run concurrent with send-prep, not as a serial second gate. The
+ * timeout is enforced at the HTTP route layer (route caller sets the
+ * deadline; classifier itself is pure async).
+ *
+ * Per `feedback_signal_vs_authority`: ArcCheck is the brittle/low-context
+ * filter that detects and emits a signal. The higher-level outbound gate
+ * (tone-gate, response-review) has blocking authority. Two-layer split.
+ *
+ * Framework-agnostic: the LLM call is injected. Production wires it to
+ * Instar's LlmQueue + IntelligenceProvider; tests stub it.
+ */
+export class ArcCheck {
+    store;
+    classifyFn;
+    constructor(store, classifyFn) {
+        this.store = store;
+        this.classifyFn = classifyFn;
+    }
+    /**
+     * Run ArcCheck on a draft. Returns a verdict object suitable for direct
+     * return from an HTTP route or consumption by a hook.
+     *
+     * Verdict priority (when multiple conditions fire):
+     *   1. contradicts-settled (highest — wrong direction on a decided item)
+     *   2. acting-on-tentative (lower — uncertain, but not wrong)
+     *
+     * If the draft engages multiple refs, the first matching one of the
+     * highest-priority kind wins. Subsequent fires are deferred to a
+     * future ArcCheck call after the agent's redraft.
+     */
+    async check(input) {
+        const refs = this.store.getRefsAtOrAbove(input.topicId, 'tentative');
+        if (refs.length === 0)
+            return { fire: false };
+        const classification = await this.classifyFn(input.draftText, refs);
+        // Priority 1: contradicts settled item
+        for (const refId of classification.contradicts) {
+            const ref = refs.find(r => r.refId === refId);
+            if (ref && ref.projection.tier === 'authoritative') {
+                return {
+                    fire: true,
+                    kind: 'contradicts-settled',
+                    refId,
+                    refText: ref.text,
+                    currentTier: 'authoritative',
+                    currentConfidence: ref.projection.confidence,
+                    reason: `draft appears to contradict settled item "${ref.text}"`,
+                    suggestedRewriteHint: `Pause and surface the contradiction in plain English: ` +
+                        `acknowledge we previously settled on "${ref.text}", flag that the current draft would change that, ` +
+                        `and ask the user to confirm the change before proceeding.`,
+                };
+            }
+        }
+        // Priority 2: acting on tentative item
+        for (const refId of classification.actsOn) {
+            const ref = refs.find(r => r.refId === refId);
+            if (ref && ref.projection.tier === 'tentative') {
+                return {
+                    fire: true,
+                    kind: 'acting-on-tentative',
+                    refId,
+                    refText: ref.text,
+                    currentTier: 'tentative',
+                    currentConfidence: ref.projection.confidence,
+                    reason: `draft acts on tentative item "${ref.text}" (confidence ${ref.projection.confidence.toFixed(2)}) without explicit confirmation`,
+                    suggestedRewriteHint: `Add a brief natural-language confirmation question before the action: ` +
+                        `"I'm planning to use ${ref.text} here — just want to make sure that's still the call. ` +
+                        `If we settled on something else, let me know."`,
+                };
+            }
+        }
+        return { fire: false };
+    }
+}
+/**
+ * Build the ArcCheck prompt for production use. Separated so prompt
+ * tuning can iterate without touching the classifier logic.
+ *
+ * The actual LLM provider call is wired in by the caller; this returns
+ * the prompt string + structured response schema description.
+ */
+export function buildArcCheckPrompt(draftText, refs) {
+    const systemPrompt = `You are an arc-check classifier for a conversation. Your job is to read a draft agent reply and identify whether it ACTS ON or CONTRADICTS any items the conversation is currently tracking.
+
+Output a JSON object: {"actsOn": ["<refId>", …], "contradicts": ["<refId>", …]}.
+
+Rules:
+- Be CONSERVATIVE. Most drafts engage with ZERO tracked refs. Don't pattern-match loosely.
+- "actsOn" means the draft proceeds as if the ref is true / decided (uses the OAuth path, assumes the timeout value, etc.).
+- "contradicts" means the draft says or implies the OPPOSITE of the ref's text.
+- Mere mention of the same topic area is NOT engagement. The draft must commit to action ON the proposition.
+- If unsure, return empty arrays.`;
+    const refsBlock = refs
+        .map(r => `- refId=${r.refId} tier=${r.projection.tier} text="${r.text}"`)
+        .join('\n');
+    const userPrompt = `Draft agent reply:
+"""
+${draftText}
+"""
+
+Currently tracked refs on this topic:
+${refsBlock}
+
+Return JSON: {"actsOn": [...], "contradicts": [...]}`;
+    return { systemPrompt, userPrompt };
+}
+/**
+ * Parse the LLM's response into an ArcCheckClassification. Tolerates
+ * code fences and prose preamble; degrades to empty arrays on parse
+ * failure so a busted LLM response never falsely fires ArcCheck.
+ */
+export function parseArcCheckResponse(raw) {
+    let cleaned = raw.trim();
+    const fenceMatch = cleaned.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
+    if (fenceMatch)
+        cleaned = fenceMatch[1];
+    const start = cleaned.indexOf('{');
+    const end = cleaned.lastIndexOf('}');
+    if (start === -1 || end === -1 || end <= start)
+        return { actsOn: [], contradicts: [] };
+    try {
+        const parsed = JSON.parse(cleaned.slice(start, end + 1));
+        const actsOn = Array.isArray(parsed.actsOn) ? parsed.actsOn.filter((s) => typeof s === 'string') : [];
+        const contradicts = Array.isArray(parsed.contradicts) ? parsed.contradicts.filter((s) => typeof s === 'string') : [];
+        return { actsOn, contradicts };
+    }
+    catch {
+        return { actsOn: [], contradicts: [] };
+    }
+}
+//# sourceMappingURL=TopicIntentArcCheck.js.map

package/dist/core/TopicIntentArcCheck.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TopicIntentArcCheck.js","sourceRoot":"","sources":["../../src/core/TopicIntentArcCheck.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAiDH,MAAM,OAAO,QAAQ;IAET;IACA;IAFV,YACU,KAAuB,EACvB,UAA8B;QAD9B,UAAK,GAAL,KAAK,CAAkB;QACvB,eAAU,GAAV,UAAU,CAAoB;IACrC,CAAC;IAEJ;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,KAAK,CAAC,KAAoB;QAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,KAAK,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QACrE,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;QAE9C,MAAM,cAAc,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QAEpE,uCAAuC;QACvC,KAAK,MAAM,KAAK,IAAI,cAAc,CAAC,WAAW,EAAE,CAAC;YAC/C,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;YAC9C,IAAI,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,KAAK,eAAe,EAAE,CAAC;gBACnD,OAAO;oBACL,IAAI,EAAE,IAAI;oBACV,IAAI,EAAE,qBAAqB;oBAC3B,KAAK;oBACL,OAAO,EAAE,GAAG,CAAC,IAAI;oBACjB,WAAW,EAAE,eAAe;oBAC5B,iBAAiB,EAAE,GAAG,CAAC,UAAU,CAAC,UAAU;oBAC5C,MAAM,EAAE,6CAA6C,GAAG,CAAC,IAAI,GAAG;oBAChE,oBAAoB,EAClB,wDAAwD;wBACxD,yCAAyC,GAAG,CAAC,IAAI,oDAAoD;wBACrG,2DAA2D;iBAC9D,CAAC;YACJ,CAAC;QACH,CAAC;QAED,uCAAuC;QACvC,KAAK,MAAM,KAAK,IAAI,cAAc,CAAC,MAAM,EAAE,CAAC;YAC1C,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;YAC9C,IAAI,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;gBAC/C,OAAO;oBACL,IAAI,EAAE,IAAI;oBACV,IAAI,EAAE,qBAAqB;oBAC3B,KAAK;oBACL,OAAO,EAAE,GAAG,CAAC,IAAI;oBACjB,WAAW,EAAE,WAAW;oBACxB,iBAAiB,EAAE,GAAG,CAAC,UAAU,CAAC,UAAU;oBAC5C,MAAM,EAAE,iCAAiC,GAAG,CAAC,IAAI,iBAAiB,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,iCAAiC;oBACvI,oBAAoB,EAClB,wEAAwE;wBACxE,wBAAwB,GAAG,CAAC,IAAI,wDAAwD;wBACxF,gDAAgD;iBACnD,CAAC;YACJ,CAAC;QACH,CAAC;QAED,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IACzB,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,SAAiB,EACjB,IAA8D;IAE9D,MAAM,YAAY,GAAG;;;;;;;;;kCASW,CAAC;IAEjC,MAAM,SAAS,GAAG,IAAI;SACnB,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,WAAW,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,UAAU,CAAC,IAAI,UAAU,CAAC,CAAC,IAAI,GAAG,CAAC;SACzE,IAAI,CAAC,IAAI,CAAC,CAAC;IAEd,MAAM,UAAU,GAAG;;EAEnB,SAAS;;;;EAIT,SAAS;;qDAE0C,CAAC;IAEpD,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,CAAC;AACtC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAW;IAC/C,IAAI,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IACzB,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC;IACpE,IAAI,UAAU;QAAE,OAAO,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;IAExC,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACnC,MAAM,GAAG,GAAG,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACrC,IAAI,KAAK,KAAK,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC,IAAI,GAAG,IAAI,KAAK;QAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC;IAEvF,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QACzD,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAU,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/G,MAAM,WAAW,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAU,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9H,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC;IACzC,CAAC;AACH,CAAC"}

package/dist/core/TopicIntentBriefing.d.ts

@@ -0,0 +1,44 @@
+/**
+ * TopicIntentBriefing — Layer 2 of the Topic Intent Layer.
+ *
+ * Renders the per-topic semantic state as a plain-text briefing that the
+ * bootstrap context hooks prepend to the conversation history. Replaces
+ * "here's the transcript" with "here's the arc, then the transcript."
+ *
+ * Per spec v14 section "Layer 2 — arc-aware continuation header":
+ *   - Stated goal of the topic (when extracted; optional)
+ *   - Open threads (tentative items with extracted text, hedged)
+ *   - Established (authoritative items, unhedged)
+ *   - Observation tier is NOT surfaced
+ *
+ * Framework-agnostic: pure rendering function. Same output reachable from
+ * Claude Code bootstrap hooks, Codex bootstrap equivalents, and any other
+ * harness that wants the briefing as a plain string.
+ */
+import { TopicIntentStore } from './TopicIntent.js';
+export interface BriefingOptions {
+    /** Override "now" for time-sensitive projections (testing). */
+    nowMs?: number;
+    /** Maximum number of items per section (defaults to 8). */
+    maxPerSection?: number;
+}
+export interface BriefingResult {
+    /** The full briefing text. Empty string when nothing tracked yet. */
+    text: string;
+    /** Whether anything was rendered (false → safe to skip injection entirely). */
+    hasContent: boolean;
+    /** Counts for telemetry / diagnostics. */
+    counts: {
+        authoritative: number;
+        tentative: number;
+        /** Outstanding pending confirmation (if any). */
+        pendingOutstanding: boolean;
+    };
+}
+/**
+ * Render the briefing for a topic. Returns an empty string when nothing has
+ * accumulated to authoritative or tentative tier yet — observation-only is
+ * not surfaced to avoid noise.
+ */
+export declare function renderTopicIntentBriefing(store: TopicIntentStore, topicId: number, opts?: BriefingOptions): BriefingResult;
+//# sourceMappingURL=TopicIntentBriefing.d.ts.map

package/dist/core/TopicIntentBriefing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TopicIntentBriefing.d.ts","sourceRoot":"","sources":["../../src/core/TopicIntentBriefing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,UAAU,EAAE,OAAO,CAAC;IACpB,0CAA0C;IAC1C,MAAM,EAAE;QACN,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,iDAAiD;QACjD,kBAAkB,EAAE,OAAO,CAAC;KAC7B,CAAC;CACH;AAID;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,gBAAgB,EACvB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,eAAoB,GACzB,cAAc,CAqEhB"}

package/dist/core/TopicIntentBriefing.js

@@ -0,0 +1,88 @@
+/**
+ * TopicIntentBriefing — Layer 2 of the Topic Intent Layer.
+ *
+ * Renders the per-topic semantic state as a plain-text briefing that the
+ * bootstrap context hooks prepend to the conversation history. Replaces
+ * "here's the transcript" with "here's the arc, then the transcript."
+ *
+ * Per spec v14 section "Layer 2 — arc-aware continuation header":
+ *   - Stated goal of the topic (when extracted; optional)
+ *   - Open threads (tentative items with extracted text, hedged)
+ *   - Established (authoritative items, unhedged)
+ *   - Observation tier is NOT surfaced
+ *
+ * Framework-agnostic: pure rendering function. Same output reachable from
+ * Claude Code bootstrap hooks, Codex bootstrap equivalents, and any other
+ * harness that wants the briefing as a plain string.
+ */
+const DEFAULT_MAX_PER_SECTION = 8;
+/**
+ * Render the briefing for a topic. Returns an empty string when nothing has
+ * accumulated to authoritative or tentative tier yet — observation-only is
+ * not surfaced to avoid noise.
+ */
+export function renderTopicIntentBriefing(store, topicId, opts = {}) {
+    const max = opts.maxPerSection ?? DEFAULT_MAX_PER_SECTION;
+    const nowMs = opts.nowMs;
+    const file = store.read(topicId);
+    const refs = store.getRefsAtOrAbove(topicId, 'tentative', nowMs);
+    const authoritative = refs.filter(r => r.projection.tier === 'authoritative');
+    const tentative = refs.filter(r => r.projection.tier === 'tentative');
+    if (authoritative.length === 0 && tentative.length === 0 && !file.pending.outstanding) {
+        return {
+            text: '',
+            hasContent: false,
+            counts: { authoritative: 0, tentative: 0, pendingOutstanding: false },
+        };
+    }
+    const lines = [];
+    lines.push(`=== TOPIC ${topicId} INTENT BRIEFING (auto-injected) ===`);
+    lines.push(`The agent has been tracking the arc of this conversation. Read this before responding —`);
+    lines.push(`it's the goal-and-decisions context that won't appear in the message history alone.`);
+    if (authoritative.length > 0) {
+        lines.push('');
+        lines.push('SETTLED (treat as decided unless you see a contradiction):');
+        for (const r of sortByConfidenceDesc(authoritative).slice(0, max)) {
+            const kindTag = r.kind === 'decision' ? '[decision]' : '[fact]';
+            lines.push(`  • ${kindTag} ${r.text}`);
+        }
+        if (authoritative.length > max) {
+            lines.push(`  • (… ${authoritative.length - max} more settled items not shown)`);
+        }
+    }
+    if (tentative.length > 0) {
+        lines.push('');
+        lines.push('TENTATIVE (agent operating on these but not confirmed — verify before acting):');
+        for (const r of sortByConfidenceDesc(tentative).slice(0, max)) {
+            const kindTag = r.kind === 'decision' ? '[decision]' : '[fact]';
+            const conf = `(confidence ${r.projection.confidence.toFixed(2)})`;
+            lines.push(`  • ${kindTag} ${r.text} ${conf}`);
+        }
+        if (tentative.length > max) {
+            lines.push(`  • (… ${tentative.length - max} more tentative items not shown)`);
+        }
+    }
+    if (file.pending.outstanding) {
+        const pc = file.pending.outstanding;
+        lines.push('');
+        lines.push('PENDING CONFIRMATION (the agent asked the user about this; awaiting answer):');
+        lines.push(`  • "${pc.propositionText}"`);
+        lines.push(`    asked at turn ${pc.sentAtTurn} (retries: ${pc.retries}/${pc.maxRetries})`);
+        lines.push(`    if the user just answered, the next response should record the verdict.`);
+    }
+    lines.push('');
+    lines.push('=== END TOPIC INTENT BRIEFING ===');
+    return {
+        text: lines.join('\n'),
+        hasContent: true,
+        counts: {
+            authoritative: authoritative.length,
+            tentative: tentative.length,
+            pendingOutstanding: file.pending.outstanding !== null,
+        },
+    };
+}
+function sortByConfidenceDesc(arr) {
+    return [...arr].sort((a, b) => b.projection.confidence - a.projection.confidence);
+}
+//# sourceMappingURL=TopicIntentBriefing.js.map

package/dist/core/TopicIntentBriefing.js.map

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

package/dist/core/TopicIntentExtractor.d.ts

@@ -0,0 +1,90 @@
+/**
+ * TopicIntentExtractor — converts a raw conversation turn into EvidenceEvents.
+ *
+ * Layer 1 component. Reads a new substantive message + the topic's existing
+ * EstablishedRef set, asks a Tier-1 LLM to identify signal events (new
+ * extractions, re-references, affirmations, contradictions), and persists
+ * them via TopicIntentStore.appendEvidence.
+ *
+ * Framework-agnostic: the LLM call itself is injected. Production wires it
+ * to Instar's LlmQueue + chosen provider; tests stub it.
+ *
+ * The extractor returns the events it CREATED so callers can act on them
+ * (e.g., trigger conflict-mark when two refs come into conflict).
+ */
+import { TopicIntentStore, type EvidenceEvent, type RefKind, type EstablishedRef } from './TopicIntent.js';
+export interface ExtractorInput {
+    topicId: number;
+    arcId: string;
+    message: {
+        id: string;
+        text: string;
+        fromUser: boolean;
+        turn: number;
+        at: string;
+    };
+    /** Existing refs on the topic, provided so the LLM can anchor signals. */
+    existingRefs: EstablishedRef[];
+}
+/**
+ * The LLM is asked to return zero or more SignalProposals per message.
+ * Each proposal references either an existing refId (re-reference,
+ * affirmation, contradiction) OR a new ref proposition text (initial
+ * extraction).
+ *
+ * The actual provider call is injected; this type is the contract.
+ */
+export interface SignalProposal {
+    kind: 'new-ref' | 'reref' | 'affirm' | 'contradict';
+    /** Required for reref / affirm / contradict; null for new-ref. */
+    refId: string | null;
+    /** Required for new-ref; describes the proposition being extracted. */
+    propositionText?: string;
+    /** Required for new-ref; the type of proposition. */
+    refKind?: RefKind;
+    /** Optional: extractor's confidence in this signal (for logging; not used in projection). */
+    llmConfidence?: number;
+}
+export type ExtractFn = (input: ExtractorInput) => Promise<SignalProposal[]>;
+export interface ExtractorResult {
+    emitted: EvidenceEvent[];
+    createdRefs: Array<{
+        refId: string;
+        kind: RefKind;
+        text: string;
+    }>;
+    skipped: number;
+}
+export declare class TopicIntentExtractor {
+    private store;
+    private extractFn;
+    constructor(store: TopicIntentStore, extractFn: ExtractFn);
+    /**
+     * Process a new message: run the LLM, translate proposals to events,
+     * append to store, return what was created.
+     */
+    ingest(input: ExtractorInput): Promise<ExtractorResult>;
+    /**
+     * Translate a SignalProposal into the (refId, EvidenceEvent, refInit?) tuple
+     * to be appended. Returns null if the proposal is invalid.
+     */
+    private translateProposal;
+}
+/**
+ * Build the extractor prompt for production use. Separated so prompt
+ * tuning can iterate without touching the extractor logic.
+ *
+ * The actual LLM provider call is wired in by the caller; this function
+ * returns the prompt string + the JSON schema description for the
+ * structured response.
+ */
+export declare function buildExtractorPrompt(input: ExtractorInput): {
+    systemPrompt: string;
+    userPrompt: string;
+};
+/**
+ * Parse the LLM's response into SignalProposal[]. Tolerates the LLM
+ * wrapping the JSON in code fences or prose preamble.
+ */
+export declare function parseExtractorResponse(raw: string): SignalProposal[];
+//# sourceMappingURL=TopicIntentExtractor.d.ts.map

package/dist/core/TopicIntentExtractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TopicIntentExtractor.d.ts","sourceRoot":"","sources":["../../src/core/TopicIntentExtractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EACL,gBAAgB,EAEhB,KAAK,aAAa,EAElB,KAAK,OAAO,EACZ,KAAK,cAAc,EAEpB,MAAM,kBAAkB,CAAC;AAE1B,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE;QACP,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,OAAO,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,EAAE,EAAE,MAAM,CAAC;KACZ,CAAC;IACF,0EAA0E;IAC1E,YAAY,EAAE,cAAc,EAAE,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,YAAY,CAAC;IACpD,kEAAkE;IAClE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,uEAAuE;IACvE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,qDAAqD;IACrD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,6FAA6F;IAC7F,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,cAAc,KAAK,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;AAE7E,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,WAAW,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,oBAAoB;IAE7B,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,SAAS;gBADT,KAAK,EAAE,gBAAgB,EACvB,SAAS,EAAE,SAAS;IAG9B;;;OAGG;IACG,MAAM,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IAwB7D;;;OAGG;IACH,OAAO,CAAC,iBAAiB;CAuC1B;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,cAAc,GAAG;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CA8BxG;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,EAAE,CAkBpE"}

package/dist/core/TopicIntentExtractor.js

@@ -0,0 +1,153 @@
+/**
+ * TopicIntentExtractor — converts a raw conversation turn into EvidenceEvents.
+ *
+ * Layer 1 component. Reads a new substantive message + the topic's existing
+ * EstablishedRef set, asks a Tier-1 LLM to identify signal events (new
+ * extractions, re-references, affirmations, contradictions), and persists
+ * them via TopicIntentStore.appendEvidence.
+ *
+ * Framework-agnostic: the LLM call itself is injected. Production wires it
+ * to Instar's LlmQueue + chosen provider; tests stub it.
+ *
+ * The extractor returns the events it CREATED so callers can act on them
+ * (e.g., trigger conflict-mark when two refs come into conflict).
+ */
+import { randomUUID } from 'node:crypto';
+import { buildEvent, } from './TopicIntent.js';
+export class TopicIntentExtractor {
+    store;
+    extractFn;
+    constructor(store, extractFn) {
+        this.store = store;
+        this.extractFn = extractFn;
+    }
+    /**
+     * Process a new message: run the LLM, translate proposals to events,
+     * append to store, return what was created.
+     */
+    async ingest(input) {
+        const proposals = await this.extractFn(input);
+        const emitted = [];
+        const createdRefs = [];
+        let skipped = 0;
+        for (const p of proposals) {
+            const translated = this.translateProposal(p, input);
+            if (!translated) {
+                skipped++;
+                continue;
+            }
+            const { refId, ev, refInit } = translated;
+            this.store.appendEvidence(input.topicId, refId, ev, refInit);
+            emitted.push(ev);
+            if (p.kind === 'new-ref' && refInit) {
+                createdRefs.push({ refId, kind: refInit.kind ?? 'fact', text: refInit.text ?? '' });
+            }
+        }
+        return { emitted, createdRefs, skipped };
+    }
+    /**
+     * Translate a SignalProposal into the (refId, EvidenceEvent, refInit?) tuple
+     * to be appended. Returns null if the proposal is invalid.
+     */
+    translateProposal(p, input) {
+        const { message, arcId } = input;
+        if (p.kind === 'new-ref') {
+            if (!p.propositionText || !p.refKind)
+                return null;
+            const refId = `ref-${randomUUID()}`;
+            const evKind = message.fromUser ? 'extract-user' : 'extract-agent';
+            const ev = buildEvent(refId, evKind, message.id, { at: message.at });
+            return {
+                refId,
+                ev,
+                refInit: { text: p.propositionText, kind: p.refKind, arcId },
+            };
+        }
+        // For reref / affirm / contradict, the proposal must point to an existing refId
+        if (!p.refId)
+            return null;
+        const existing = input.existingRefs.find(r => r.refId === p.refId);
+        if (!existing)
+            return null;
+        let evKind;
+        if (p.kind === 'reref') {
+            evKind = message.fromUser ? 'user-reref' : 'agent-reref';
+        }
+        else if (p.kind === 'affirm') {
+            // Only user messages produce affirm signals; agent messages mapping to "affirm" are bookkeeping reref
+            if (!message.fromUser)
+                return null;
+            evKind = 'user-affirm';
+        }
+        else {
+            // contradict — only user-authored
+            if (!message.fromUser)
+                return null;
+            evKind = 'contradiction';
+        }
+        const ev = buildEvent(p.refId, evKind, message.id, { at: message.at });
+        return { refId: p.refId, ev };
+    }
+}
+/**
+ * Build the extractor prompt for production use. Separated so prompt
+ * tuning can iterate without touching the extractor logic.
+ *
+ * The actual LLM provider call is wired in by the caller; this function
+ * returns the prompt string + the JSON schema description for the
+ * structured response.
+ */
+export function buildExtractorPrompt(input) {
+    const systemPrompt = `You are an arc-tracking extractor for a multi-turn conversation. Your job is to read one new message and identify candidate facts and decisions that the conversation is establishing, plus references / affirmations / contradictions of previously-tracked items.
+
+Output a JSON array of signal proposals. Each item is one of:
+- {"kind":"new-ref","propositionText":"<the candidate fact or decision in 1-2 sentences>","refKind":"fact"|"decision"}
+- {"kind":"reref","refId":"<existing refId>"}
+- {"kind":"affirm","refId":"<existing refId>"}
+- {"kind":"contradict","refId":"<existing refId>"}
+
+Rules:
+- Be CONSERVATIVE. Most messages produce zero or one signal. Don't extract trivia.
+- Anchor "reref"/"affirm"/"contradict" to an existing refId only if the message clearly references the same proposition.
+- "affirm" is for explicit agreement ("yes", "exactly", "agreed").
+- "contradict" is for explicit disagreement ("actually no", "we switched to X").
+- "new-ref" is reserved for SIGNIFICANT items that warrant tracking — not every passing remark.
+- If unsure, return [].`;
+    const refsBlock = input.existingRefs.length === 0
+        ? '(no existing refs tracked yet)'
+        : input.existingRefs.map(r => `- refId=${r.refId} kind=${r.kind} text="${r.text}" tier=${r.confidence >= 0.7 ? 'authoritative' : r.confidence >= 0.3 ? 'tentative' : 'observation'}`).join('\n');
+    const userPrompt = `New message (fromUser=${input.message.fromUser}, turn=${input.message.turn}):
+${input.message.text}
+
+Currently tracked refs on this topic:
+${refsBlock}
+
+Return JSON array of signal proposals.`;
+    return { systemPrompt, userPrompt };
+}
+/**
+ * Parse the LLM's response into SignalProposal[]. Tolerates the LLM
+ * wrapping the JSON in code fences or prose preamble.
+ */
+export function parseExtractorResponse(raw) {
+    // Strip code fences if present
+    let cleaned = raw.trim();
+    const fenceMatch = cleaned.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
+    if (fenceMatch)
+        cleaned = fenceMatch[1];
+    // Find the first [ and matching final ]
+    const start = cleaned.indexOf('[');
+    const end = cleaned.lastIndexOf(']');
+    if (start === -1 || end === -1 || end <= start)
+        return [];
+    try {
+        const parsed = JSON.parse(cleaned.slice(start, end + 1));
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter(p => p && typeof p === 'object' && typeof p.kind === 'string');
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=TopicIntentExtractor.js.map

package/dist/core/TopicIntentExtractor.js.map

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

package/dist/core/TopicIntentPendingConfirm.d.ts

@@ -0,0 +1,96 @@
+/**
+ * PendingConfirmationManager — lifecycle for conversational confirmation records.
+ *
+ * Layer 1 component. Manages the queue, TTL, dedup, retry-with-sharpening,
+ * and revalidation rules for pending confirmations. Per spec v14 section
+ * "Pending-Confirmation Records (v9 — addresses GPT round-on-v8 finding #2)":
+ *
+ *   - At most one outstanding PendingConfirmation per topic
+ *   - Queue depth: 3; 4th queued is dropped silently with telemetry
+ *   - Queue dedup by refId
+ *   - TTL: 5 substantive user turns OR 24h, whichever first
+ *   - TTL clock starts at DEQUEUE time, not queue-entry time
+ *   - Revalidation at dequeue: refId still tentative + proposition still
+ *     semantically relevant; stale → drop silently with telemetry
+ *   - Answer interpretation by Tier 1 LLM (positive / negative / ambiguous /
+ *     non-responsive); ambiguous triggers sharpen + retry up to maxRetries=2,
+ *     then status=abandoned
+ *
+ * Framework-agnostic: pure logic over the JSON store. No transport coupling.
+ */
+import { TopicIntentStore, type PendingConfirmation, type TopicIntentFile } from './TopicIntent.js';
+export type AnswerVerdict = 'positive' | 'negative' | 'ambiguous' | 'non-responsive';
+export interface CreateOpts {
+    topicId: number;
+    arcId: string;
+    refId: string;
+    propositionText: string;
+    questionText: string;
+    currentUserTurn: number;
+    now?: string;
+    ttl?: {
+        turns: number;
+        hours: number;
+    };
+    maxRetries?: number;
+}
+export interface RevalidationResult {
+    valid: boolean;
+    reason?: 'no-longer-tentative' | 'proposition-stale' | 'ref-missing' | 'ok';
+}
+/**
+ * Operator-supplied callbacks. Both are deterministic from the manager's
+ * point of view — the caller routes them to whatever LLM/lexical check
+ * makes sense in context.
+ */
+export interface PendingConfirmCallbacks {
+    /**
+     * Asked at DEQUEUE time. Returns whether the queued proposition is still
+     * semantically relevant given more recent events on the topic.
+     * Default: always valid (no-op stub for tests / pre-Layer-3).
+     */
+    revalidateProposition?: (queued: PendingConfirmation, file: TopicIntentFile) => RevalidationResult;
+}
+export interface CreateResult {
+    status: 'outstanding' | 'queued' | 'dropped-duplicate' | 'dropped-queue-full';
+    pendingId?: string;
+    reason?: string;
+}
+export declare class PendingConfirmationManager {
+    private store;
+    private callbacks;
+    constructor(store: TopicIntentStore, callbacks?: PendingConfirmCallbacks);
+    /**
+     * Create a new pending confirmation. May go outstanding immediately,
+     * queue, or be dropped (duplicate / queue full).
+     */
+    create(opts: CreateOpts): CreateResult;
+    /**
+     * Interpret an incoming user-authored message as an answer to the current
+     * outstanding pending confirmation, if any.
+     *
+     * The caller is responsible for running the Tier-1 LLM verdict; this
+     * method takes the verdict and applies the state machine.
+     */
+    interpretAnswer(topicId: number, verdict: AnswerVerdict, sourceMessageId: string, now?: string): {
+        applied: boolean;
+        outcome: 'positive' | 'negative' | 'sharpen-retry' | 'abandoned' | 'no-outstanding';
+    };
+    /**
+     * Sweep for TTL expiry on the outstanding pending. Called by the caller
+     * after every substantive user turn (turn-based TTL) and periodically
+     * (clock-based TTL).
+     *
+     * Returns the dropped pending if one was swept.
+     */
+    sweepTtl(topicId: number, currentUserTurn: number, now?: string): PendingConfirmation | null;
+    /** Force-cancel the outstanding pending (e.g. on emergency stop / corrective input). */
+    cancelOutstanding(topicId: number, now?: string): PendingConfirmation | null;
+    /**
+     * Promote the next queued item to outstanding (if any).
+     * Runs revalidation at dequeue time. Stale items are dropped silently.
+     */
+    private dequeueNext;
+    private revalidate;
+}
+//# sourceMappingURL=TopicIntentPendingConfirm.d.ts.map

package/dist/core/TopicIntentPendingConfirm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TopicIntentPendingConfirm.d.ts","sourceRoot":"","sources":["../../src/core/TopicIntentPendingConfirm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EACL,gBAAgB,EAEhB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACrB,MAAM,kBAAkB,CAAC;AAO1B,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,UAAU,GAAG,WAAW,GAAG,gBAAgB,CAAC;AAErF,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,qBAAqB,GAAG,mBAAmB,GAAG,aAAa,GAAG,IAAI,CAAC;CAC7E;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,CAAC,MAAM,EAAE,mBAAmB,EAAE,IAAI,EAAE,eAAe,KAAK,kBAAkB,CAAC;CACpG;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,aAAa,GAAG,QAAQ,GAAG,mBAAmB,GAAG,oBAAoB,CAAC;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,0BAA0B;IAEnC,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,SAAS;gBADT,KAAK,EAAE,gBAAgB,EACvB,SAAS,GAAE,uBAA4B;IAGjD;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,YAAY;IAmDtC;;;;;;OAMG;IACH,eAAe,CACb,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,aAAa,EACtB,eAAe,EAAE,MAAM,EACvB,GAAG,CAAC,EAAE,MAAM,GACX;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,UAAU,GAAG,UAAU,GAAG,eAAe,GAAG,WAAW,GAAG,gBAAgB,CAAA;KAAE;IAsD5G;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI;IAqB5F,wFAAwF;IACxF,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI;IAa5E;;;OAGG;IACH,OAAO,CAAC,WAAW;IAkBnB,OAAO,CAAC,UAAU;CAiBnB"}