@buildaharness/aielia 0.3.0

package/dist/contradiction-checker.d.ts

@@ -0,0 +1,27 @@
+import { ILLMClient, TokenUsage } from '@buildaharness/runtime';
+import { ExternalContradictionInput } from '@buildaharness/harness';
+export interface BeliefCandidate {
+    id: string;
+    statement: string;
+}
+/** Zero-LLM-call gate: true when a belief statement reads like a structured/technical (build, test, service, file) claim rather than a natural-language personal fact. */
+export declare function looksLikeCodingFact(statement: string): boolean;
+/**
+ * `AUDIT_SEMANTIC_CONTRADICTION` gate — feature-value audit (Phase A4 of
+ * plans/feature_audit_automation_plan.html). Default **ON**: the semantic contradiction-checker
+ * LLM call ships enabled, so an unset / empty / truthy value keeps today's behaviour. Set to a
+ * falsy value (`0` / `false` / `off` / `no` / `disabled`) to skip the LLM call entirely and fall
+ * back to the harness's always-on lexical / negation-pair check only. Read at exactly one call
+ * site — `harness-bridge.ts`, where the `contradictionChecker` host hook is wired.
+ */
+export declare function semanticContradictionEnabled(env?: Record<string, string | undefined>): boolean;
+/** A newBelief restating/reinforcing an uncertainFacts or rejectedFacts entry in different words — see checkForContradictions' doc comment. Caller resolves which pool `existingId` came from by id membership (both ids are always from this call's own known-id set, filtered below). */
+export interface Corroboration {
+    existingId: string;
+    newId: string;
+}
+export interface ContradictionCheckResult {
+    contradictions: ExternalContradictionInput[];
+    corroborations: Corroboration[];
+}
+export declare function checkForContradictions(newBeliefs: BeliefCandidate[], existingBeliefs: BeliefCandidate[], llmClient: ILLMClient, model?: string, onUsage?: (usage: TokenUsage) => void, uncertainFacts?: BeliefCandidate[], rejectedFacts?: BeliefCandidate[]): Promise<ContradictionCheckResult>;

package/dist/debug-log.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Full conversation content, for a caller that wants live visibility while debugging — a
+ * user's message, the assistant's final reply/reason, or one real tool call's name/input/
+ * result. Not privacy-scrubbed and not truncated to name-only the way TraceEvent is; a
+ * caller opts into this explicitly (see PersonalAssistantOptions.onDebugLog) knowing it
+ * carries real content, not just metadata.
+ *
+ * Split into its own file so both assistant.ts (user_message/assistant_reply kinds, emitted from
+ * `turn()`) and agent-loop.ts (tool_call kind, emitted from the ReAct loop) can depend on it
+ * without either owning the other.
+ */
+export interface DebugLogEntry {
+    kind: 'user_message' | 'assistant_reply' | 'tool_call';
+    sessionId: string;
+    content: string;
+}

package/dist/decomposition-classifier.d.ts

@@ -0,0 +1,38 @@
+import { ILLMClient, TokenUsage } from '@buildaharness/runtime';
+/**
+ * True if `message` looks like an enumeration of multiple distinct items — the strong signals
+ * above (sequencing markers, comma/semicolon/numbered lists), deliberately WITHOUT a word-count
+ * fallback: a single long reminder isn't multiple reminders just because it's wordy. Used by
+ * risk-classifier.ts to gate bulk reminder creation on confirmation instead of letting the model
+ * silently create several reminders in one turn.
+ */
+export declare function looksLikeEnumeratedItems(message: string): boolean;
+export interface DecomposedTaskSpec {
+    id: string;
+    description: string;
+    depends_on: string[];
+    /**
+     * Per-task risk (LOW/MEDIUM/HIGH), not the turn-level risk broadcast across every task —
+     * see Phase 4.2 of the harness layer activation plan: a step like "delete the draft file"
+     * shouldn't inherit an unrelated sibling step's risk profile just because they were rendered
+     * from the same turn. classifyTurnIntent's LLM call judges this directly for ad hoc
+     * decompositions; buildPlanFromTemplate (plan-builder.ts) attaches it from the template's own
+     * already-curated per-task risk_level instead of asking the LLM to re-derive it.
+     */
+    riskLevel: 'LOW' | 'MEDIUM' | 'HIGH';
+}
+/**
+ * Reframes a single-task turn's description to lead with its subject — the same phrasing
+ * classifyTurnIntent's own decomposedTasks and buildPlanFromTemplate (plan-builder.ts) already
+ * produce for their own tasks, applied here for the much more common case where a turn goes
+ * through neither: an ad hoc single-task turn whose description otherwise stays the raw verbatim userMessage (see
+ * assistant.ts's initialTasks fallback). Without this, only decomposed/planned tasks got
+ * subject-first descriptions, so the "Completed: <description>" belief statementsOpposed/
+ * isNegation compare against was structured for some tasks and not others. Deliberately not
+ * called unconditionally — the caller gates this behind looksLikeCodingFact AND riskLevel !==
+ * 'LOW' (the actual precondition for a single task's description to ever reach that belief; see
+ * assistant.ts's call site for why looksLikeCodingFact alone isn't a safe gate for a new call).
+ * Falls back to null (caller keeps the original message) on any parse failure or LLM error,
+ * matching this codebase's other LLM-backed classifiers.
+ */
+export declare function reframeTaskDescriptionWithLLM(message: string, llmClient: ILLMClient, model?: string, onUsage?: (usage: TokenUsage) => void): Promise<string | null>;

package/dist/doctor-checks.d.ts

@@ -0,0 +1,8 @@
+import { FsBackend } from '@buildaharness/runtime';
+import { DoctorCheck } from './cli-session.js';
+/** GET <proxyUrl>/health, expecting {status:'ok'} (see packages/proxy/src/index.ts) — hard-timed so a dead proxy can't hang /doctor. */
+export declare function checkProxyHealth(proxyUrl: string): Promise<DoctorCheck>;
+/** Spawns `<claudePath> --version`, same path resolution ClaudeCliLLMClient uses — hard-timed so a hung/missing binary can't hang /doctor. */
+export declare function checkClaudeCli(claudePath: string): Promise<DoctorCheck>;
+export declare function checkWorkspaceRoot(workspaceRoot: string): Promise<DoctorCheck>;
+export declare function checkDataDirWritable(backend: FsBackend, dataDir: string): Promise<DoctorCheck>;

package/dist/email-smtp.d.ts

@@ -0,0 +1,19 @@
+import { SendEmail } from './email.js';
+export interface SmtpSenderOptions {
+    host: string;
+    port: number;
+    /** true for implicit TLS (port 465); false for STARTTLS (587) or plain (25). */
+    secure?: boolean;
+    auth?: {
+        user: string;
+        pass: string;
+    };
+    /** Default sender address, used when a message omits `from`. */
+    from: string;
+}
+/**
+ * SMTP transport via nodemailer. All connection details come from config
+ * (ASSISTANT_EMAIL_SMTP_* / config.json), never from the model. `nodemailer` is a dependency of
+ * this package but imported dynamically so it is only loaded when SMTP is actually configured.
+ */
+export declare function createSmtpSender(options: SmtpSenderOptions): SendEmail;

package/dist/email.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Email as a real, approval-gated "effect" tool (adoption plan F2, path (a)).
+ *
+ * The assistant's flagship demo — "send an email to my boss saying I quit" → the risk gate
+ * stops before anything leaves the machine — only means something if there is an actual send
+ * behind the gate. `send_email` is that action, staged exactly like `write_file`/`run_shell_command`
+ * (see file-tools.ts's stagePendingAction): the model can only ever *propose* a message, never
+ * deliver one, and `applyPendingAction` calls the injected `SendEmail` transport only after a human
+ * approves the concrete recipient/subject/body.
+ *
+ * This module is browser-safe (no static Node imports) so it can be reached from
+ * assistant.ts/index.ts, which chat-ui bundles. The Resend transport below is pure `fetch`. The
+ * SMTP transport lives in email-smtp.ts (Node-only, lazy-loads nodemailer) and is wired in only by
+ * Node callers (cli.ts), the same split shell-executor.ts / node-fs-backend.ts already use.
+ */
+/** A concrete message the model has proposed. `from` is filled in by the transport if omitted. */
+export interface EmailMessage {
+    to: string;
+    subject: string;
+    body: string;
+    from?: string;
+    cc?: string;
+    bcc?: string;
+}
+export interface SendEmailResult {
+    /** Provider-assigned id for the delivered message, when the transport returns one. */
+    id?: string;
+    provider: 'resend' | 'smtp';
+}
+/**
+ * Delivers a message for real. Injected into applyPendingAction (file-tools.ts) rather than
+ * imported, so the staging/approval path has no transport dependency and stays unit-testable with
+ * a spy. Throws on a delivery failure — applyPendingAction lets that propagate to the caller.
+ */
+export type SendEmail = (message: EmailMessage) => Promise<SendEmailResult>;
+export declare class EmailDeliveryError extends Error {
+    readonly provider: 'resend' | 'smtp';
+    constructor(provider: 'resend' | 'smtp', detail: string);
+}
+/** Minimal RFC-5322-ish address check — a staged action with a malformed recipient is rejected before it is ever shown for approval. */
+export declare function isLikelyEmailAddress(value: string): boolean;
+export interface ResendSenderOptions {
+    apiKey: string;
+    /** The verified sender address Resend delivers as. Required — Resend rejects a send with no `from`. */
+    from: string;
+    /** Override for tests; defaults to the global fetch. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Resend transport (https://resend.com) — a single authenticated POST, works in Node and the
+ * browser. `apiKey` and `from` come from config (ASSISTANT_EMAIL_* / config.json), never from the
+ * model.
+ */
+export declare function createResendSender(options: ResendSenderOptions): SendEmail;
+/**
+ * One-line human-readable summary of a staged email, for the approval prompt and trace. Kept here
+ * (not in agent-loop.ts) so the MCP server (file-tools-mcp-server.mjs) and the CLI can format the
+ * same way without importing the loop.
+ */
+export declare function formatEmailApprovalReason(message: Pick<EmailMessage, 'to' | 'subject' | 'body'>): string;

package/dist/error-classifier.d.ts

@@ -0,0 +1,13 @@
+import { AssistantConfig } from './config.js';
+export interface ErrorClassification {
+    message: string;
+    retryable: boolean;
+}
+/**
+ * Maps a thrown turn error to user-facing copy and whether retrying is worth offering. Defaults
+ * to a generic, still-retryable message for anything unrecognized. `backend` (the caller's
+ * current `config.llmBackend`) disambiguates errors whose shape is identical across backends but
+ * whose actual cause/remedy differs — see the FlowExecutionError pattern's comment above; omit it
+ * only when no backend context exists (e.g. classifying a local file-write error).
+ */
+export declare function classifyError(err: unknown, backend?: AssistantConfig['llmBackend']): ErrorClassification;

package/dist/execution-mode.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Phase 4 of plans/harness_and_assistant_architecture_remediation_plan.html: a named,
+ * typed replacement for the three implicit bypass branches runTurn() used to make on its
+ * own, ad hoc, with no shared vocabulary between them:
+ *   - classification.isTrivial          → skip the harness run entirely (assistant.ts:1487-1495)
+ *   - the plan-cancel bypass            → skip classifyTurnIntent entirely (assistant.ts:1341-1370)
+ *   - the batch-confirmation resume     → skip the per-turn HarnessRuntime run entirely (assistant.ts:2467-2487)
+ * Each of those is a real, distinct guarantee-level a turn can run at — README's "every ordinary
+ * message walks the full 11-layer harness" claim is only true for two of the five modes below, and
+ * classifyExecutionMode() makes that precise instead of leaving it to be inferred from call-site
+ * reading order.
+ */
+export type ExecutionMode = 'FAST' | 'TOOL' | 'PLAN' | 'CONSEQUENTIAL' | 'RESEARCH';
+/**
+ * Per-mode guarantee documentation — what a caller can and can't rely on for a turn classified
+ * into each mode. Kept next to the type (not just in this file's header comment) so a reader
+ * inspecting one mode's behavior sees its contract without having to scroll up.
+ *
+ *  - FAST:          Trivial, self-contained factual turns (turn-intent-classifier.ts's isTrivial
+ *                    contract). No HarnessRuntime run at all this turn — no verification, no
+ *                    control-state, no reviewer pass, no checkpoint. Fastest path, weakest
+ *                    guarantees; safe only because isTrivial is deliberately conservative.
+ *  - PLAN:          A durable-plan bookkeeping turn (cancel/abandon a task) that never leaves this
+ *                    session's own plan-store state — no external effect, so no harness run and no
+ *                    tool loop either.
+ *  - RESEARCH:      The batch-research path (an explicit N-item list). Runs its own self-calibrating
+ *                    per-item tool-call budget (see budget.ts / BATCH_* constants) instead of the
+ *                    harness's task graph; a confirmed-large batch pauses for approval before
+ *                    spending it. No per-turn HarnessRuntime run backs this mode's own tool calls
+ *                    (though a resumed confirmation still skips it too, matching the direct path).
+ *  - TOOL:          An ordinary tool-using turn with no approval gate tripped. Walks the full
+ *                    HarnessRuntime run (world model, hypothesis, contradiction, control state,
+ *                    verification, recovery, reviewer pass) over the tool loop's already-produced
+ *                    reply — today's real guarantee level, still post-hoc bookkeeping rather than
+ *                    an in-loop control plane (see ToolPolicy for where deterministic, harness-
+ *                    state-informed gating is actually enforced).
+ *  - CONSEQUENTIAL: turn-policy.ts's evaluateTurnPolicy() returned REQUIRE_APPROVAL, or the
+ *                    turn's tool calls include a write_file/run_shell_command (always staged,
+ *                    independent of risk classification — see ToolPolicy). Never executes without
+ *                    an explicit approve-by-ID round trip; the harness run (when one applies)
+ *                    still runs on top for bookkeeping, but TurnPolicy/ToolPolicy — not
+ *                    classification.riskLevel/requiresApproval directly — are the actual
+ *                    authoritative decision for whether this turn's action proceeds (Phase D3).
+ */
+export declare const EXECUTION_MODE_GUARANTEES: Record<ExecutionMode, string>;
+export interface ExecutionModeInput {
+    /** True when the plan-cancel bypass (matchTaskCancelAttempt) short-circuited before
+     * classifyTurnIntent ever ran this turn. */
+    isPlanCancelBypass: boolean;
+    /** True when this turn is resolving a batch-research confirmation pause
+     * (resolvePendingBatchConfirmation) or is about to enter the batch-research path
+     * (runBatchToolLoop) fresh. */
+    isBatchResearch: boolean;
+    /** turn-intent-classifier.ts's own isTrivial verdict — only meaningful once classification has
+     * actually run (never true when isPlanCancelBypass/isBatchResearch already short-circuited). */
+    isTrivial: boolean;
+    /** turn-policy.ts's evaluateTurnPolicy() decision (REQUIRE_APPROVAL), recomputed from
+     * turn-intent-classifier.ts's riskLevel/isBulkReminderRequest signals rather than read directly
+     * off its requiresApproval boolean — OR a write_file/run_shell_command tool call was proposed
+     * this turn (file-tools.ts's unconditional per-call staging gate). See ToolPolicy for the
+     * per-tool-call analog of this same deterministic-gate shape. */
+    requiresApproval: boolean;
+}
+/**
+ * Pure classification — no I/O, no LLM call. Order matters: earlier bypasses in runTurn's own
+ * control flow take precedence over classification fields that were never computed for that path
+ * (e.g. isTrivial is meaningless once isPlanCancelBypass already fired), mirroring the exact
+ * precedence runTurn's own if/else chain already encodes today.
+ */
+export declare function classifyExecutionMode(input: ExecutionModeInput): ExecutionMode;
+/**
+ * classifyExecutionMode() plus the trace-emission wrapper every call site used to repeat inline
+ * (PersonalAssistant.classifyAndTraceExecutionMode, before the Phase 4d module split) — always
+ * traces unconditionally (the ASSISTANT_CONTROL_PLANE flag this used to gate on was removed in
+ * Phase 4b). Shared by every module that needs to classify-and-trace this turn's ExecutionMode
+ * (action-approval-service.ts's resolvePendingBatchConfirmation, and assistant.ts's own
+ * sequencer — TurnInterpreter deliberately never touches onTrace at all, see its own doc
+ * comment) instead of each repeating `onTrace?.(...)` separately. Takes the narrowest event
+ * shape it actually emits (not the full TraceEvent union) so this file never needs to import
+ * trace-events.ts, which itself imports ExecutionMode from here.
+ */
+export declare function classifyAndTraceExecutionMode(onTrace: ((event: {
+    kind: 'execution_mode_classified';
+    mode: ExecutionMode;
+}) => void) | undefined, input: ExecutionModeInput): ExecutionMode;

package/dist/fact-extraction.d.ts

@@ -0,0 +1,143 @@
+import { FactConfidence, FactCategory } from './turn-intent-classifier.js';
+/**
+ * Provenance of a captured fact — Phase 5 of the harness/personal-assistant remediation plan
+ * (plans/harness_and_assistant_architecture_remediation_plan.html), replacing the previous bare
+ * `durable: boolean` with a typed source plus a promotion policy keyed off it (see
+ * assistant.ts's recordFacts()). USER_ASSERTED is this file's own free lexical marker pass
+ * (extractFactsFromTurn) — unchanged in behavior and still auto-promotable, exactly as before
+ * this phase. MODEL_INFERRED is classifyTurnIntent's statesDurableFact free-form LLM read, only
+ * ever consulted when the lexical pass found nothing — no longer auto-promoted to durable status
+ * on its own (see recordFacts). OBSERVED and EXTERNALLY_VERIFIED have no producer in this
+ * codebase yet (e.g. a future tool-observed state claim, or Phase 6's AnswerClaim evidence
+ * trail) — defined now so a future producer has a typed slot to land in rather than overloading
+ * MODEL_INFERRED for something with a different trust profile.
+ *
+ * Storage-taxonomy note (Phase 5b, superseded by Phase E's typed `MemoryTier` below): `UserFact`
+ * is this codebase's Knowledge-shaped data ("what we believe") — `text`/`durable` is the belief
+ * itself; `FactSource` is its provenance ("why we believe it"). See
+ * packages/aielia/README.md's "Memory tiers" section for the full tier map this fits
+ * into, and memory-service.ts's DURABLE_FACTS_KEY doc comment for where promoted facts are stored.
+ */
+export type FactSource = 'user_asserted' | 'model_inferred' | 'observed' | 'externally_verified';
+export interface UserFact {
+    text: string;
+    extractedAt: string;
+    sourceTurn: string;
+    /**
+     * True for a fact currently promoted to the cross-session store that survives /new (name,
+     * stated preference, health/dietary — see DURABLE_MARKERS below), false for a session-scoped
+     * detail (current location, current job, "remember that"-style context, or an unconfirmed
+     * MODEL_INFERRED claim) that's expected to change more often or hasn't earned promotion yet.
+     * Derived from `source` via the promotion policy in recordFacts(), not set independently.
+     * assistant.ts's recordFacts() stores promoted facts in a second, never-cleared store in
+     * addition to the per-session one.
+     */
+    durable: boolean;
+    /** See FactSource. */
+    source: FactSource;
+    /**
+     * Confidence `classifyTurnIntent`'s `StatedFact.confidence` (turn-intent-classifier.ts) assigns
+     * a `model_inferred` fact — undefined for `user_asserted`/`observed`/`externally_verified`
+     * facts, which have no confidence gradient (they either matched a lexical pattern or didn't).
+     * Added in Phase 2 of plans/personal_assistant_fact_extraction_llm_confidence_plan.html for
+     * `recordFacts()`'s three-way promotion policy; Phase 4 additionally uses it to adjust
+     * `tierForFact()` and to annotate the per-turn facts prompt block. `migrateFact()` needs no
+     * change for this field — a pre-existing on-disk fact with no `confidence` reads back as
+     * `undefined`, which every reader here already treats as "no confidence signal, most
+     * conservative".
+     */
+    confidence?: FactConfidence;
+    /**
+     * `StatedFact.category` (turn-intent-classifier.ts) carried through onto the stored fact —
+     * undefined for `user_asserted`/`observed`/`externally_verified` facts, same "no signal from
+     * that source" convention `confidence` already follows. Added in Phase 3 of
+     * plans/personal_assistant_fact_extraction_llm_confidence_plan.html so a medium-confidence
+     * fact queued to `facts:pending-confirmation` (memory-service.ts) carries the topic its
+     * `/memory` grouping needs — see that file's `PendingFact`.
+     */
+    category?: FactCategory;
+    /**
+     * The project label this fact is scoped to — undefined means global (always shown, regardless
+     * of which project is active). Set by `MemoryService.recordFacts()`/`buildTurnFacts()` only for
+     * a fact classified `category: 'project'` (see FactCategory), using whatever
+     * `PersonalAssistant`'s `currentProject()` getter resolves to at capture time: an explicit
+     * `config.activeProject` override if the user set one via `/project <name>`, else the workspace
+     * root the assistant is running in. A fact in any other category is inherently about the user,
+     * not a codebase, so it stays global on purpose even while a project is active.
+     * `loadFacts()`/`getMemorySummary()` still return every fact regardless of `project` — only the
+     * turn's `factsBlock` (what the model actually sees) filters to global-or-current-project, so
+     * `/memory` stays a complete inventory the user can review/forget from regardless of which
+     * project is currently active.
+     */
+    project?: string;
+}
+/** Every fact has a certainty for `/memory` display purposes, even one with no `confidence` gradient (user_asserted/observed/externally_verified) — those are exactly as certain as a stated fact gets, so they display as 'high' rather than blank. Never used for promotion/tier logic, which still reads `fact.confidence` directly and treats undefined as "no LLM confidence signal" (see that field's own doc comment) — this is purely a rendering convenience. */
+export declare function certaintyLabel(fact: UserFact): FactConfidence;
+export declare function migrateFact(fact: UserFact): UserFact;
+/**
+ * The six-tier taxonomy (Phase E of the harness consolidation plan, criticism001 #8 /
+ * criticism002 #6: "transcript ≠ memory"), made real as a type instead of the doc-comment-only
+ * split this file's `FactSource` note above already described. `UserFact` only ever populates
+ * four of these — `procedural` (the `ExperienceStore`) and `commitment` (`ReminderStore`) are
+ * separate stores with their own writers and never routed through `tierForFact`; keeping them in
+ * this union (rather than a narrower `UserFactTier`) is what lets `TIER_RULES.procedural`'s empty
+ * `allowedSources` structurally enforce INV-16 (no Experience entry is ever reachable as a
+ * `UserFact`, let alone a Knowledge one) instead of relying on every caller to remember to check.
+ */
+export type MemoryTier = 'episodic' | 'semantic' | 'procedural' | 'preference' | 'commitment' | 'identity';
+export interface TierRule {
+    /** FactSource values allowed to populate this tier — see TIER_RULES. */
+    allowedSources: FactSource[];
+    /** 'session': cleared with the rest of `facts:${sessionId}` on /new. 'durable': survives /new (DURABLE_FACTS_KEY today). */
+    retention: 'session' | 'durable';
+    /** Whether contradiction detection considers entries in this tier (see harness-bridge.ts's factExtractor). */
+    contradictionChecked: boolean;
+}
+/**
+ * Retention / contradiction / (implicitly, via `retention`) deletion rule per tier, plus the
+ * `FactSource` provenances allowed to populate it — the four properties Phase E's scope calls
+ * for. `procedural` and `commitment` have an empty `allowedSources`: no `UserFact` is ever tagged
+ * with either tier (see `tierForFact` below), so a `UserFact` can never populate the Experience or
+ * Commitment stores through this path — that's the structural half of INV-16, not just a runtime
+ * check.
+ */
+export declare const TIER_RULES: Record<MemoryTier, TierRule>;
+/**
+ * Routes a `UserFact` to its `MemoryTier` per Phase E / E3's rule, extended by Phase 4 of
+ * plans/personal_assistant_fact_extraction_llm_confidence_plan.html: `observed` (a future
+ * tool-observed claim) always stays `episodic` — an uncorroborated observation, never Knowledge.
+ * `model_inferred` (the LLM's `statesDurableFacts` guess) stays `episodic` too UNLESS it's both
+ * `durable` and `confidence === 'high'` — Phase 1's own definition of high confidence ("the user
+ * states it directly and unhedged about themselves in first person") is the same trust bar
+ * `user_asserted` facts clear by construction, so a high-confidence durable guess is routed
+ * exactly the same way from here on; medium/low confidence (or no confidence signal at all) stays
+ * a musing until/unless it's promoted via `/memory confirm` or corroboration reaches high — see
+ * `memory-service.ts`'s `promoteConfirmedFact()`, which re-sources a confirmed fact to
+ * `externally_verified` rather than relying on this function's `durable` check, since a fact
+ * queued via the low-confidence corroboration path isn't guaranteed to carry `durable: true`.
+ * `user_asserted`/`externally_verified`/qualifying `model_inferred` facts land in the durable
+ * `identity` or `preference` tier when the text itself reads as a name/preference statement and
+ * the fact earned promotion (`durable: true`); every other such fact (a stated job, location, or
+ * coding-fact-shaped claim — see `looksLikeCodingFact` — none of which are `durable` under
+ * `isDurable()` above) is `semantic`: still a stated claim about what's currently true, still
+ * eligible for contradiction detection (the "tests passed"/"tests failed" and nurse-vs-designer
+ * job-flip cases this file's admission logic exists to support), just not promoted to
+ * cross-session storage. Pure and total — every `UserFact` maps to exactly one tier, and
+ * `procedural`/`commitment` are never returned (see `TIER_RULES`'s doc comment).
+ */
+export declare function tierForFact(fact: UserFact): MemoryTier;
+/** Whether `tier` counts as the Knowledge tier for contradiction-detection purposes — see harness-bridge.ts's factExtractor and TIER_RULES.*.contradictionChecked. */
+export declare function isKnowledgeTier(tier: MemoryTier): boolean;
+/**
+ * Extracts at most one durable fact from a user message — verbatim, not summarized. Returns []
+ * when the message doesn't look like a fact statement.
+ *
+ * Also admits anything looksLikeCodingFact (contradiction-checker.ts) recognizes, unless the
+ * message also reads as a request or a question rather than a claim — a build/test/service-state
+ * claim like "the tests passed" is exactly what the World Model's belief/contradiction machinery
+ * (CODING_FACT_MARKERS, NEGATION_PAIRS) is built to track, but FACT_MARKERS' personal-fact
+ * phrasing never matched statements like that, so no belief was ever created for the
+ * contradiction checks to compare — a "tests passed" / "tests failed" flip produced zero beliefs
+ * and thus zero contradiction detection at any layer, lexical or LLM.
+ */
+export declare function extractFactsFromTurn(userMessage: string, sourceTurn: string): UserFact[];

package/dist/failure-mode-matcher.d.ts

@@ -0,0 +1,32 @@
+import { ILLMClient, TokenUsage } from '@buildaharness/runtime';
+import { FailureModeEntry } from '@buildaharness/harness';
+/**
+ * `AUDIT_SEMANTIC_FAILURE_MATCH` gate — feature-value audit (Phase A6 of
+ * plans/feature_audit_automation_plan.html). Default **ON**: the semantic failure-mode-matcher
+ * LLM call ships enabled, so an unset / empty / truthy value keeps today's behaviour. Set to a
+ * falsy value (`0` / `false` / `off` / `no` / `disabled`) to skip the LLM call entirely and fall
+ * back to `FailureModeLibrary.match()`'s exact-string-overlap check only. Read at exactly one call
+ * site — `harness-bridge.ts`, where the `semanticFailureMatcher` host hook is wired. Same shape as
+ * `semanticContradictionEnabled()` (contradiction-checker.ts) / `llmInjectionDetectEnabled()`
+ * (trust-tagging.ts) and the harness's `supervisorEnabled()`.
+ */
+export declare function semanticFailureMatchEnabled(env?: Record<string, string | undefined>): boolean;
+/**
+ * One LLM call checking a symptom set against the whole failure-mode library at once (never
+ * one call per entry) — layered on top of FailureModeLibrary.match()'s own exact-string-overlap
+ * check, which requires a symptom to be byte-for-byte identical to a curated one. That exact-match
+ * floor (and the shared-subject gates in detect-contradictions.ts / review-proposed-change.ts —
+ * see looksLikeCodingFact's doc comment in contradiction-checker.ts) is why decomposition-classifier.ts
+ * and plan-builder.ts prompt task descriptions to lead with their concrete subject: consistent
+ * subject vocabulary gives every lexical layer, not just this one, real overlap to match on. Since
+ * observations are free text ("Task executed: ...", "Result: ..."), exact equality against a
+ * curated list almost never happens by chance — this is what actually lets the library
+ * recognize a known failure pattern described in different words. Falls back to "no match" on
+ * any parse failure or LLM error, matching this codebase's other LLM-backed classifiers — a
+ * missed match costs nothing worse than the exact-match-only behavior this is layered on top of.
+ */
+export declare function checkSemanticFailureMatch(symptoms: string[], libraryEntries: readonly FailureModeEntry[], llmClient: ILLMClient, model?: string, onUsage?: (usage: TokenUsage) => void): Promise<{
+    failure_class: string;
+    confidence: number;
+    matched_pattern: string;
+} | null>;