useathena 0.1.0 → 0.2.0

package/dist/core/fixtures.js

@@ -41,6 +41,32 @@ export function makeInstance(overrides = {}) {
     };
     return { ...base, ...overrides };
 }
+export function makeObject(overrides = {}) {
+    const base = {
+        id: newId("obj"),
+        kind: "org",
+        name: "Acme Corp",
+        aliases: ["acme", "acme.com"],
+        properties: {},
+        validFrom: new Date(0).toISOString(),
+    };
+    return { ...base, ...overrides };
+}
+export function makeFact(overrides = {}) {
+    const base = {
+        id: newId("fct"),
+        objectId: newId("obj"),
+        statement: "Acme's contract renewal is in September 2026.",
+        domain: "email.outreach",
+        supportingInstanceIds: [newId("ins")],
+        confidence: 0.7,
+        firstSeenAt: new Date(0).toISOString(),
+        lastConfirmedAt: new Date(0).toISOString(),
+        staleAfter: new Date(180 * 24 * 3600 * 1000).toISOString(),
+        visibility: "user_private",
+    };
+    return { ...base, ...overrides };
+}
 export function makeHypothesis(overrides = {}) {
     const base = {
         id: newId("hyp"),

package/dist/core/refs.js

@@ -5,6 +5,8 @@ const KIND_BY_PREFIX = {
     src: "source",
     out: "outcome",
     brf: "brief",
+    fct: "fact",
+    drf: "draft",
 };
 export function refTo(id, fragment) {
     const prefix = id.split("_")[0] ?? "";

package/dist/engine/engine.js

@@ -28,13 +28,15 @@ export class LlmHypothesisEngine {
         this.replaySamples = Math.max(1, options.replaySamples ?? DEFAULT_REPLAY_SAMPLES);
     }
     async infer(instances) {
-        const hypotheses = [];
+        const output = { hypotheses: [], facts: [] };
         for (const [domain, cluster] of clusterByDomain(instances)) {
             if (cluster.length < MIN_CLUSTER_SIZE)
                 continue;
-            hypotheses.push(...(await this.inferCluster(domain, cluster)));
+            const clusterOutput = await this.inferCluster(domain, cluster);
+            output.hypotheses.push(...clusterOutput.hypotheses);
+            output.facts.push(...clusterOutput.facts);
         }
-        return hypotheses;
+        return output;
     }
     async inferCluster(domain, cluster) {
         const { train, holdout } = splitHoldout(cluster);
@@ -42,9 +44,9 @@ export class LlmHypothesisEngine {
             system: INFERENCE_SYSTEM,
             prompt: inferencePrompt(domain, train),
         });
-        const candidates = parseInferenceResponse(raw, train.length);
+        const parsed = parseInferenceResponse(raw, train.length);
         const results = [];
-        for (const candidate of candidates) {
+        for (const candidate of parsed.hypotheses) {
             const supportingInstanceIds = candidate.supporting.map((index) => train[index - 1].id);
             if (supportingInstanceIds.length === 0)
                 continue; // everything cites — uncited rules are dropped
@@ -66,7 +68,14 @@ export class LlmHypothesisEngine {
             }
             results.push(hypothesis);
         }
-        return results;
+        const facts = parsed.facts.map((fact) => ({
+            entity: fact.entity,
+            statement: fact.statement,
+            domain,
+            supportingInstanceIds: fact.supporting.map((index) => train[index - 1].id),
+            confidence: fact.confidence,
+        }));
+        return { hypotheses: results, facts };
     }
     /** Majority vote across samples; stops early once a side is unreachable. */
     async replayVerdict(hypothesis, heldOut) {

package/dist/engine/facts.js

@@ -0,0 +1,80 @@
+import { newId } from "../core/ids.js";
+import { changedRatio } from "../capture/ingest.js";
+/**
+ * Turn engine fact drafts into stored records: resolve or create the entity,
+ * then dedupe against that entity's existing facts — a restated fact confirms
+ * (bumps lastConfirmedAt, merges evidence) instead of duplicating. Facts are
+ * never entered manually and agents cannot write them directly; this is the
+ * only path in.
+ */
+const FACT_STALE_DAYS = 180;
+/** Statements this close (normalized edit distance) are the same fact. */
+const SAME_FACT_RATIO = 0.25;
+export function materializeFacts(store, drafts, now = () => new Date()) {
+    const result = { created: [], confirmed: [] };
+    for (const draft of drafts) {
+        const object = resolveOrCreateObject(store, draft, now);
+        const existing = findSameFact(store.listFacts({ objectId: object.id }), draft.statement);
+        if (existing) {
+            existing.lastConfirmedAt = now().toISOString();
+            existing.staleAfter = staleAfter(now);
+            existing.confidence = Math.max(existing.confidence, draft.confidence);
+            existing.supportingInstanceIds = [
+                ...new Set([...existing.supportingInstanceIds, ...draft.supportingInstanceIds]),
+            ];
+            store.saveFact(existing);
+            result.confirmed.push(existing);
+            continue;
+        }
+        const fact = {
+            id: newId("fct", now().getTime()),
+            objectId: object.id,
+            statement: draft.statement,
+            domain: draft.domain,
+            supportingInstanceIds: draft.supportingInstanceIds,
+            confidence: draft.confidence,
+            firstSeenAt: now().toISOString(),
+            lastConfirmedAt: now().toISOString(),
+            staleAfter: staleAfter(now),
+            visibility: "user_private",
+        };
+        store.saveFact(fact);
+        result.created.push(fact);
+    }
+    return result;
+}
+function resolveOrCreateObject(store, draft, now) {
+    for (const alias of [draft.entity.name, ...draft.entity.aliases]) {
+        const matches = store.resolveObject(alias);
+        if (matches[0]) {
+            const object = matches[0];
+            const known = new Set([object.name.toLowerCase(), ...object.aliases.map((a) => a.toLowerCase())]);
+            const fresh = draft.entity.aliases.filter((a) => !known.has(a.toLowerCase()));
+            if (fresh.length > 0) {
+                object.aliases = [...object.aliases, ...fresh];
+                store.saveObject(object);
+            }
+            return object;
+        }
+    }
+    const object = {
+        id: newId("obj", now().getTime()),
+        kind: draft.entity.kind,
+        name: draft.entity.name,
+        aliases: draft.entity.aliases,
+        properties: {},
+        validFrom: now().toISOString(),
+    };
+    store.saveObject(object);
+    return object;
+}
+function findSameFact(existing, statement) {
+    const normalized = normalize(statement);
+    return existing.find((fact) => !fact.supersededById && changedRatio(normalize(fact.statement), normalized) <= SAME_FACT_RATIO);
+}
+function normalize(text) {
+    return text.toLowerCase().replace(/[^\p{L}\p{N} ]/gu, "").replace(/\s+/g, " ").trim();
+}
+function staleAfter(now) {
+    return new Date(now().getTime() + FACT_STALE_DAYS * 24 * 3600 * 1000).toISOString();
+}

package/dist/engine/parse.js

@@ -1,13 +1,38 @@
-/**
- * Strict parsing of the inference response. The model is untrusted input;
- * everything is validated, indices are checked against the instance count,
- * and a malformed response throws with a message naming what was wrong.
- */
+const OBJECT_KINDS = ["person", "org", "project", "repo", "process", "custom"];
 export function parseInferenceResponse(raw, instanceCount) {
     if (typeof raw !== "object" || raw === null || !Array.isArray(raw.hypotheses)) {
         throw new Error(`inference response missing "hypotheses" array: ${preview(raw)}`);
     }
-    return (raw.hypotheses).map((entry, i) => parseHypothesis(entry, i, instanceCount));
+    const record = raw;
+    const hypotheses = record.hypotheses.map((entry, i) => parseHypothesis(entry, i, instanceCount));
+    // "facts" is optional in the response — older prompts and terse models omit it.
+    const facts = Array.isArray(record.facts)
+        ? record.facts.flatMap((entry, i) => parseFact(entry, i, instanceCount))
+        : [];
+    return { hypotheses, facts };
+}
+/** Malformed facts are dropped, not fatal — rules are the primary output. */
+function parseFact(entry, position, instanceCount) {
+    if (typeof entry !== "object" || entry === null)
+        return [];
+    const record = entry;
+    const entity = record.entity;
+    const name = typeof entity?.name === "string" ? entity.name.trim() : "";
+    const statement = typeof record.statement === "string" ? record.statement.trim() : "";
+    if (!name || !statement)
+        return [];
+    let supporting;
+    try {
+        supporting = requireIndexArray(record, "supporting", position, instanceCount);
+    }
+    catch {
+        return [];
+    }
+    if (supporting.length === 0)
+        return [];
+    const kind = OBJECT_KINDS.includes(entity?.kind) ? entity?.kind : "custom";
+    const confidence = typeof record.confidence === "number" ? clamp(record.confidence, 0.05, 0.95) : 0.5;
+    return [{ entity: { name, kind, aliases: stringArray(entity?.aliases) }, statement, supporting, confidence }];
 }
 function parseHypothesis(entry, position, instanceCount) {
     if (typeof entry !== "object" || entry === null) {

package/dist/engine/prompts.js

@@ -18,8 +18,17 @@ Extract the transferable judgment rules behind these edits. Requirements:
 - Cite supporting instances by their number. Cite counterexamples (instances that cut against the rule) by number too.
 - confidence is 0..1: your honest estimate that this rule reflects a stable preference rather than coincidence.
 
+Separately, extract FACTS: durable, declarative, entity-grounded statements an agent would need before acting in this domain ("Acme's renewal is in September", "Dana is the CFO and prefers bullet summaries", "the team tracks work in Linear"). Requirements for facts:
+
+- Each fact is about ONE named entity (a person, org, project, repo, process, or tool) and must be evident in the instances — never world knowledge, never speculation.
+- Facts are stable context, not judgments and not events ("sent an email Tuesday" is not a fact; "Priya is the GTM lead at Vanta" is).
+- No platitudes. If it would be true of any company, it is not a fact worth storing.
+- Cite supporting instances by number. Give each entity its kind and any aliases visible in the evidence (email addresses, handles, short names).
+- It is normal to extract zero facts.
+
 Respond with STRICT JSON only, no prose, matching:
-{"hypotheses": [{"rule": string, "cues": string[], "expectancies": string[], "goal": string?, "appliesWhen": string[], "doesNotApplyWhen": string[], "supporting": number[], "counterexamples": number[], "rationale": string, "confidence": number}]}`;
+{"hypotheses": [{"rule": string, "cues": string[], "expectancies": string[], "goal": string?, "appliesWhen": string[], "doesNotApplyWhen": string[], "supporting": number[], "counterexamples": number[], "rationale": string, "confidence": number}],
+ "facts": [{"entity": {"name": string, "kind": "person"|"org"|"project"|"repo"|"process"|"custom", "aliases": string[]}, "statement": string, "supporting": number[], "confidence": number}]}`;
 export function inferencePrompt(domain, instances) {
     const blocks = instances.map((instance, i) => renderInstance(instance, i + 1));
     return `Domain: ${domain}\n\n${blocks.join("\n\n")}`;

package/dist/eval/run-eval.js

@@ -21,9 +21,9 @@ const judge = useLlmJudge ? new LlmJudge(model) : new RubricJudge();
 const inferred = new Map();
 const engine = {
     infer: async (instances) => {
-        const hypotheses = await inner.infer(instances);
-        inferred.set(instances[0]?.situation.domain ?? "unknown", hypotheses);
-        return hypotheses;
+        const output = await inner.infer(instances);
+        inferred.set(instances[0]?.situation.domain ?? "unknown", output.hypotheses);
+        return output.hypotheses;
     },
 };
 console.log(`engine model: ${model.id}   judge: ${useLlmJudge ? `llm (${model.id})` : "rubric"}`);

package/dist/mcp/server.js

@@ -1,6 +1,9 @@
+import { createHash } from "node:crypto";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { ingestSensorEvent } from "../capture/ingest.js";
+import { newId } from "../core/ids.js";
+import { ingestAndMatch } from "../serve/auto-outcome.js";
+import { maybeAutoLearn } from "../serve/auto-learn.js";
 import { compileBrief } from "../serve/brief.js";
 import { recordOutcome } from "../serve/outcome.js";
 import { openRef } from "../store/open.js";
@@ -22,7 +25,7 @@ const OUTCOME_RESULTS = ["uncorrected", "corrected", "abandoned", "unknown"];
 export function buildMcpServer(store) {
     const server = new McpServer({ name: "athena", version: "0.1.0" });
     server.registerTool("athena_brief", {
-        description: "Call this BEFORE acting on a task. Returns the tacit judgment rules that apply (with confidence and boundary conditions), relevant facts with citations, things you must not assume, open questions, and a readiness verdict (act / act_with_caveats / inspect_first / ask_human). Honor the boundaries and do-not-assume list. After finishing the task, report what happened with athena_record type=outcome, citing the briefId.",
+        description: "Call this BEFORE acting on a task. Returns the tacit judgment rules that apply (with confidence and boundary conditions), relevant facts with citations, things you must not assume, open questions, a readiness verdict (act / act_with_caveats / inspect_first / ask_human), and a map of everything else athena knows (use athena_search/athena_open to pull what you need — you are not flooded by default). Honor the boundaries and do-not-assume list. After drafting, register your artifact with athena_record type=output so the outcome can be detected automatically; or report it explicitly with type=outcome.",
         inputSchema: {
             task: z.string().describe("The task you are about to perform, in one sentence"),
             domain: z
@@ -44,18 +47,19 @@ export function buildMcpServer(store) {
         return asJson(entity);
     });
     server.registerTool("athena_record", {
-        description: "Report back to athena. type=outcome: after a task where you used a brief, report whether your output was accepted unchanged (uncorrected) or edited by the human (corrected) — this is how rules earn or lose trust. type=event: capture a judgment moment you observed (a correction of your output, a human decision, a failed approach, an explicit 'remember this'). Events become evidence for new rules after review; nothing you record changes durable rules directly.",
+        description: "Report back to athena. type=output: register the artifact you produced from a brief (an email draft, a message) — when a sensor later observes what the human actually sent, athena matches it and records the outcome automatically. type=outcome: explicitly report whether your briefed output was accepted unchanged (uncorrected) or edited (corrected) — this is how rules earn or lose trust. type=event: capture a judgment moment you observed (a correction of your output, a human decision, a failed approach, an explicit 'remember this'). Events become evidence for new rules and facts; nothing you record changes durable rules directly.",
         inputSchema: {
-            type: z.enum(["outcome", "event"]),
-            briefId: z.string().optional().describe("outcome: the brief this outcome judges"),
+            type: z.enum(["outcome", "event", "output"]),
+            briefId: z.string().optional().describe("outcome/output: the brief this belongs to"),
             result: z.enum(OUTCOME_RESULTS).optional().describe("outcome: what happened"),
             correctionInstanceId: z
                 .string()
                 .optional()
                 .describe("outcome: if corrected, the instance id of the captured correction (record the event first)"),
+            content: z.string().optional().describe("output: the artifact you produced, verbatim"),
             kind: z.enum(INSTANCE_KINDS).optional().describe("event: what kind of judgment moment"),
             summary: z.string().optional().describe("event: one-line situation summary"),
-            domain: z.string().optional().describe('event: dot-path domain, e.g. "email.outreach"'),
+            domain: z.string().optional().describe('event/output: dot-path domain, e.g. "email.outreach"'),
             task: z.string().optional().describe("event: what was being attempted"),
             before: z.string().optional().describe("event: the draft/output before the human acted"),
             after: z.string().optional().describe("event: the human's version (omit for approvals)"),
@@ -74,6 +78,24 @@ export function buildMcpServer(store) {
             });
             return asJson(outcome);
         }
+        if (args.type === "output") {
+            if (!args.briefId || !args.content)
+                throw new Error("output requires briefId and content");
+            const brief = store.getBrief(args.briefId);
+            if (!brief)
+                throw new Error(`unknown brief ${args.briefId}`);
+            const draft = {
+                id: newId("drf"),
+                briefId: brief.id,
+                content: args.content,
+                contentHash: createHash("sha256").update(args.content).digest("hex").slice(0, 16),
+                mediaType: "text/plain",
+                domain: args.domain ?? brief.domain ?? "general",
+                recordedAt: new Date().toISOString(),
+            };
+            store.saveDraft(draft);
+            return asJson({ registered: draft.id, watchingDomain: draft.domain });
+        }
         if (!args.kind || !args.summary)
             throw new Error("event requires kind and summary");
         const event = {
@@ -89,14 +111,20 @@ export function buildMcpServer(store) {
             ...(args.before !== undefined ? { before: { mediaType: "text/plain", content: args.before } } : {}),
             ...(args.after !== undefined ? { after: { mediaType: "text/plain", content: args.after } } : {}),
         };
-        const instance = ingestSensorEvent(store, event);
-        return asJson({ recorded: instance.id, kind: instance.kind, domain: instance.situation.domain });
+        const { instance, autoOutcome } = ingestAndMatch(store, event);
+        maybeAutoLearn(store);
+        return asJson({
+            recorded: instance.id,
+            kind: instance.kind,
+            domain: instance.situation.domain,
+            ...(autoOutcome ? { autoOutcome: { id: autoOutcome.id, result: autoOutcome.result } } : {}),
+        });
     });
     server.registerTool("athena_search", {
-        description: "Lexical search across captured judgment instances, learned rules, and sources. Returns athena:// refs ranked by relevance — open them with athena_open.",
+        description: "Lexical search across captured judgment instances, learned rules, extracted facts, and sources. Returns athena:// refs ranked by relevance — open them with athena_open. The brief's map tells you what is worth searching for.",
         inputSchema: {
             query: z.string(),
-            lane: z.enum(["instance", "hypothesis", "source"]).optional().describe("Restrict to one lane"),
+            lane: z.enum(["instance", "hypothesis", "source", "fact"]).optional().describe("Restrict to one lane"),
             limit: z.number().int().min(1).max(50).optional(),
         },
     }, ({ query, lane, limit }) => asJson(store.search(query, lane, limit ?? 20)));

package/dist/sensors/claude-code-hook.js

@@ -1,6 +1,6 @@
 import { closeSync, openSync, readSync, statSync } from "node:fs";
 import { basename } from "node:path";
-import { ingestSensorEvent } from "../capture/ingest.js";
+import { ingestAndMatch } from "../serve/auto-outcome.js";
 const EXPLICIT_MARKER = /^(remember|athena)\s*[:,]\s*(.+)$/is;
 /** Redirects at the start of a prompt: the user is stopping or reversing the agent. */
 const REDIRECT_START = /^(no|nope|wrong|wait|stop|hold on|don't|do not|undo|revert|not like that)\b/i;
@@ -8,6 +8,13 @@ const REDIRECT_START = /^(no|nope|wrong|wait|stop|hold on|don't|do not|undo|reve
 const REDIRECT_START_EXCEPTIONS = /^no (worries|problem|rush|need)\b/i;
 /** Correction phrases anywhere in the prompt. */
 const REDIRECT_INLINE = /\b(that's (wrong|not right|not what)|not what i (asked|meant|wanted)|why did you|you should(n't| not) have|i didn't ask (for|you)|never do that|don't do that again|you keep|again with)\b/i;
+/** Approvals at the start of a short prompt: the user is accepting the agent's output. */
+const APPROVAL_START = /^(lgtm|looks good|looks great|looks right|love it|ship it|approved|that works|works for me)\b/i;
+/** Bare one-word sign-offs count too — but only on their own. */
+const APPROVAL_EXACT = /^(perfect|great|nice|done|exactly)[.!\s]*$/i;
+/** "looks good, but…" is a correction wearing an approval's hat. */
+const APPROVAL_REVERSAL = /\b(but|except|however|though|almost|one (thing|issue|nit)|small (thing|nit)|can you|change|fix)\b/i;
+const APPROVAL_MAX_LENGTH = 100;
 export function detectSignal(prompt) {
     const trimmed = prompt.trim();
     if (trimmed.length === 0)
@@ -22,6 +29,11 @@ export function detectSignal(prompt) {
     if (REDIRECT_INLINE.test(trimmed)) {
         return { kind: "override", reason: "correction_phrase" };
     }
+    if (trimmed.length <= APPROVAL_MAX_LENGTH &&
+        (APPROVAL_START.test(trimmed) || APPROVAL_EXACT.test(trimmed)) &&
+        !APPROVAL_REVERSAL.test(trimmed)) {
+        return { kind: "approval", reason: "approval_phrase" };
+    }
     return undefined;
 }
 export function handleUserPrompt(store, input) {
@@ -45,6 +57,23 @@ export function handleUserPrompt(store, input) {
             after: { mediaType: "text/plain", content: signal.note },
         };
     }
+    else if (signal.kind === "approval") {
+        // What was approved (the transcript tail) is the evidence — it can also
+        // resolve a registered agent draft into an uncorrected outcome.
+        const lastTurn = input.transcript_path ? lastAssistantTurn(input.transcript_path) : undefined;
+        event = {
+            sensorId: "sen_claude_code",
+            emittedAt,
+            kind: "approval",
+            situation: {
+                summary: `user approved the agent's output: ${truncate(input.prompt, 100)}`,
+                domain,
+                app: "claude-code",
+            },
+            ...(lastTurn !== undefined ? { before: { mediaType: "text/markdown", content: lastTurn } } : {}),
+            raw: { reason: signal.reason, sessionId: input.session_id },
+        };
+    }
     else {
         const lastTurn = input.transcript_path ? lastAssistantTurn(input.transcript_path) : undefined;
         event = {
@@ -61,7 +90,7 @@ export function handleUserPrompt(store, input) {
             raw: { reason: signal.reason, sessionId: input.session_id },
         };
     }
-    const instance = ingestSensorEvent(store, event);
+    const { instance } = ingestAndMatch(store, event);
     return { captured: instance.id, kind: instance.kind };
 }
 const TAIL_BYTES = 64_000;

package/dist/serve/auto-learn.js

@@ -0,0 +1,56 @@
+import { spawn } from "node:child_process";
+import { mkdirSync, openSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { dbPath } from "../config.js";
+/**
+ * Keeps the loop from stalling on a forgotten `athena learn`: every sensor
+ * entry point calls maybeAutoLearn after ingesting, and once enough new
+ * evidence has accumulated a detached `athena learn` runs in the background.
+ *
+ * Guards, in order: a kill switch (ATHENA_AUTO_LEARN=off), an evidence
+ * threshold (don't spend inference on every capture), and a cooldown (don't
+ * stack runs while one is still thinking). Never throws — a broken trigger
+ * must never break capture.
+ */
+/** Stamped by cmdLearn on every completed run (manual or automatic). */
+export const LAST_LEARN_AT = "learn.lastRunAt";
+const LAST_ATTEMPT_AT = "autoLearn.lastAttemptAt";
+export const AUTO_LEARN_THRESHOLD = 5;
+const COOLDOWN_MS = 30 * 60 * 1000;
+export function autoLearnEnabled(env = process.env) {
+    const value = (env.ATHENA_AUTO_LEARN ?? "").toLowerCase();
+    return !["0", "false", "off", "no"].includes(value);
+}
+export function maybeAutoLearn(store, options = {}) {
+    const now = options.now ?? (() => new Date());
+    try {
+        const pending = store.countInstancesSince(store.getMeta(LAST_LEARN_AT));
+        if (!autoLearnEnabled(options.env)) {
+            return { launched: false, reason: "disabled via ATHENA_AUTO_LEARN", pending };
+        }
+        if (pending < AUTO_LEARN_THRESHOLD) {
+            return { launched: false, reason: `below threshold (${pending}/${AUTO_LEARN_THRESHOLD})`, pending };
+        }
+        const lastAttempt = store.getMeta(LAST_ATTEMPT_AT);
+        if (lastAttempt && now().getTime() - new Date(lastAttempt).getTime() < COOLDOWN_MS) {
+            return { launched: false, reason: "cooling down", pending };
+        }
+        store.setMeta(LAST_ATTEMPT_AT, now().toISOString());
+        (options.launch ?? launchDetachedLearn)();
+        return { launched: true, reason: "threshold reached", pending };
+    }
+    catch {
+        return { launched: false, reason: "trigger error (ignored)", pending: 0 };
+    }
+}
+/** Spawn `athena learn` detached so the calling sensor returns immediately. */
+function launchDetachedLearn() {
+    const packageRoot = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+    const bin = join(packageRoot, "bin", "athena");
+    const logDir = dirname(dbPath());
+    mkdirSync(logDir, { recursive: true });
+    const log = openSync(join(logDir, "auto-learn.log"), "a");
+    const child = spawn(process.execPath, [bin, "learn"], { detached: true, stdio: ["ignore", log, log] });
+    child.unref();
+}

package/dist/serve/auto-outcome.js

@@ -0,0 +1,63 @@
+import { changedRatio, ingestSensorEvent } from "../capture/ingest.js";
+import { recordOutcome } from "./outcome.js";
+/**
+ * Closes the loop without anyone reporting: an agent registers the draft it
+ * produced from a brief (athena_record type=output); when a sensor later
+ * captures what the human actually did with it, the instance is matched back
+ * to the draft and the outcome records itself — approval → uncorrected,
+ * correction → corrected with the instance as the counterexample.
+ *
+ * Matching is conservative: same domain, recent, and the captured "before"
+ * must be essentially the registered draft. A miss costs nothing (outcomes
+ * can still be recorded explicitly); a false match would corrupt trust.
+ */
+const MATCH_WINDOW_HOURS = 72;
+/** Captured before-text may differ from the draft by at most this much. */
+const MATCH_RATIO = 0.15;
+/**
+ * What every sensor should call: ingest the event, then see whether the new
+ * evidence resolves a registered draft into an outcome.
+ */
+export function ingestAndMatch(store, event, options = {}, now = () => new Date()) {
+    expireStaleDrafts(store, now);
+    const instance = ingestSensorEvent(store, event, options);
+    const autoOutcome = matchDraftToInstance(store, instance, now);
+    return autoOutcome ? { instance, autoOutcome } : { instance };
+}
+/**
+ * Drafts that outlive the match window resolve to result "unknown": the loop
+ * closes honestly instead of leaving them "awaiting" forever, and rule trust
+ * is untouched (only uncorrected/corrected adjust it). Swept opportunistically
+ * on every ingest.
+ */
+export function expireStaleDrafts(store, now = () => new Date()) {
+    const cutoff = new Date(now().getTime() - MATCH_WINDOW_HOURS * 3600 * 1000).toISOString();
+    return store
+        .listUnmatchedDrafts({})
+        .filter((draft) => draft.recordedAt < cutoff)
+        .map((draft) => {
+        const outcome = recordOutcome(store, { briefId: draft.briefId, result: "unknown" }, now);
+        draft.matchedOutcomeId = outcome.id;
+        store.saveDraft(draft);
+        return outcome;
+    });
+}
+export function matchDraftToInstance(store, instance, now = () => new Date()) {
+    if (instance.kind !== "correction" && instance.kind !== "override" && instance.kind !== "approval") {
+        return undefined;
+    }
+    const captured = instance.before?.content;
+    if (!captured)
+        return undefined;
+    const since = new Date(now().getTime() - MATCH_WINDOW_HOURS * 3600 * 1000).toISOString();
+    const candidates = store.listUnmatchedDrafts({ domain: instance.situation.domain, since });
+    const draft = candidates.find((candidate) => changedRatio(candidate.content, captured) <= MATCH_RATIO);
+    if (!draft)
+        return undefined;
+    const outcome = recordOutcome(store, instance.kind === "approval"
+        ? { briefId: draft.briefId, result: "uncorrected" }
+        : { briefId: draft.briefId, result: "corrected", correctionInstanceId: instance.id }, now);
+    draft.matchedOutcomeId = outcome.id;
+    store.saveDraft(draft);
+    return outcome;
+}

package/dist/serve/brief.js

@@ -12,8 +12,9 @@ import { parseRef, refTo } from "../core/refs.js";
  *   ask_human         athena knows nothing useful for this task
  */
 const MAX_RULES = 5;
-const MAX_FACTS = 3;
+const MAX_FACTS = 5;
 const MAX_OPEN_QUESTIONS = 3;
+const MAX_MAP_ENTRIES = 8;
 const HIGH_CONFIDENCE = 0.7;
 export function compileBrief(store, request, now = () => new Date()) {
     const inScope = collectHypotheses(store, request);
@@ -32,16 +33,7 @@ export function compileBrief(store, request, now = () => new Date()) {
         boundaries: h.doesNotApplyWhen,
         ref: refTo(h.id),
     }));
-    const facts = store
-        .search(request.task, "source", MAX_FACTS)
-        .flatMap((hit) => {
-        const source = store.getSource(parseRef(hit.ref).id);
-        return source ? [source] : [];
-    })
-        .map((source) => ({
-        statement: `${source.title}: ${source.content.slice(0, 160)}`,
-        ref: refTo(source.id),
-    }));
+    const facts = collectFacts(store, request, now);
     const doNotAssume = stale.map((h) => `A previously learned rule is stale — do not assume it still holds: "${h.rule}"`);
     const openQuestions = unvalidated
         .slice(0, MAX_OPEN_QUESTIONS)
@@ -49,6 +41,7 @@ export function compileBrief(store, request, now = () => new Date()) {
     const brief = {
         id: newId("brf", now().getTime()),
         task: request.task,
+        ...(request.domain !== undefined ? { domain: request.domain } : {}),
         compiledAt: now().toISOString(),
         rules,
         facts,
@@ -56,6 +49,7 @@ export function compileBrief(store, request, now = () => new Date()) {
         openQuestions,
         readiness: readinessFor(rules, facts, doNotAssume, openQuestions),
         refs: [...rules.map((r) => r.ref), ...facts.map((f) => f.ref), ...unvalidated.slice(0, MAX_OPEN_QUESTIONS).map((h) => refTo(h.id))],
+        map: knowledgeMap(store),
     };
     // Serving is an event: fires feed the outcome loop.
     for (const rule of rules) {
@@ -69,6 +63,65 @@ export function compileBrief(store, request, now = () => new Date()) {
     store.saveBrief(brief);
     return brief;
 }
+/**
+ * Facts reach a brief three ways: the task names a known entity (alias match),
+ * the task's domain produced facts, or lexical search hits. Stale and
+ * superseded facts never serve.
+ */
+function collectFacts(store, request, now) {
+    const byId = new Map();
+    const task = ` ${request.task.toLowerCase()} `;
+    for (const object of store.listObjects()) {
+        const aliases = [object.name, ...object.aliases].filter((alias) => alias.length >= 3);
+        if (!aliases.some((alias) => task.includes(alias.toLowerCase())))
+            continue;
+        for (const fact of store.listFacts({ objectId: object.id }))
+            byId.set(fact.id, fact);
+    }
+    if (request.domain) {
+        for (const fact of store.listFacts({ domain: request.domain }))
+            byId.set(fact.id, fact);
+    }
+    for (const hit of store.search(request.task, "fact", MAX_FACTS)) {
+        const fact = store.getFact(parseRef(hit.ref).id);
+        if (fact)
+            byId.set(fact.id, fact);
+    }
+    const nowIso = now().toISOString();
+    const live = [...byId.values()]
+        .filter((fact) => !fact.supersededById && fact.staleAfter > nowIso)
+        .sort((a, b) => b.lastConfirmedAt.localeCompare(a.lastConfirmedAt))
+        .slice(0, MAX_FACTS)
+        .map((fact) => ({ statement: fact.statement, ref: refTo(fact.id) }));
+    if (live.length >= MAX_FACTS)
+        return live;
+    // Raw sources fill remaining slots — weaker than extracted facts, still cited.
+    const sources = store
+        .search(request.task, "source", MAX_FACTS - live.length)
+        .flatMap((hit) => {
+        const source = store.getSource(parseRef(hit.ref).id);
+        return source ? [source] : [];
+    })
+        .map((source) => ({
+        statement: `${source.title}: ${source.content.slice(0, 160)}`,
+        ref: refTo(source.id),
+    }));
+    return [...live, ...sources];
+}
+/** The coordinates: what athena knows about and how to retrieve each slice. */
+function knowledgeMap(store) {
+    const entries = [];
+    for (const { domain, count } of store.hypothesisCountsByDomain()) {
+        entries.push({ label: `${count} rule${count === 1 ? "" : "s"} in ${domain}`, count, query: domain });
+    }
+    for (const { objectId, count } of store.factCountsByObject()) {
+        const object = store.getObject(objectId);
+        if (!object)
+            continue;
+        entries.push({ label: `${count} fact${count === 1 ? "" : "s"} about ${object.name}`, count, query: object.name });
+    }
+    return entries.sort((a, b) => b.count - a.count).slice(0, MAX_MAP_ENTRIES);
+}
 function collectHypotheses(store, request) {
     const byId = new Map();
     if (request.domain) {

package/dist/store/open.js

@@ -15,5 +15,9 @@ export function openRef(store, ref) {
             return store.getBrief(parsed.id);
         case "outcome":
             return store.getOutcome(parsed.id);
+        case "fact":
+            return store.getFact(parsed.id);
+        case "draft":
+            return store.getDraft(parsed.id);
     }
 }