instar 1.2.37 → 1.2.39

package/dist/core/TopicIntent.d.ts

@@ -0,0 +1,162 @@
+/**
+ * TopicIntent — per-topic semantic state tracking via continuous confidence.
+ *
+ * Layer 1 of the Topic Intent Layer spec (v14 CLEAN, approved 2026-05-22).
+ * See docs/specs/topic-intent-layer.md.
+ *
+ * Tracks candidate facts and decisions extracted from conversation. Each
+ * EstablishedRef accumulates evidence over multi-turn exchange; confidence
+ * is computed on read as a deterministic projection over the append-only
+ * event log.
+ *
+ * Framework-agnostic: pure JSON persistence, pure math projection. Reachable
+ * from Claude Code and Codex sessions alike.
+ *
+ * Storage: {stateDir}/topic-intent/<topicId>.json
+ */
+export type RefKind = 'fact' | 'decision';
+export type RefStatus = 'live' | 'conflicted';
+export type EvidenceKind = 'extract-user' | 'extract-agent' | 'user-reref' | 'agent-reref' | 'user-affirm' | 'pending-confirm-positive' | 'pending-confirm-negative' | 'contradiction' | 'conflict-mark' | 'sharpen-retry-issued';
+export interface EvidenceEvent {
+    eventId: string;
+    refId: string;
+    kind: EvidenceKind;
+    sourceMessageId: string;
+    userAuthored: boolean;
+    at: string;
+    delta: number;
+    meta?: Record<string, unknown>;
+}
+export interface EstablishedRef {
+    refId: string;
+    arcId: string;
+    topicId: number;
+    kind: RefKind;
+    text: string;
+    confidence: number;
+    evidence: EvidenceEvent[];
+    lastReinforcedAt: string;
+    status: RefStatus;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface PendingConfirmation {
+    pendingId: string;
+    topicId: number;
+    arcId: string;
+    refId: string;
+    propositionText: string;
+    questionText: string;
+    sentAtTurn: number;
+    sentAtTime: string;
+    ttl: {
+        turns: number;
+        hours: number;
+    };
+    retries: number;
+    maxRetries: number;
+    status: 'pending' | 'answered' | 'expired' | 'abandoned';
+    queuedAtTime?: string;
+    dequeuedAtTime?: string;
+    answeredAtTime?: string;
+    answerVerdict?: 'positive' | 'negative' | 'ambiguous' | 'non-responsive';
+}
+export interface TopicIntentFile {
+    topicId: number;
+    refs: Record<string, EstablishedRef>;
+    pending: {
+        outstanding: PendingConfirmation | null;
+        queue: PendingConfirmation[];
+    };
+    telemetry: TelemetryCounters;
+    schemaVersion: 1;
+}
+export interface TelemetryCounters {
+    extraction_total: Record<string, number>;
+    evidence_event_total: Record<string, number>;
+    confidence_clamp_authority_total: number;
+    pending_confirm_created_total: number;
+    pending_confirm_queue_dropped_total: number;
+    pending_confirm_abandoned_total: number;
+    pending_confirm_expired_total: number;
+    pending_confirm_answered_total: Record<string, number>;
+}
+export declare const SIGNAL_DELTA: Record<EvidenceKind, number>;
+export declare const USER_AUTHORED_BY_DEFAULT: Record<EvidenceKind, boolean>;
+export interface ProjectionResult {
+    confidence: number;
+    tier: 'observation' | 'tentative' | 'authoritative';
+    authorityClampApplied: boolean;
+    decayApplied: number;
+    evidenceCount: number;
+    userAuthoredEpisodes: number;
+}
+/**
+ * Compute the confidence projection for a single EstablishedRef from its
+ * evidence array. Pure function — no I/O, no state, fully deterministic.
+ *
+ * Order of operations:
+ *   1. Per-message dedup by (refId, sourceMessageId): on collision, keep the
+ *      single largest applicable delta. (Multiple signals from the same user
+ *      message about the same refId count as ONE episode.)
+ *   2. Apply signal-specific caps (user-reref cumulative <= +0.30, etc.)
+ *   3. Apply affirmation caps (per-refId per 24h, per single user message).
+ *   4. Sum applicable deltas (with caps).
+ *   5. Apply time decay if (now - lastReinforcedAt) > 30 days.
+ *   6. Authority hard clamp: if would-be >= 0.7 and no qualifying
+ *      user-authored episode exists, clamp at 0.69.
+ *   7. Clamp final to [0.0, 1.0].
+ */
+export declare function projectConfidence(evidence: EvidenceEvent[], lastReinforcedAt: string, nowMs?: number): ProjectionResult;
+/**
+ * Which evidence kinds count as user-authored EPISODES that qualify for
+ * authority? (Distinct from the userAuthored boolean, which is broader.)
+ *
+ * Per spec: "user-authored episodes are the unit of evidence." Only
+ * specific kinds qualify — extraction from user, user re-reference,
+ * anchored affirmation, positive pending-confirm answer, contradiction
+ * (which is also a user-authored episode in the negative direction).
+ */
+export declare function qualifiesAsUserAuthoredEpisode(kind: EvidenceKind): boolean;
+export declare function buildEvent(refId: string, kind: EvidenceKind, sourceMessageId: string, opts?: {
+    at?: string;
+    userAuthored?: boolean;
+    delta?: number;
+    meta?: Record<string, unknown>;
+}): EvidenceEvent;
+export declare class TopicIntentStore {
+    private dir;
+    constructor(stateDir: string);
+    private filePath;
+    /** Load a topic's intent file, returning an empty skeleton if missing or corrupt. */
+    load(topicId: number): TopicIntentFile;
+    /** Persist the topic's intent file. */
+    save(file: TopicIntentFile): void;
+    /**
+     * Append an evidence event to a refId. Creates the ref if it doesn't exist.
+     * Updates lastReinforcedAt if the event has positive delta.
+     * Updates telemetry counters.
+     */
+    appendEvidence(topicId: number, refId: string, ev: EvidenceEvent, refInit?: Partial<EstablishedRef>): TopicIntentFile;
+    /** Get the live projection for a refId (recomputed from evidence). */
+    getProjection(topicId: number, refId: string, nowMs?: number): ProjectionResult | null;
+    /** Get all refs for a topic at current tier or above. */
+    getRefsAtOrAbove(topicId: number, minTier: 'observation' | 'tentative' | 'authoritative', nowMs?: number): Array<EstablishedRef & {
+        projection: ProjectionResult;
+    }>;
+    /** Full read of a topic's file (for diagnostics endpoint). */
+    read(topicId: number): TopicIntentFile;
+}
+export declare const TOPIC_INTENT_CONSTANTS: {
+    DECAY_HALF_LIFE_DAYS: number;
+    DECAY_GRACE_DAYS: number;
+    DECAY_LAMBDA: number;
+    AUTHORITY_THRESHOLD: number;
+    AUTHORITY_CLAMP: number;
+    TENTATIVE_THRESHOLD: number;
+    SIGNAL_CAPS: Partial<Record<EvidenceKind, number>>;
+    AFFIRM_PER_REF_PER_24H_LIMIT: number;
+    AFFIRM_PER_MESSAGE_REF_LIMIT: number;
+    MS_PER_DAY: number;
+};
+//# sourceMappingURL=TopicIntent.d.ts.map

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

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

package/dist/core/TopicIntent.js

@@ -0,0 +1,355 @@
+/**
+ * TopicIntent — per-topic semantic state tracking via continuous confidence.
+ *
+ * Layer 1 of the Topic Intent Layer spec (v14 CLEAN, approved 2026-05-22).
+ * See docs/specs/topic-intent-layer.md.
+ *
+ * Tracks candidate facts and decisions extracted from conversation. Each
+ * EstablishedRef accumulates evidence over multi-turn exchange; confidence
+ * is computed on read as a deterministic projection over the append-only
+ * event log.
+ *
+ * Framework-agnostic: pure JSON persistence, pure math projection. Reachable
+ * from Claude Code and Codex sessions alike.
+ *
+ * Storage: {stateDir}/topic-intent/<topicId>.json
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+// ── Constants from spec ──────────────────────────────────────────────────
+const DECAY_HALF_LIFE_DAYS = 180;
+const DECAY_GRACE_DAYS = 30;
+const DECAY_LAMBDA = Math.log(2) / DECAY_HALF_LIFE_DAYS;
+const AUTHORITY_THRESHOLD = 0.7;
+const AUTHORITY_CLAMP = 0.69;
+const TENTATIVE_THRESHOLD = 0.3;
+/** Signal-specific caps. Numeric = max cumulative contribution from that kind. */
+const SIGNAL_CAPS = {
+    'user-reref': 0.30,
+    'agent-reref': 0.05,
+    'extract-agent': 0.10, // initial agent-origin extraction capped at single occurrence value
+};
+/** Affirmation safety: per-refId per 24h cap. */
+const AFFIRM_PER_REF_PER_24H_LIMIT = 1;
+/** Per single user message, max number of distinct refIds that may receive affirmation bonus. */
+const AFFIRM_PER_MESSAGE_REF_LIMIT = 3;
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+// ── Default signal deltas (used by helpers; raw spec values) ─────────────
+export const SIGNAL_DELTA = {
+    'extract-user': 0.40,
+    'extract-agent': 0.10,
+    'user-reref': 0.10,
+    'agent-reref': 0.01,
+    'user-affirm': 0.30,
+    'pending-confirm-positive': 0.50,
+    'pending-confirm-negative': -0.70,
+    'contradiction': -0.60,
+    'conflict-mark': 0, // marker-only, no delta
+    'sharpen-retry-issued': 0, // bookkeeping, no delta
+};
+export const USER_AUTHORED_BY_DEFAULT = {
+    'extract-user': true,
+    'extract-agent': false,
+    'user-reref': true,
+    'agent-reref': false,
+    'user-affirm': true,
+    'pending-confirm-positive': true,
+    'pending-confirm-negative': true,
+    'contradiction': true,
+    'conflict-mark': false,
+    'sharpen-retry-issued': false,
+};
+/**
+ * Compute the confidence projection for a single EstablishedRef from its
+ * evidence array. Pure function — no I/O, no state, fully deterministic.
+ *
+ * Order of operations:
+ *   1. Per-message dedup by (refId, sourceMessageId): on collision, keep the
+ *      single largest applicable delta. (Multiple signals from the same user
+ *      message about the same refId count as ONE episode.)
+ *   2. Apply signal-specific caps (user-reref cumulative <= +0.30, etc.)
+ *   3. Apply affirmation caps (per-refId per 24h, per single user message).
+ *   4. Sum applicable deltas (with caps).
+ *   5. Apply time decay if (now - lastReinforcedAt) > 30 days.
+ *   6. Authority hard clamp: if would-be >= 0.7 and no qualifying
+ *      user-authored episode exists, clamp at 0.69.
+ *   7. Clamp final to [0.0, 1.0].
+ */
+export function projectConfidence(evidence, lastReinforcedAt, nowMs = Date.now()) {
+    // Step 1: per-message dedup — keep largest applicable delta per (refId, sourceMessageId)
+    const dedupedByMsg = new Map();
+    for (const ev of evidence) {
+        const key = `${ev.refId}::${ev.sourceMessageId}`;
+        const existing = dedupedByMsg.get(key);
+        if (!existing || Math.abs(ev.delta) > Math.abs(existing.delta)) {
+            dedupedByMsg.set(key, ev);
+        }
+    }
+    const deduped = Array.from(dedupedByMsg.values());
+    // Step 2-3: bucket by kind, apply caps
+    const bucketedByKind = new Map();
+    for (const ev of deduped) {
+        if (!bucketedByKind.has(ev.kind))
+            bucketedByKind.set(ev.kind, []);
+        bucketedByKind.get(ev.kind).push(ev);
+    }
+    let runningSum = 0;
+    let userAuthoredEpisodes = 0;
+    for (const [kind, events] of bucketedByKind) {
+        const cap = SIGNAL_CAPS[kind];
+        if (cap !== undefined && events.length > 0 && events[0].delta > 0) {
+            // Positive-delta capped signal: sum and clamp at cap
+            const raw = events.reduce((s, e) => s + e.delta, 0);
+            runningSum += Math.min(raw, cap);
+        }
+        else if (kind === 'user-affirm') {
+            // Affirm safety: enforce per-refId per 24h limit
+            // and per single source-message limit of distinct refIds (handled at INSERT time,
+            // but defensive in projection too)
+            const affirmsByDay = new Map();
+            for (const ev of events) {
+                const dayKey = ev.at.slice(0, 10); // YYYY-MM-DD coarse bucket
+                if (!affirmsByDay.has(dayKey))
+                    affirmsByDay.set(dayKey, []);
+                affirmsByDay.get(dayKey).push(ev);
+            }
+            let appliedAffirms = 0;
+            for (const dayEvents of affirmsByDay.values()) {
+                // Sort by time and take only the first AFFIRM_PER_REF_PER_24H_LIMIT
+                dayEvents.sort((a, b) => a.at.localeCompare(b.at));
+                const allowed = dayEvents.slice(0, AFFIRM_PER_REF_PER_24H_LIMIT);
+                appliedAffirms += allowed.reduce((s, e) => s + e.delta, 0);
+            }
+            runningSum += appliedAffirms;
+        }
+        else {
+            // Uncapped signal: just sum
+            runningSum += events.reduce((s, e) => s + e.delta, 0);
+        }
+        // Count user-authored episodes (those that qualify for authority)
+        for (const ev of events) {
+            if (ev.userAuthored && qualifiesAsUserAuthoredEpisode(ev.kind)) {
+                userAuthoredEpisodes++;
+            }
+        }
+    }
+    // Step 5: time decay
+    let preDecaySum = Math.max(0, Math.min(1, runningSum));
+    const daysSince = Math.max(0, (nowMs - new Date(lastReinforcedAt).getTime()) / MS_PER_DAY);
+    let decayApplied = 0;
+    if (daysSince > DECAY_GRACE_DAYS) {
+        const decayDays = daysSince - DECAY_GRACE_DAYS;
+        const decayed = preDecaySum * Math.exp(-DECAY_LAMBDA * decayDays);
+        decayApplied = preDecaySum - decayed;
+        preDecaySum = decayed;
+    }
+    // Step 6: authority hard clamp
+    let authorityClampApplied = false;
+    let finalConf = preDecaySum;
+    if (finalConf >= AUTHORITY_THRESHOLD && userAuthoredEpisodes === 0) {
+        finalConf = AUTHORITY_CLAMP;
+        authorityClampApplied = true;
+    }
+    // Step 7: final clamp
+    finalConf = Math.max(0, Math.min(1, finalConf));
+    // Tier classification (emergent)
+    let tier;
+    if (finalConf < TENTATIVE_THRESHOLD)
+        tier = 'observation';
+    else if (finalConf < AUTHORITY_THRESHOLD)
+        tier = 'tentative';
+    else
+        tier = 'authoritative';
+    return {
+        confidence: finalConf,
+        tier,
+        authorityClampApplied,
+        decayApplied,
+        evidenceCount: deduped.length,
+        userAuthoredEpisodes,
+    };
+}
+/**
+ * Which evidence kinds count as user-authored EPISODES that qualify for
+ * authority? (Distinct from the userAuthored boolean, which is broader.)
+ *
+ * Per spec: "user-authored episodes are the unit of evidence." Only
+ * specific kinds qualify — extraction from user, user re-reference,
+ * anchored affirmation, positive pending-confirm answer, contradiction
+ * (which is also a user-authored episode in the negative direction).
+ */
+export function qualifiesAsUserAuthoredEpisode(kind) {
+    return (kind === 'extract-user' ||
+        kind === 'user-reref' ||
+        kind === 'user-affirm' ||
+        kind === 'pending-confirm-positive' ||
+        kind === 'pending-confirm-negative' ||
+        kind === 'contradiction');
+}
+// ── Helpers for building events ──────────────────────────────────────────
+export function buildEvent(refId, kind, sourceMessageId, opts) {
+    return {
+        eventId: randomUUID(),
+        refId,
+        kind,
+        sourceMessageId,
+        userAuthored: opts?.userAuthored ?? USER_AUTHORED_BY_DEFAULT[kind],
+        at: opts?.at ?? new Date().toISOString(),
+        delta: opts?.delta ?? SIGNAL_DELTA[kind],
+        meta: opts?.meta,
+    };
+}
+// ── Store (file-based, framework-agnostic) ───────────────────────────────
+export class TopicIntentStore {
+    dir;
+    constructor(stateDir) {
+        this.dir = path.join(stateDir, 'topic-intent');
+        try {
+            fs.mkdirSync(this.dir, { recursive: true });
+        }
+        catch (err) {
+            console.error(`[TopicIntentStore] Failed to create dir ${this.dir}: ${err}`);
+        }
+    }
+    filePath(topicId) {
+        return path.join(this.dir, `${topicId}.json`);
+    }
+    /** Load a topic's intent file, returning an empty skeleton if missing or corrupt. */
+    load(topicId) {
+        const fp = this.filePath(topicId);
+        try {
+            if (fs.existsSync(fp)) {
+                const parsed = JSON.parse(fs.readFileSync(fp, 'utf-8'));
+                // Ensure required fields exist (defensive for older files)
+                if (!parsed.refs)
+                    parsed.refs = {};
+                if (!parsed.pending)
+                    parsed.pending = { outstanding: null, queue: [] };
+                if (!parsed.telemetry)
+                    parsed.telemetry = emptyTelemetry();
+                if (parsed.schemaVersion === undefined)
+                    parsed.schemaVersion = 1;
+                return parsed;
+            }
+        }
+        catch (err) {
+            console.error(`[TopicIntentStore] Corrupt file ${fp}, starting fresh: ${err}`);
+        }
+        return emptyFile(topicId);
+    }
+    /** Persist the topic's intent file. */
+    save(file) {
+        const fp = this.filePath(file.topicId);
+        try {
+            fs.writeFileSync(fp, JSON.stringify(file, null, 2));
+        }
+        catch (err) {
+            console.error(`[TopicIntentStore] Failed to save ${fp}: ${err}`);
+        }
+    }
+    /**
+     * Append an evidence event to a refId. Creates the ref if it doesn't exist.
+     * Updates lastReinforcedAt if the event has positive delta.
+     * Updates telemetry counters.
+     */
+    appendEvidence(topicId, refId, ev, refInit) {
+        const file = this.load(topicId);
+        let ref = file.refs[refId];
+        if (!ref) {
+            ref = {
+                refId,
+                arcId: refInit?.arcId ?? `arc-${topicId}`,
+                topicId,
+                kind: refInit?.kind ?? 'fact',
+                text: refInit?.text ?? '',
+                confidence: 0,
+                evidence: [],
+                lastReinforcedAt: ev.at,
+                status: 'live',
+                createdAt: ev.at,
+                updatedAt: ev.at,
+            };
+            file.refs[refId] = ref;
+        }
+        ref.evidence.push(ev);
+        if (ev.delta > 0) {
+            ref.lastReinforcedAt = ev.at;
+        }
+        ref.updatedAt = ev.at;
+        // Recompute confidence + tier snapshot for visibility (projection runs on read regardless)
+        const proj = projectConfidence(ref.evidence, ref.lastReinforcedAt);
+        ref.confidence = proj.confidence;
+        // Telemetry
+        const extractKey = `${ev.kind}:${ev.userAuthored}`;
+        file.telemetry.extraction_total[extractKey] = (file.telemetry.extraction_total[extractKey] ?? 0) + 1;
+        file.telemetry.evidence_event_total[ev.kind] = (file.telemetry.evidence_event_total[ev.kind] ?? 0) + 1;
+        if (proj.authorityClampApplied) {
+            file.telemetry.confidence_clamp_authority_total++;
+        }
+        this.save(file);
+        return file;
+    }
+    /** Get the live projection for a refId (recomputed from evidence). */
+    getProjection(topicId, refId, nowMs) {
+        const file = this.load(topicId);
+        const ref = file.refs[refId];
+        if (!ref)
+            return null;
+        return projectConfidence(ref.evidence, ref.lastReinforcedAt, nowMs);
+    }
+    /** Get all refs for a topic at current tier or above. */
+    getRefsAtOrAbove(topicId, minTier, nowMs) {
+        const file = this.load(topicId);
+        const tierOrder = { observation: 0, tentative: 1, authoritative: 2 };
+        const minRank = tierOrder[minTier];
+        const out = [];
+        for (const ref of Object.values(file.refs)) {
+            const proj = projectConfidence(ref.evidence, ref.lastReinforcedAt, nowMs);
+            if (tierOrder[proj.tier] >= minRank) {
+                out.push({ ...ref, projection: proj });
+            }
+        }
+        return out;
+    }
+    /** Full read of a topic's file (for diagnostics endpoint). */
+    read(topicId) {
+        return this.load(topicId);
+    }
+}
+// ── Helpers for empty state ──────────────────────────────────────────────
+function emptyTelemetry() {
+    return {
+        extraction_total: {},
+        evidence_event_total: {},
+        confidence_clamp_authority_total: 0,
+        pending_confirm_created_total: 0,
+        pending_confirm_queue_dropped_total: 0,
+        pending_confirm_abandoned_total: 0,
+        pending_confirm_expired_total: 0,
+        pending_confirm_answered_total: {},
+    };
+}
+function emptyFile(topicId) {
+    return {
+        topicId,
+        refs: {},
+        pending: { outstanding: null, queue: [] },
+        telemetry: emptyTelemetry(),
+        schemaVersion: 1,
+    };
+}
+// ── Re-exports for convenience ───────────────────────────────────────────
+export const TOPIC_INTENT_CONSTANTS = {
+    DECAY_HALF_LIFE_DAYS,
+    DECAY_GRACE_DAYS,
+    DECAY_LAMBDA,
+    AUTHORITY_THRESHOLD,
+    AUTHORITY_CLAMP,
+    TENTATIVE_THRESHOLD,
+    SIGNAL_CAPS,
+    AFFIRM_PER_REF_PER_24H_LIMIT,
+    AFFIRM_PER_MESSAGE_REF_LIMIT,
+    MS_PER_DAY,
+};
+//# sourceMappingURL=TopicIntent.js.map

package/dist/core/TopicIntent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TopicIntent.js","sourceRoot":"","sources":["../../src/core/TopicIntent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAsFzC,4EAA4E;AAE5E,MAAM,oBAAoB,GAAG,GAAG,CAAC;AACjC,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAC5B,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,oBAAoB,CAAC;AAExD,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAChC,MAAM,eAAe,GAAG,IAAI,CAAC;AAC7B,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAEhC,kFAAkF;AAClF,MAAM,WAAW,GAA0C;IACzD,YAAY,EAAE,IAAI;IAClB,aAAa,EAAE,IAAI;IACnB,eAAe,EAAE,IAAI,EAAE,oEAAoE;CAC5F,CAAC;AAEF,iDAAiD;AACjD,MAAM,4BAA4B,GAAG,CAAC,CAAC;AACvC,iGAAiG;AACjG,MAAM,4BAA4B,GAAG,CAAC,CAAC;AAEvC,MAAM,UAAU,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAEvC,4EAA4E;AAE5E,MAAM,CAAC,MAAM,YAAY,GAAiC;IACxD,cAAc,EAAE,IAAI;IACpB,eAAe,EAAE,IAAI;IACrB,YAAY,EAAE,IAAI;IAClB,aAAa,EAAE,IAAI;IACnB,aAAa,EAAE,IAAI;IACnB,0BAA0B,EAAE,IAAI;IAChC,0BAA0B,EAAE,CAAC,IAAI;IACjC,eAAe,EAAE,CAAC,IAAI;IACtB,eAAe,EAAE,CAAC,EAAS,wBAAwB;IACnD,sBAAsB,EAAE,CAAC,EAAE,wBAAwB;CACpD,CAAC;AAEF,MAAM,CAAC,MAAM,wBAAwB,GAAkC;IACrE,cAAc,EAAE,IAAI;IACpB,eAAe,EAAE,KAAK;IACtB,YAAY,EAAE,IAAI;IAClB,aAAa,EAAE,KAAK;IACpB,aAAa,EAAE,IAAI;IACnB,0BAA0B,EAAE,IAAI;IAChC,0BAA0B,EAAE,IAAI;IAChC,eAAe,EAAE,IAAI;IACrB,eAAe,EAAE,KAAK;IACtB,sBAAsB,EAAE,KAAK;CAC9B,CAAC;AAaF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAyB,EACzB,gBAAwB,EACxB,QAAgB,IAAI,CAAC,GAAG,EAAE;IAE1B,yFAAyF;IACzF,MAAM,YAAY,GAAG,IAAI,GAAG,EAAyB,CAAC;IACtD,KAAK,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC;QAC1B,MAAM,GAAG,GAAG,GAAG,EAAE,CAAC,KAAK,KAAK,EAAE,CAAC,eAAe,EAAE,CAAC;QACjD,MAAM,QAAQ,GAAG,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC/D,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;IACD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC;IAElD,uCAAuC;IACvC,MAAM,cAAc,GAAG,IAAI,GAAG,EAAiC,CAAC;IAChE,KAAK,MAAM,EAAE,IAAI,OAAO,EAAE,CAAC;QACzB,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC;YAAE,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAClE,cAAc,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACxC,CAAC;IAED,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,oBAAoB,GAAG,CAAC,CAAC;IAE7B,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,cAAc,EAAE,CAAC;QAC5C,MAAM,GAAG,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;QAC9B,IAAI,GAAG,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC;YAClE,qDAAqD;YACrD,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YACpD,UAAU,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACnC,CAAC;aAAM,IAAI,IAAI,KAAK,aAAa,EAAE,CAAC;YAClC,iDAAiD;YACjD,kFAAkF;YAClF,mCAAmC;YACnC,MAAM,YAAY,GAAG,IAAI,GAAG,EAA2B,CAAC;YACxD,KAAK,MAAM,EAAE,IAAI,MAAM,EAAE,CAAC;gBACxB,MAAM,MAAM,GAAG,EAAE,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,2BAA2B;gBAC9D,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC;oBAAE,YAAY,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;gBAC5D,YAAY,CAAC,GAAG,CAAC,MAAM,CAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACrC,CAAC;YACD,IAAI,cAAc,GAAG,CAAC,CAAC;YACvB,KAAK,MAAM,SAAS,IAAI,YAAY,CAAC,MAAM,EAAE,EAAE,CAAC;gBAC9C,oEAAoE;gBACpE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;gBACnD,MAAM,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,4BAA4B,CAAC,CAAC;gBACjE,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YAC7D,CAAC;YACD,UAAU,IAAI,cAAc,CAAC;QAC/B,CAAC;aAAM,CAAC;YACN,4BAA4B;YAC5B,UAAU,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QACxD,CAAC;QAED,kEAAkE;QAClE,KAAK,MAAM,EAAE,IAAI,MAAM,EAAE,CAAC;YACxB,IAAI,EAAE,CAAC,YAAY,IAAI,8BAA8B,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC/D,oBAAoB,EAAE,CAAC;YACzB,CAAC;QACH,CAAC;IACH,CAAC;IAED,qBAAqB;IACrB,IAAI,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC;IACvD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,GAAG,IAAI,IAAI,CAAC,gBAAgB,CAAC,CAAC,OAAO,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC;IAC3F,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,IAAI,SAAS,GAAG,gBAAgB,EAAE,CAAC;QACjC,MAAM,SAAS,GAAG,SAAS,GAAG,gBAAgB,CAAC;QAC/C,MAAM,OAAO,GAAG,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,YAAY,GAAG,SAAS,CAAC,CAAC;QAClE,YAAY,GAAG,WAAW,GAAG,OAAO,CAAC;QACrC,WAAW,GAAG,OAAO,CAAC;IACxB,CAAC;IAED,+BAA+B;IAC/B,IAAI,qBAAqB,GAAG,KAAK,CAAC;IAClC,IAAI,SAAS,GAAG,WAAW,CAAC;IAC5B,IAAI,SAAS,IAAI,mBAAmB,IAAI,oBAAoB,KAAK,CAAC,EAAE,CAAC;QACnE,SAAS,GAAG,eAAe,CAAC;QAC5B,qBAAqB,GAAG,IAAI,CAAC;IAC/B,CAAC;IAED,sBAAsB;IACtB,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC;IAEhD,iCAAiC;IACjC,IAAI,IAAmD,CAAC;IACxD,IAAI,SAAS,GAAG,mBAAmB;QAAE,IAAI,GAAG,aAAa,CAAC;SACrD,IAAI,SAAS,GAAG,mBAAmB;QAAE,IAAI,GAAG,WAAW,CAAC;;QACxD,IAAI,GAAG,eAAe,CAAC;IAE5B,OAAO;QACL,UAAU,EAAE,SAAS;QACrB,IAAI;QACJ,qBAAqB;QACrB,YAAY;QACZ,aAAa,EAAE,OAAO,CAAC,MAAM;QAC7B,oBAAoB;KACrB,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,8BAA8B,CAAC,IAAkB;IAC/D,OAAO,CACL,IAAI,KAAK,cAAc;QACvB,IAAI,KAAK,YAAY;QACrB,IAAI,KAAK,aAAa;QACtB,IAAI,KAAK,0BAA0B;QACnC,IAAI,KAAK,0BAA0B;QACnC,IAAI,KAAK,eAAe,CACzB,CAAC;AACJ,CAAC;AAED,4EAA4E;AAE5E,MAAM,UAAU,UAAU,CACxB,KAAa,EACb,IAAkB,EAClB,eAAuB,EACvB,IAA8F;IAE9F,OAAO;QACL,OAAO,EAAE,UAAU,EAAE;QACrB,KAAK;QACL,IAAI;QACJ,eAAe;QACf,YAAY,EAAE,IAAI,EAAE,YAAY,IAAI,wBAAwB,CAAC,IAAI,CAAC;QAClE,EAAE,EAAE,IAAI,EAAE,EAAE,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACxC,KAAK,EAAE,IAAI,EAAE,KAAK,IAAI,YAAY,CAAC,IAAI,CAAC;QACxC,IAAI,EAAE,IAAI,EAAE,IAAI;KACjB,CAAC;AACJ,CAAC;AAED,4EAA4E;AAE5E,MAAM,OAAO,gBAAgB;IACnB,GAAG,CAAS;IAEpB,YAAY,QAAgB;QAC1B,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;QAC/C,IAAI,CAAC;YACH,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,2CAA2C,IAAI,CAAC,GAAG,KAAK,GAAG,EAAE,CAAC,CAAC;QAC/E,CAAC;IACH,CAAC;IAEO,QAAQ,CAAC,OAAe;QAC9B,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,OAAO,CAAC,CAAC;IAChD,CAAC;IAED,qFAAqF;IACrF,IAAI,CAAC,OAAe;QAClB,MAAM,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAClC,IAAI,CAAC;YACH,IAAI,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC,EAAE,CAAC;gBACtB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,EAAE,EAAE,OAAO,CAAC,CAAoB,CAAC;gBAC3E,2DAA2D;gBAC3D,IAAI,CAAC,MAAM,CAAC,IAAI;oBAAE,MAAM,CAAC,IAAI,GAAG,EAAE,CAAC;gBACnC,IAAI,CAAC,MAAM,CAAC,OAAO;oBAAE,MAAM,CAAC,OAAO,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;gBACvE,IAAI,CAAC,MAAM,CAAC,SAAS;oBAAE,MAAM,CAAC,SAAS,GAAG,cAAc,EAAE,CAAC;gBAC3D,IAAI,MAAM,CAAC,aAAa,KAAK,SAAS;oBAAE,MAAM,CAAC,aAAa,GAAG,CAAC,CAAC;gBACjE,OAAO,MAAM,CAAC;YAChB,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,mCAAmC,EAAE,qBAAqB,GAAG,EAAE,CAAC,CAAC;QACjF,CAAC;QACD,OAAO,SAAS,CAAC,OAAO,CAAC,CAAC;IAC5B,CAAC;IAED,uCAAuC;IACvC,IAAI,CAAC,IAAqB;QACxB,MAAM,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACvC,IAAI,CAAC;YACH,EAAE,CAAC,aAAa,CAAC,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QACtD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,KAAK,CAAC,qCAAqC,EAAE,KAAK,GAAG,EAAE,CAAC,CAAC;QACnE,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,cAAc,CAAC,OAAe,EAAE,KAAa,EAAE,EAAiB,EAAE,OAAiC;QACjG,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAChC,IAAI,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC3B,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,GAAG,GAAG;gBACJ,KAAK;gBACL,KAAK,EAAE,OAAO,EAAE,KAAK,IAAI,OAAO,OAAO,EAAE;gBACzC,OAAO;gBACP,IAAI,EAAE,OAAO,EAAE,IAAI,IAAI,MAAM;gBAC7B,IAAI,EAAE,OAAO,EAAE,IAAI,IAAI,EAAE;gBACzB,UAAU,EAAE,CAAC;gBACb,QAAQ,EAAE,EAAE;gBACZ,gBAAgB,EAAE,EAAE,CAAC,EAAE;gBACvB,MAAM,EAAE,MAAM;gBACd,SAAS,EAAE,EAAE,CAAC,EAAE;gBAChB,SAAS,EAAE,EAAE,CAAC,EAAE;aACjB,CAAC;YACF,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC;QACzB,CAAC;QAED,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACtB,IAAI,EAAE,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC;YACjB,GAAG,CAAC,gBAAgB,GAAG,EAAE,CAAC,EAAE,CAAC;QAC/B,CAAC;QACD,GAAG,CAAC,SAAS,GAAG,EAAE,CAAC,EAAE,CAAC;QAEtB,2FAA2F;QAC3F,MAAM,IAAI,GAAG,iBAAiB,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,gBAAgB,CAAC,CAAC;QACnE,GAAG,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QAEjC,YAAY;QACZ,MAAM,UAAU,GAAG,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,YAAY,EAAE,CAAC;QACnD,IAAI,CAAC,SAAS,CAAC,gBAAgB,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,gBAAgB,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QACrG,IAAI,CAAC,SAAS,CAAC,oBAAoB,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,oBAAoB,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QACvG,IAAI,IAAI,CAAC,qBAAqB,EAAE,CAAC;YAC/B,IAAI,CAAC,SAAS,CAAC,gCAAgC,EAAE,CAAC;QACpD,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,sEAAsE;IACtE,aAAa,CAAC,OAAe,EAAE,KAAa,EAAE,KAAc;QAC1D,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAChC,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC7B,IAAI,CAAC,GAAG;YAAE,OAAO,IAAI,CAAC;QACtB,OAAO,iBAAiB,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAC;IACtE,CAAC;IAED,yDAAyD;IACzD,gBAAgB,CAAC,OAAe,EAAE,OAAsD,EAAE,KAAc;QACtG,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAChC,MAAM,SAAS,GAAG,EAAE,WAAW,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,CAAC;QACrE,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;QACnC,MAAM,GAAG,GAA6D,EAAE,CAAC;QACzE,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3C,MAAM,IAAI,GAAG,iBAAiB,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAC;YAC1E,IAAI,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,OAAO,EAAE,CAAC;gBACpC,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;YACzC,CAAC;QACH,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,8DAA8D;IAC9D,IAAI,CAAC,OAAe;QAClB,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC5B,CAAC;CACF;AAED,4EAA4E;AAE5E,SAAS,cAAc;IACrB,OAAO;QACL,gBAAgB,EAAE,EAAE;QACpB,oBAAoB,EAAE,EAAE;QACxB,gCAAgC,EAAE,CAAC;QACnC,6BAA6B,EAAE,CAAC;QAChC,mCAAmC,EAAE,CAAC;QACtC,+BAA+B,EAAE,CAAC;QAClC,6BAA6B,EAAE,CAAC;QAChC,8BAA8B,EAAE,EAAE;KACnC,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAAC,OAAe;IAChC,OAAO;QACL,OAAO;QACP,IAAI,EAAE,EAAE;QACR,OAAO,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE;QACzC,SAAS,EAAE,cAAc,EAAE;QAC3B,aAAa,EAAE,CAAC;KACjB,CAAC;AACJ,CAAC;AAED,4EAA4E;AAE5E,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,oBAAoB;IACpB,gBAAgB;IAChB,YAAY;IACZ,mBAAmB;IACnB,eAAe;IACf,mBAAmB;IACnB,WAAW;IACX,4BAA4B;IAC5B,4BAA4B;IAC5B,UAAU;CACX,CAAC"}

package/dist/core/TopicIntentArcCheck.d.ts

@@ -0,0 +1,101 @@
+/**
+ * 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.
+ */
+import { TopicIntentStore, type EstablishedRef, type ProjectionResult } from './TopicIntent.js';
+export interface ArcCheckInput {
+    topicId: number;
+    draftText: string;
+    /** Optional: which user turn this draft is in reply to (for record-keeping). */
+    forUserTurn?: number;
+}
+export type ArcCheckVerdict = {
+    fire: false;
+} | {
+    fire: true;
+    kind: 'acting-on-tentative' | 'contradicts-settled';
+    refId: string;
+    refText: string;
+    currentTier: 'tentative' | 'authoritative';
+    currentConfidence: number;
+    reason: string;
+    /** Suggested rewrite hint the agent can include in its redraft. */
+    suggestedRewriteHint: string;
+};
+/**
+ * The injectable LLM step. Receives the draft + tracked refs and returns
+ * a structured classification. Production wires this to a Haiku-class
+ * call via LlmQueue; tests stub it.
+ *
+ * Return value shape: which refs (if any) the draft engages with, and
+ * whether the engagement is "act on it" or "contradict it."
+ */
+export interface ArcCheckClassification {
+    /** refIds the draft appears to ACT ON (decisions baked in, facts assumed). */
+    actsOn: string[];
+    /** refIds the draft appears to CONTRADICT. */
+    contradicts: string[];
+}
+export type ArcCheckClassifyFn = (draftText: string, refs: Array<EstablishedRef & {
+    projection: ProjectionResult;
+}>) => Promise<ArcCheckClassification>;
+export declare class ArcCheck {
+    private store;
+    private classifyFn;
+    constructor(store: TopicIntentStore, classifyFn: ArcCheckClassifyFn);
+    /**
+     * 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.
+     */
+    check(input: ArcCheckInput): Promise<ArcCheckVerdict>;
+}
+/**
+ * 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 declare function buildArcCheckPrompt(draftText: string, refs: Array<EstablishedRef & {
+    projection: ProjectionResult;
+}>): {
+    systemPrompt: string;
+    userPrompt: string;
+};
+/**
+ * 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 declare function parseArcCheckResponse(raw: string): ArcCheckClassification;
+//# sourceMappingURL=TopicIntentArcCheck.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TopicIntentArcCheck.d.ts","sourceRoot":"","sources":["../../src/core/TopicIntentArcCheck.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EACL,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACtB,MAAM,kBAAkB,CAAC;AAE1B,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,GACf;IACE,IAAI,EAAE,IAAI,CAAC;IACX,IAAI,EAAE,qBAAqB,GAAG,qBAAqB,CAAC;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,WAAW,GAAG,eAAe,CAAC;IAC3C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,oBAAoB,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEN;;;;;;;GAOG;AACH,MAAM,WAAW,sBAAsB;IACrC,8EAA8E;IAC9E,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,MAAM,kBAAkB,GAAG,CAC/B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,KAAK,CAAC,cAAc,GAAG;IAAE,UAAU,EAAE,gBAAgB,CAAA;CAAE,CAAC,KAC3D,OAAO,CAAC,sBAAsB,CAAC,CAAC;AAErC,qBAAa,QAAQ;IAEjB,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,UAAU;gBADV,KAAK,EAAE,gBAAgB,EACvB,UAAU,EAAE,kBAAkB;IAGxC;;;;;;;;;;;OAWG;IACG,KAAK,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,eAAe,CAAC;CAgD5D;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,KAAK,CAAC,cAAc,GAAG;IAAE,UAAU,EAAE,gBAAgB,CAAA;CAAE,CAAC,GAC7D;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CA2B9C;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,sBAAsB,CAiBzE"}