useathena 0.1.0 → 0.2.0

package/dist/store/store.js

@@ -55,6 +55,19 @@ export class AthenaStore {
       CREATE TABLE IF NOT EXISTS briefs (
         id TEXT PRIMARY KEY, compiled_at TEXT NOT NULL, data TEXT NOT NULL
       );
+      CREATE TABLE IF NOT EXISTS facts (
+        id TEXT PRIMARY KEY, object_id TEXT NOT NULL, domain TEXT NOT NULL,
+        last_confirmed_at TEXT NOT NULL, data TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_facts_object ON facts(object_id);
+      CREATE TABLE IF NOT EXISTS drafts (
+        id TEXT PRIMARY KEY, brief_id TEXT NOT NULL, domain TEXT NOT NULL,
+        recorded_at TEXT NOT NULL, matched_outcome_id TEXT, data TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_drafts_unmatched ON drafts(domain, recorded_at) WHERE matched_outcome_id IS NULL;
+      CREATE TABLE IF NOT EXISTS meta (
+        key TEXT PRIMARY KEY, value TEXT NOT NULL
+      );
       CREATE VIRTUAL TABLE IF NOT EXISTS search_index USING fts5(ref, lane, text);
     `);
     }
@@ -97,6 +110,13 @@ export class AthenaStore {
       ORDER BY observed_at DESC LIMIT ${filter.limit ?? 200}`;
         return this.db.prepare(sql).all(...params).map((rowData));
     }
+    /** Instances observed strictly after `since` (all instances when omitted). */
+    countInstancesSince(since) {
+        const row = since
+            ? this.db.prepare("SELECT COUNT(*) AS n FROM instances WHERE observed_at > ?").get(since)
+            : this.db.prepare("SELECT COUNT(*) AS n FROM instances").get();
+        return row.n;
+    }
     // --- hypotheses (revisable views over evidence) ---
     saveHypothesis(hypothesis) {
         if (hypothesis.supportingInstanceIds.length === 0) {
@@ -170,6 +190,77 @@ export class AthenaStore {
             .all(objectId, objectId)
             .map((rowData));
     }
+    // --- facts (revisable views over evidence, like hypotheses) ---
+    saveFact(fact) {
+        if (fact.supportingInstanceIds.length === 0) {
+            throw new Error(`fact ${fact.id} has no supporting instances — everything cites`);
+        }
+        const object = this.getObject(fact.objectId);
+        if (!object) {
+            throw new Error(`fact ${fact.id} references unknown object ${fact.objectId}`);
+        }
+        this.upsert("facts", "INSERT INTO facts (id, object_id, domain, last_confirmed_at, data) VALUES (?, ?, ?, ?, ?) " +
+            "ON CONFLICT(id) DO UPDATE SET object_id = excluded.object_id, domain = excluded.domain, " +
+            "last_confirmed_at = excluded.last_confirmed_at, data = excluded.data", [fact.id, fact.objectId, fact.domain, fact.lastConfirmedAt, JSON.stringify(fact)]);
+        this.index(`athena://fact/${fact.id}`, "fact", [fact.statement, fact.domain, object.name, object.aliases.join(" ")].join("\n"));
+    }
+    getFact(id) {
+        return this.getData("facts", id);
+    }
+    listFacts(filter = {}) {
+        const where = [];
+        const params = [];
+        if (filter.objectId) {
+            where.push("object_id = ?");
+            params.push(filter.objectId);
+        }
+        if (filter.domain) {
+            where.push("domain = ?");
+            params.push(filter.domain);
+        }
+        const sql = `SELECT data FROM facts ${where.length ? `WHERE ${where.join(" AND ")}` : ""}
+      ORDER BY last_confirmed_at DESC LIMIT ${filter.limit ?? 200}`;
+        return this.db.prepare(sql).all(...params).map((rowData));
+    }
+    /** Per-entity fact counts for the brief's knowledge map. */
+    factCountsByObject() {
+        return this.db
+            .prepare("SELECT object_id AS objectId, COUNT(*) AS count FROM facts GROUP BY object_id ORDER BY count DESC")
+            .all();
+    }
+    /** Per-domain servable-rule counts for the brief's knowledge map. */
+    hypothesisCountsByDomain() {
+        return this.db
+            .prepare("SELECT domain, COUNT(*) AS count FROM hypotheses WHERE status IN ('validated','active') GROUP BY domain ORDER BY count DESC")
+            .all();
+    }
+    // --- agent drafts (outputs awaiting an observed outcome) ---
+    saveDraft(draft) {
+        this.upsert("drafts", "INSERT INTO drafts (id, brief_id, domain, recorded_at, matched_outcome_id, data) VALUES (?, ?, ?, ?, ?, ?) " +
+            "ON CONFLICT(id) DO UPDATE SET matched_outcome_id = excluded.matched_outcome_id, data = excluded.data", [draft.id, draft.briefId, draft.domain, draft.recordedAt, draft.matchedOutcomeId ?? null, JSON.stringify(draft)]);
+    }
+    getDraft(id) {
+        return this.getData("drafts", id);
+    }
+    listUnmatchedDrafts(filter = {}) {
+        const where = ["matched_outcome_id IS NULL"];
+        const params = [];
+        if (filter.domain) {
+            where.push("domain = ?");
+            params.push(filter.domain);
+        }
+        if (filter.since) {
+            where.push("recorded_at >= ?");
+            params.push(filter.since);
+        }
+        return this.db
+            .prepare(`SELECT data FROM drafts WHERE ${where.join(" AND ")} ORDER BY recorded_at DESC LIMIT 100`)
+            .all(...params)
+            .map((rowData));
+    }
+    listDrafts() {
+        return this.db.prepare("SELECT data FROM drafts ORDER BY recorded_at DESC LIMIT 500").all().map((rowData));
+    }
     // --- serving layer ---
     saveBrief(brief) {
         this.upsert("briefs", "INSERT INTO briefs (id, compiled_at, data) VALUES (?, ?, ?) ON CONFLICT(id) DO UPDATE SET data = excluded.data", [brief.id, brief.compiledAt, JSON.stringify(brief)]);
@@ -190,6 +281,22 @@ export class AthenaStore {
             : this.db.prepare("SELECT data FROM outcomes ORDER BY recorded_at DESC").all();
         return rows.map((rowData));
     }
+    listBriefs(limit = 500) {
+        return this.db
+            .prepare(`SELECT data FROM briefs ORDER BY compiled_at DESC LIMIT ${limit}`)
+            .all()
+            .map((rowData));
+    }
+    // --- meta (operational state: last learn run, cooldowns) ---
+    getMeta(key) {
+        const row = this.db.prepare("SELECT value FROM meta WHERE key = ?").get(key);
+        return row ? row.value : undefined;
+    }
+    setMeta(key, value) {
+        this.db
+            .prepare("INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value")
+            .run(key, value);
+    }
     // --- stats ---
     counts() {
         const byColumn = (table, column) => {
@@ -205,6 +312,8 @@ export class AthenaStore {
             sources: total("sources"),
             outcomes: total("outcomes"),
             briefs: total("briefs"),
+            facts: total("facts"),
+            unmatchedDrafts: this.db.prepare("SELECT COUNT(*) AS n FROM drafts WHERE matched_outcome_id IS NULL").get().n,
         };
     }
     // --- search (lexical lane) ---

package/docs/schema.md

@@ -29,7 +29,8 @@ Mission framing: athena captures **tacit knowledge** from real work so agents be
 ## IDs
 
 Prefixed ULIDs: `ins_` instance, `hyp_` hypothesis, `obj_` object, `src_` source,
-`out_` outcome, `brf_` brief, `act_` actor, `sen_` sensor. Sortable by creation time.
+`out_` outcome, `brf_` brief, `act_` actor, `sen_` sensor, `fct_` fact, `drf_` agent
+draft. Sortable by creation time.
 
 ---
 
@@ -268,6 +269,30 @@ type ObjectRelation = {
 };
 ```
 
+### Fact — the explicit counterpart of a hypothesis
+
+A declarative, entity-grounded statement extracted from evidence ("Acme's renewal
+is in September" vs the tacit "be formal with Acme execs"). Facts are never entered
+manually and agents cannot write them: the engine extracts them during learn, and
+`materializeFacts` is the only write path — it resolves or creates the entity and
+dedupes near-identical statements into a confirmation instead of a duplicate.
+
+```ts
+type Fact = {
+  id: FactId;                  // fct_…
+  objectId: ObjectId;          // every fact is about exactly one entity
+  statement: string;
+  domain: string;              // domain of the evidence cluster it came from
+  supportingInstanceIds: InstanceId[];  // facts cite, like everything else
+  confidence: number;
+  firstSeenAt: string;
+  lastConfirmedAt: string;     // bumped when new evidence restates the fact
+  staleAfter: string;          // unconfirmed past this → no longer served
+  supersededById?: FactId;
+  visibility: Exclude<Visibility, "user_private_raw">;
+};
+```
+
 Markdown pages (per object, per domain) are **projections** generated from sources +
 hypotheses + relations. Stored in `.athena/pages/` for humans and git; rebuilt, never edited
 as truth.
@@ -284,6 +309,7 @@ Compact payload + dereferenceable pointers. Persisted for audit and outcome link
 type Brief = {
   id: BriefId;
   task: string;                // as the agent stated it
+  domain?: string;             // when given — drafts registered against this brief match captures in it
   compiledAt: string;
 
   rules: {
@@ -305,6 +331,12 @@ type Brief = {
 
   readiness: "act" | "act_with_caveats" | "inspect_first" | "ask_human";
   refs: Ref[];                 // additional evidence worth opening, ranked
+
+  map?: {                      // coordinates into everything else athena knows:
+    label: string;             //   "12 rules in email.outreach", "4 facts about Acme"
+    count: number;
+    query: string;             //   pass to athena_search — agents pull, never flooded
+  }[];
 };
 
 type Ref = string;             // athena://hypothesis/hyp_x | athena://instance/ins_x
@@ -332,14 +364,39 @@ type AgentOutcome = {
 This closes the loop: **brief → action → outcome → instance → hypothesis update**, and
 gives us the north-star metric directly: correction rate per served brief, over time.
 
+### AgentDraft — outcomes that record themselves
+
+The artifact an agent produced from a brief, registered (`athena_record type=output`)
+so athena can detect the outcome without anyone reporting: when a sensor later
+captures what the human actually did with it, the instance matches back —
+approval → `uncorrected`, correction → `corrected` with the instance as the
+counterexample.
+
+```ts
+type AgentDraft = {
+  id: DraftId;                 // drf_…
+  briefId: BriefId;
+  content: string;             // the artifact, verbatim
+  contentHash: string;
+  mediaType: string;
+  domain: string;
+  recordedAt: string;
+  matchedOutcomeId?: OutcomeId; // set once resolved (matched or expired)
+};
+```
+
+Matching is conservative — same domain, within 72h, captured before-text within
+15% of the draft — because a false match would corrupt trust; a miss costs nothing.
+Drafts that outlive the window expire to `result: "unknown"` (rule trust untouched).
+
 ### MCP surface (4 tools, not 19)
 
 | Tool | Does |
 |---|---|
 | `athena_brief(task, domain?)` | compile + persist a Brief |
 | `athena_open(ref)` | dereference any `athena://` ref |
-| `athena_record(event)` | SensorEvent in: outcome, correction, manual note, rule *proposal* |
-| `athena_search(query, lane?)` | direct lexical+semantic search when the agent wants to explore |
+| `athena_record(event)` | outcome report, draft registration (`type=output`), or SensorEvent: correction, manual note, rule *proposal* |
+| `athena_search(query, lane?)` | direct search (lanes: instance, hypothesis, source, fact) when the agent wants to explore |
 
 No durable-mutation tools. `athena_record` proposals enter the review queue like any sensor event.
 
@@ -348,9 +405,11 @@ No durable-mutation tools. `athena_record` proposals enter the review queue like
 ## 5. Storage mapping
 
 SQLite, one file per workspace (`.athena/athena.db`):
-- `instances`, `hypotheses`, `sources`, `objects`, `relations`, `outcomes`, `briefs`
-  — JSON column + extracted indexed columns (id, kind, domain, status, observedAt, visibility).
-- FTS5 over instance summaries/diffs, hypothesis rules, source content.
+- `instances`, `hypotheses`, `sources`, `objects`, `relations`, `outcomes`, `briefs`,
+  `facts`, `drafts` — JSON column + extracted indexed columns (id, kind, domain, status,
+  observedAt, visibility).
+- `meta` — key/value operational state (last learn run, auto-learn cooldown).
+- FTS5 over instance summaries/diffs, hypothesis rules, source content, fact statements.
 - `sqlite-vec` over situation/rule/source embeddings (optional lane — everything works without it).
 - WAL mode; single-writer per file is acceptable for local; server mode serializes per workspace.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "useathena",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "athena captures tacit knowledge from real work so agents become truly autonomous and reliable.",
   "license": "UNLICENSED",
   "repository": {