@jbarket/loomai 0.5.0 → 0.6.0

package/dist/backends/sqlite-knowledge.js

@@ -11,6 +11,8 @@ import { mkdirSync } from 'node:fs';
 import { dirname } from 'node:path';
 import BetterSqlite3 from 'better-sqlite3';
 import { retryWrite } from './retry.js';
+/** Identity attributed to a stamped access when the caller doesn't pass one. */
+const UNKNOWN_IDENTITY = 'unknown';
 /** Hard size caps — enforced at write boundary (design §A3). */
 const MAX_PAGE_BODY_LENGTH = 64 * 1024; // 64 KB
 const MAX_CITATION_EXCERPT_LENGTH = 4096; // 4 KB
@@ -25,10 +27,9 @@ export class SqliteKnowledgeBackend {
         // Open in constructor for schema init; caller closes after use.
         this.db = new BetterSqlite3(config.dbPath);
         this.db.pragma('journal_mode = WAL');
-        // Single-writer (c-loom-strictness §single-writer): fail fast on a second
-        // concurrent writer (SQLITE_BUSY) instead of blocking for the 5s default —
-        // see sqlite-vec.ts for the rationale. The knowledge wing shares the policy.
-        this.db.pragma('busy_timeout = 0');
+        // busy_timeout: concurrent sleeves retry brief write-lock windows rather
+        // than failing immediately — see sqlite-vec.ts for the full rationale.
+        this.db.pragma(`busy_timeout = ${config.busyTimeoutMs ?? 5000}`);
         this.db.pragma('user_version = 1');
         this.initSchema();
     }
@@ -38,63 +39,92 @@ export class SqliteKnowledgeBackend {
             enforcePageBodyCap(input.body);
             const db = this.ensureOpen();
             const timestamp = new Date().toISOString();
-            const existing = db.prepare('SELECT id, uuid, title, body FROM pages WHERE slug = ?').get(input.slug);
-            let pageId;
-            let uuid;
-            let title;
-            let sourcing;
-            let appliedMode;
-            if (existing) {
-                uuid = existing.uuid;
-                // Title and domain follow the write — the page is addressed by slug,
-                // so a differing title/domain on upsert is an intentional revision.
-                title = input.title;
-                sourcing = input.sourcing ?? 'sourced';
-                pageId = existing.id;
-                appliedMode = input.bodyMode ?? 'replace';
-                const newBody = appliedMode === 'append'
-                    ? `${existing.body}\n\n${input.body}`
-                    : input.body;
-                enforcePageBodyCap(newBody);
-                // Replace-writes destroy the stored body — snapshot it first so the
-                // page is recoverable (the 2026-06-01 verify run stomped 13 bodies
-                // with no recovery path other than transcript archaeology).
-                if (appliedMode === 'replace' && newBody !== existing.body) {
-                    retryWrite(() => this.snapshotRevision(db, pageId, input.slug, existing.body, 'write-replace', timestamp));
+            // Title and domain follow the write — the page is addressed by slug,
+            // so a differing title/domain on upsert is an intentional revision.
+            const title = input.title;
+            const sourcing = input.sourcing ?? 'sourced';
+            // Set inside the transaction, read after it commits. Every one of these
+            // is derived from the existing-page read, so all of them are re-derived
+            // on a SQLITE_BUSY retry rather than carried over from the losing attempt.
+            let uuid = '';
+            let appliedMode = 'create';
+            let pageId = 0;
+            // Validate all citations before opening the transaction.
+            if (input.citations && input.citations.length > 0) {
+                for (const cit of input.citations) {
+                    enforceExcerptCap(cit.excerpt);
                 }
-                // verified_at is a verification stamp, not a write stamp: an update
-                // only moves it when the writer explicitly claims verification.
-                // (Creation still stamps write time — the page was just synthesized
-                // against its sources.)
-                // created_by / version are preserved across upserts when omitted.
-                retryWrite(() => db.prepare(`UPDATE pages SET title = ?, domain = ?, body = ?, sourcing = ?, verified_at = COALESCE(?, verified_at), freshness_anchor = COALESCE(?, freshness_anchor), created_by = COALESCE(?, created_by), version = COALESCE(?, version), updated = ? WHERE id = ?`).run(title, input.domain, newBody, sourcing, input.verified_at ?? null, input.freshness_anchor ?? null, input.created_by ?? null, input.version ?? null, timestamp, pageId));
-            }
-            else {
-                uuid = randomUUID();
-                title = input.title;
-                sourcing = input.sourcing ?? 'sourced';
-                appliedMode = 'create';
-                const result = retryWrite(() => db.prepare(`INSERT INTO pages (uuid, slug, title, domain, body, sourcing, provenance, verified_at, freshness_anchor, created_by, version, created, updated)
-           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(uuid, input.slug, title, input.domain, input.body, sourcing, input.provenance ?? null, input.verified_at ?? timestamp, input.freshness_anchor ?? null, input.created_by ?? null, input.version ?? null, timestamp, timestamp));
-                pageId = Number(result.lastInsertRowid);
             }
             let citationsAdded = 0;
             let citationsDeduped = 0;
-            if (input.citations && input.citations.length > 0) {
-                for (const cit of input.citations) {
-                    enforceExcerptCap(cit.excerpt);
+            // Pre-prepare citation statements — compiled once, safe to reuse on retry.
+            // Exact-duplicate guard: re-sending a page's citations on upsert must not
+            // multiply them. A citation is a duplicate when claim, kind, locator, and
+            // excerpt all match an existing row on the same page.
+            const dupCheck = db.prepare(`SELECT 1 FROM citations
+         WHERE page_id = ? AND claim = ? AND source_kind = ?
+           AND COALESCE(source_locator, '') = COALESCE(?, '')
+           AND excerpt = ?`);
+            const insertCit = db.prepare(`INSERT INTO citations (page_id, claim, source_kind, source_locator, excerpt, retrieved_at, created)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`);
+            // ── Single transaction: read + snapshot + page write + citations ─────────
+            // All sub-operations must commit atomically — a crash between any two
+            // leaves a partial state: a page with no citations, or a snapshot with no
+            // corresponding page update. Every other mutating method uses db.transaction;
+            // writePage — the hottest path — now does too (t-329).
+            //
+            // The existing-page read is INSIDE the span, and the span is IMMEDIATE:
+            // writePage is state-dependent (mode, body, uuid, and the snapshot's
+            // pre-image all follow from what it read), so an atomic write over a read
+            // taken outside the lock protects nothing. A second process committing in
+            // that window used to be silently overwritten — an append dropped the
+            // contribution it never saw, and a replace snapshotted a body that was no
+            // longer the one it displaced, losing it with no revision to recover from.
+            // BEGIN IMMEDIATE takes the write lock before the read, so the read/write
+            // sequence is serialized: the loser is told SQLITE_BUSY and retries the
+            // whole thing — re-reading — instead of writing over what it missed.
+            // (Mark, 2026-09-06, reviewing #92.)
+            //
+            // Counter variables (citationsAdded, citationsDeduped) are reset at the top
+            // of the callback so a SQLITE_BUSY retry never double-counts.
+            const tx = db.transaction(() => {
+                citationsAdded = 0;
+                citationsDeduped = 0;
+                const existing = db.prepare('SELECT id, uuid, title, body, freshness_anchor FROM pages WHERE slug = ?').get(input.slug);
+                uuid = existing?.uuid ?? randomUUID();
+                pageId = existing?.id ?? 0;
+                appliedMode = existing ? (input.bodyMode ?? 'replace') : 'create';
+                const newBody = (existing && appliedMode === 'append')
+                    ? `${existing.body}\n\n${input.body}`
+                    : input.body;
+                if (existing)
+                    enforcePageBodyCap(newBody);
+                // Derive sla_class from the final anchor + domain; caller may override.
+                const finalAnchor = input.freshness_anchor ?? existing?.freshness_anchor ?? null;
+                const slaClass = input.sla_class ?? deriveSlaClass(finalAnchor, input.domain);
+                if (existing) {
+                    // Replace-writes destroy the stored body — snapshot it first so the
+                    // page is recoverable (the 2026-06-01 verify run stomped 13 bodies
+                    // with no recovery path other than transcript archaeology).
+                    if (appliedMode === 'replace' && newBody !== existing.body) {
+                        this.snapshotRevision(db, pageId, input.slug, existing.body, 'write-replace', timestamp, input.actor ?? null);
+                    }
+                    // verified_at is a verification stamp, not a write stamp: an update
+                    // only moves it when the writer explicitly claims verification.
+                    // (Creation still stamps write time — the page was just synthesized
+                    // against its sources.)
+                    // created_by / version are preserved across upserts when omitted.
+                    // author is deliberately absent from this UPDATE — it is the
+                    // identity that wrote v1 and is never changed by a later upsert.
+                    // sla_class is always re-derived from the final anchor + domain.
+                    db.prepare(`UPDATE pages SET title = ?, domain = ?, body = ?, sourcing = ?, verified_at = COALESCE(?, verified_at), freshness_anchor = COALESCE(?, freshness_anchor), created_by = COALESCE(?, created_by), version = COALESCE(?, version), sla_class = ?, updated = ? WHERE id = ?`).run(title, input.domain, newBody, sourcing, input.verified_at ?? null, input.freshness_anchor ?? null, input.created_by ?? null, input.version ?? null, slaClass, timestamp, pageId);
                 }
-                // Exact-duplicate guard: re-sending a page's citations on upsert must
-                // not multiply them. A citation is a duplicate when claim, kind,
-                // locator, and excerpt all match an existing row on the same page
-                // (same identity tuple mergePages dedupes on).
-                const dupCheck = db.prepare(`SELECT 1 FROM citations
-           WHERE page_id = ? AND claim = ? AND source_kind = ?
-             AND COALESCE(source_locator, '') = COALESCE(?, '')
-             AND excerpt = ?`);
-                const insertCit = db.prepare(`INSERT INTO citations (page_id, claim, source_kind, source_locator, excerpt, retrieved_at, created)
-           VALUES (?, ?, ?, ?, ?, ?, ?)`);
-                const tx = db.transaction(() => {
+                else {
+                    const result = db.prepare(`INSERT INTO pages (uuid, slug, title, domain, body, sourcing, provenance, verified_at, freshness_anchor, sla_class, created_by, version, author, created, updated)
+             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(uuid, input.slug, title, input.domain, newBody, sourcing, input.provenance ?? null, input.verified_at ?? timestamp, input.freshness_anchor ?? null, slaClass, input.created_by ?? null, input.version ?? null, input.actor ?? null, timestamp, timestamp);
+                    pageId = Number(result.lastInsertRowid);
+                }
+                if (input.citations && input.citations.length > 0) {
                     for (const cit of input.citations) {
                         const dup = dupCheck.get(pageId, cit.claim, cit.source_kind, cit.source_locator ?? null, cit.excerpt);
                         if (dup) {
@@ -104,9 +134,9 @@ export class SqliteKnowledgeBackend {
                         insertCit.run(pageId, cit.claim, cit.source_kind, cit.source_locator ?? null, cit.excerpt, timestamp, timestamp);
                         citationsAdded++;
                     }
-                });
-                retryWrite(() => tx());
-            }
+                }
+            });
+            retryWrite(() => tx.immediate());
             return Promise.resolve({
                 uuid,
                 slug: input.slug,
@@ -129,7 +159,7 @@ export class SqliteKnowledgeBackend {
                 return Promise.resolve(null);
             if (opts?.stampAccess) {
                 const now = new Date().toISOString();
-                retryWrite(() => db.prepare('UPDATE pages SET last_accessed = ?, hit_count = hit_count + 1 WHERE id = ?').run(now, page.id));
+                this.recordAccess(db, [page.id], opts.identity ?? UNKNOWN_IDENTITY, now);
                 page.last_accessed = now;
                 page.hit_count += 1;
             }
@@ -210,12 +240,7 @@ export class SqliteKnowledgeBackend {
             // appearing in a listing is not a read.
             if (rows.length > 0 && input.stampAccess !== false) {
                 const now = new Date().toISOString();
-                const stamp = db.prepare('UPDATE pages SET last_accessed = ?, hit_count = hit_count + 1 WHERE id = ?');
-                const tx = db.transaction((ids) => {
-                    for (const id of ids)
-                        stamp.run(now, id);
-                });
-                retryWrite(() => tx(rows.map((r) => r.id)));
+                this.recordAccess(db, rows.map((r) => r.id), input.identity ?? UNKNOWN_IDENTITY, now);
             }
             return Promise.resolve(rows.map((page) => ({
                 ...page,
@@ -280,7 +305,7 @@ export class SqliteKnowledgeBackend {
                 // Record the supersession.
                 db.prepare("INSERT INTO supersessions (old_slug, new_slug, note, created) VALUES (?, ?, ?, ?)").run(input.old_slug, input.new_slug, input.note ?? null, timestamp);
             });
-            retryWrite(() => tx());
+            retryWrite(() => tx.immediate());
             return Promise.resolve({
                 old_slug: input.old_slug,
                 new_slug: input.new_slug,
@@ -312,7 +337,7 @@ export class SqliteKnowledgeBackend {
                         pages.push({ slug: p.slug, old_domain: p.domain, new_domain: newDomain });
                     }
                 });
-                retryWrite(() => tx());
+                retryWrite(() => tx.immediate());
                 return Promise.resolve({ moved: pages.length, pages, pointers_written: 0 });
             }
             // ── Batch by explicit slug list (re-domain only) ──────────────────────────
@@ -331,7 +356,7 @@ export class SqliteKnowledgeBackend {
                         pages.push({ slug, old_domain: page.domain, new_domain: input.new_domain });
                     }
                 });
-                retryWrite(() => tx());
+                retryWrite(() => tx.immediate());
                 return Promise.resolve({ moved: pages.length, pages, pointers_written: 0 });
             }
             // ── Single-page mode ──────────────────────────────────────────────────────
@@ -373,7 +398,7 @@ export class SqliteKnowledgeBackend {
                     db.prepare('UPDATE pages SET domain = ?, updated = ? WHERE slug = ?').run(input.new_domain, timestamp, currentSlug);
                 }
             });
-            retryWrite(() => tx());
+            retryWrite(() => tx.immediate());
             return Promise.resolve({
                 moved: 1,
                 pages: [{
@@ -395,7 +420,7 @@ export class SqliteKnowledgeBackend {
             if (!input.source_slugs || input.source_slugs.length === 0) {
                 return Promise.reject(new Error('mergePages: source_slugs must not be empty'));
             }
-            const targetRow = db.prepare('SELECT id, body, verified_at, freshness_anchor FROM pages WHERE slug = ?').get(input.target_slug);
+            const targetRow = db.prepare('SELECT id, body, verified_at, freshness_anchor, domain FROM pages WHERE slug = ?').get(input.target_slug);
             if (!targetRow) {
                 return Promise.reject(new Error(`mergePages: target page not found: ${input.target_slug}`));
             }
@@ -455,8 +480,9 @@ export class SqliteKnowledgeBackend {
                     db.prepare('UPDATE citations SET page_id = ? WHERE page_id = ?').run(targetRow.id, source.id);
                     citationsMoved += after;
                 }
-                // Update target: verified_at, freshness_anchor, updated.
-                db.prepare('UPDATE pages SET verified_at = ?, freshness_anchor = ?, updated = ? WHERE id = ?').run(maxVerifiedAt, freshnessAnchor ?? null, timestamp, targetRow.id);
+                // Update target: verified_at, freshness_anchor, sla_class, updated.
+                const mergedSlaClass = deriveSlaClass(freshnessAnchor ?? null, targetRow.domain);
+                db.prepare('UPDATE pages SET verified_at = ?, freshness_anchor = ?, sla_class = ?, updated = ? WHERE id = ?').run(maxVerifiedAt, freshnessAnchor ?? null, mergedSlaClass, timestamp, targetRow.id);
                 // Optionally append loser bodies to target body.
                 if (input.append_loser_bodies) {
                     let appendedBody = targetRow.body;
@@ -482,7 +508,7 @@ export class SqliteKnowledgeBackend {
                     }
                 }
             });
-            retryWrite(() => tx());
+            retryWrite(() => tx.immediate());
             return Promise.resolve({
                 target_slug: input.target_slug,
                 sources_merged: sourceRows.length,
@@ -524,7 +550,7 @@ export class SqliteKnowledgeBackend {
                     db.prepare('DELETE FROM pages WHERE id = ?').run(row.id);
                 }
             });
-            retryWrite(() => tx());
+            retryWrite(() => tx.immediate());
             return Promise.resolve({ purged: input.slugs.length, slugs: input.slugs });
         }
         catch (e) {
@@ -550,19 +576,29 @@ export class SqliteKnowledgeBackend {
             }
             const rows = [];
             for (const slug of slugs) {
-                const page = db.prepare('SELECT id, status, body FROM pages WHERE slug = ?').get(slug);
+                const page = db.prepare('SELECT id, status, body, freshness_anchor, domain FROM pages WHERE slug = ?').get(slug);
                 if (!page) {
                     return Promise.reject(new Error(`verifyPages: page not found: ${slug}`));
                 }
                 if (page.status === 'archived') {
                     return Promise.reject(new Error(`verifyPages: page '${slug}' is archived — restore it before verifying`));
                 }
-                rows.push({ id: page.id, slug, body: page.body });
-            }
+                rows.push({ id: page.id, slug, body: page.body, freshness_anchor: page.freshness_anchor, domain: page.domain });
+            }
+            const outcome = input.outcome ?? 'confirmed';
+            const citationChecked = input.citation_checked ? 1 : 0;
+            const insertVerification = db.prepare('INSERT INTO verifications (page_id, verifier, verified_at, outcome, citation_checked) VALUES (?, ?, ?, ?, ?)');
+            // verified_at means "last SUCCESSFUL verification" — it drives the
+            // stale-first queue and SLA checks. A 'stale' outcome is a failed
+            // verification: it goes in the audit trail but must not renew the
+            // stamp, or a known-wrong page drops to the back of the queue.
+            const stamped = outcome !== 'stale';
             let noted = false;
             const tx = db.transaction(() => {
                 for (const row of rows) {
-                    db.prepare('UPDATE pages SET verified_at = ?, freshness_anchor = COALESCE(?, freshness_anchor) WHERE id = ?').run(verifiedAt, input.freshness_anchor ?? null, row.id);
+                    const finalAnchor = input.freshness_anchor ?? row.freshness_anchor;
+                    const slaClass = deriveSlaClass(finalAnchor, row.domain);
+                    db.prepare('UPDATE pages SET verified_at = CASE WHEN ? THEN ? ELSE verified_at END, freshness_anchor = COALESCE(?, freshness_anchor), sla_class = ? WHERE id = ?').run(stamped ? 1 : 0, verifiedAt, input.freshness_anchor ?? null, slaClass, row.id);
                     if (input.note) {
                         const dateLabel = verifiedAt.slice(0, 10);
                         const newBody = `${row.body}\n\n## Verification — ${dateLabel}\n\n${input.note}`;
@@ -572,13 +608,18 @@ export class SqliteKnowledgeBackend {
                         db.prepare('UPDATE pages SET body = ?, updated = ? WHERE id = ?').run(newBody, timestamp, row.id);
                         noted = true;
                     }
+                    // The attributed audit trail (t-675) — recorded for every outcome,
+                    // additive to the verified_at stamp above (which stays for
+                    // freshness sort/SLA and only moves on success).
+                    insertVerification.run(row.id, input.verifier ?? null, verifiedAt, outcome, citationChecked);
                 }
             });
-            retryWrite(() => tx());
+            retryWrite(() => tx.immediate());
             return Promise.resolve({
                 verified: rows.length,
                 slugs: rows.map((r) => r.slug),
                 verified_at: verifiedAt,
+                stamped,
                 noted,
             });
         }
@@ -586,6 +627,21 @@ export class SqliteKnowledgeBackend {
             return Promise.reject(e);
         }
     }
+    getVerifications(slug) {
+        try {
+            const db = this.ensureOpen();
+            const page = db.prepare('SELECT id FROM pages WHERE slug = ?').get(slug);
+            if (!page) {
+                return Promise.reject(new Error(`getVerifications: page not found: ${slug}`));
+            }
+            const rows = db.prepare(`SELECT id, page_id, verifier, verified_at, outcome, citation_checked
+         FROM verifications WHERE page_id = ? ORDER BY id DESC`).all(page.id);
+            return Promise.resolve(rows.map((r) => ({ ...r, citation_checked: r.citation_checked !== 0 })));
+        }
+        catch (e) {
+            return Promise.reject(e);
+        }
+    }
     listRevisions(slug) {
         try {
             const db = this.ensureOpen();
@@ -593,7 +649,7 @@ export class SqliteKnowledgeBackend {
             if (!page) {
                 return Promise.reject(new Error(`listRevisions: page not found: ${slug}`));
             }
-            const rows = db.prepare(`SELECT id, page_id, slug, op, replaced_at, LENGTH(body) AS body_length
+            const rows = db.prepare(`SELECT id, page_id, slug, op, replaced_at, actor, LENGTH(body) AS body_length
          FROM page_revisions WHERE page_id = ? ORDER BY id DESC`).all(page.id);
             return Promise.resolve(rows);
         }
@@ -604,7 +660,7 @@ export class SqliteKnowledgeBackend {
     getRevision(revisionId) {
         try {
             const db = this.ensureOpen();
-            const row = db.prepare('SELECT id, page_id, slug, op, replaced_at, body FROM page_revisions WHERE id = ?').get(revisionId);
+            const row = db.prepare('SELECT id, page_id, slug, op, replaced_at, actor, body FROM page_revisions WHERE id = ?').get(revisionId);
             return Promise.resolve(row ?? null);
         }
         catch (e) {
@@ -630,10 +686,10 @@ export class SqliteKnowledgeBackend {
             const tx = db.transaction(() => {
                 // The body being displaced is itself preserved — a restore must
                 // never be the second irreversible overwrite in the story.
-                snapshotId = this.snapshotRevision(db, page.id, input.slug, page.body, 'history-restore', timestamp);
+                snapshotId = this.snapshotRevision(db, page.id, input.slug, page.body, 'history-restore', timestamp, input.actor ?? null);
                 db.prepare('UPDATE pages SET body = ?, updated = ? WHERE id = ?').run(revision.body, timestamp, page.id);
             });
-            retryWrite(() => tx());
+            retryWrite(() => tx.immediate());
             return Promise.resolve({
                 slug: input.slug,
                 revision_id: input.revision_id,
@@ -646,12 +702,13 @@ export class SqliteKnowledgeBackend {
         }
     }
     /**
-     * Insert a body snapshot and prune beyond the per-page cap. Caller owns the
-     * transaction when called from restoreRevision; called bare from writePage.
-     * Each statement is wrapped in retryWrite so both call sites are safe.
+     * Insert a body snapshot and prune beyond the per-page cap. Always called
+     * inside a transaction owned by the caller (writePage or restoreRevision).
+     * The inner retryWrite calls run bare statements — safe inside an outer
+     * transaction; the outer transaction is the atomicity boundary.
      */
-    snapshotRevision(db, pageId, slug, body, op, timestamp) {
-        const result = retryWrite(() => db.prepare('INSERT INTO page_revisions (page_id, slug, body, op, replaced_at) VALUES (?, ?, ?, ?, ?)').run(pageId, slug, body, op, timestamp));
+    snapshotRevision(db, pageId, slug, body, op, timestamp, actor = null) {
+        const result = retryWrite(() => db.prepare('INSERT INTO page_revisions (page_id, slug, body, op, replaced_at, actor) VALUES (?, ?, ?, ?, ?, ?)').run(pageId, slug, body, op, timestamp, actor));
         retryWrite(() => db.prepare(`DELETE FROM page_revisions WHERE page_id = ? AND id NOT IN (
            SELECT id FROM page_revisions WHERE page_id = ? ORDER BY id DESC LIMIT ?
          )`).run(pageId, pageId, MAX_REVISIONS_PER_PAGE));
@@ -675,13 +732,24 @@ export class SqliteKnowledgeBackend {
                     added++;
                 }
             });
-            retryWrite(() => tx());
+            retryWrite(() => tx.immediate());
             return Promise.resolve(added);
         }
         catch (e) {
             return Promise.reject(e);
         }
     }
+    getAccessStats(pageId) {
+        try {
+            const db = this.ensureOpen();
+            const rows = db.prepare(`SELECT identity, hit_count, last_accessed FROM knowledge_access
+         WHERE page_id = ? ORDER BY last_accessed DESC`).all(pageId);
+            return Promise.resolve(rows);
+        }
+        catch (e) {
+            return Promise.reject(e);
+        }
+    }
     close() {
         if (this.db) {
             this.db.close();
@@ -689,6 +757,29 @@ export class SqliteKnowledgeBackend {
         }
     }
     // ── Internals ──
+    /**
+     * Stamp a real read on each page id: bump the shared pages.hit_count /
+     * last_accessed aggregate (unchanged legacy behavior — this is what
+     * knowledge_maintain's cold/expansion ranking reads) AND upsert the
+     * per-identity row in knowledge_access (t-677 attribution). Both updates
+     * happen in one transaction so a crash between them can't desync the
+     * aggregate from the per-reader breakdown.
+     */
+    recordAccess(db, pageIds, identity, now) {
+        const bumpPage = db.prepare('UPDATE pages SET last_accessed = ?, hit_count = hit_count + 1 WHERE id = ?');
+        const upsertAccess = db.prepare(`INSERT INTO knowledge_access (page_id, identity, hit_count, last_accessed)
+       VALUES (?, ?, 1, ?)
+       ON CONFLICT(page_id, identity) DO UPDATE SET
+         hit_count = hit_count + 1,
+         last_accessed = excluded.last_accessed`);
+        const tx = db.transaction((ids) => {
+            for (const id of ids) {
+                bumpPage.run(now, id);
+                upsertAccess.run(id, identity, now);
+            }
+        });
+        retryWrite(() => tx(pageIds));
+    }
     ensureOpen() {
         if (!this.db) {
             throw new Error('KnowledgeBackend is already closed');
@@ -715,7 +806,8 @@ export class SqliteKnowledgeBackend {
         last_accessed TEXT,
         hit_count     INTEGER NOT NULL DEFAULT 0,
         verified_at   TEXT,
-        freshness_anchor TEXT
+        freshness_anchor TEXT,
+        sla_class     TEXT NOT NULL DEFAULT 'default'
       )`,
             `CREATE INDEX IF NOT EXISTS idx_pages_domain ON pages(domain)`,
             `CREATE INDEX IF NOT EXISTS idx_pages_slug ON pages(slug)`,
@@ -749,6 +841,29 @@ export class SqliteKnowledgeBackend {
         replaced_at TEXT NOT NULL
       )`,
             `CREATE INDEX IF NOT EXISTS idx_page_revisions_page ON page_revisions(page_id)`,
+            // Actor attribution (t-675): who verified a page, when, and what they
+            // found. Additive to pages.verified_at (which stays the fast single-
+            // column freshness stamp everything else queries/sorts on) — this
+            // table is the attributed audit trail underneath it.
+            `CREATE TABLE IF NOT EXISTS verifications (
+        id               INTEGER PRIMARY KEY AUTOINCREMENT,
+        page_id          INTEGER NOT NULL REFERENCES pages(id) ON DELETE CASCADE,
+        verifier         TEXT,
+        verified_at      TEXT NOT NULL,
+        outcome          TEXT NOT NULL DEFAULT 'confirmed',
+        citation_checked INTEGER NOT NULL DEFAULT 0
+      )`,
+            `CREATE INDEX IF NOT EXISTS idx_verifications_page ON verifications(page_id)`,
+            // Per-identity read attribution (t-677) — additive to pages.hit_count/
+            // last_accessed, never a replacement. See getAccessStats/recordAccess.
+            `CREATE TABLE IF NOT EXISTS knowledge_access (
+        page_id       INTEGER NOT NULL REFERENCES pages(id) ON DELETE CASCADE,
+        identity      TEXT NOT NULL,
+        hit_count     INTEGER NOT NULL DEFAULT 0,
+        last_accessed TEXT,
+        PRIMARY KEY (page_id, identity)
+      )`,
+            `CREATE INDEX IF NOT EXISTS idx_knowledge_access_page ON knowledge_access(page_id)`,
         ];
         for (const sql of statements) {
             this.db.prepare(sql).run();
@@ -771,9 +886,56 @@ export class SqliteKnowledgeBackend {
         if (!pageCols.includes('version')) {
             this.db.prepare('ALTER TABLE pages ADD COLUMN version TEXT').run();
         }
+        // sla_class: machine-readable freshness SLA class (t-434, 2026-09-25).
+        // DEFAULT 'default' covers all rows created before this migration.
+        // Backfill then upgrades rows whose anchor or domain implies a non-default class.
+        if (!pageCols.includes('sla_class')) {
+            this.db.prepare("ALTER TABLE pages ADD COLUMN sla_class TEXT NOT NULL DEFAULT 'default'").run();
+            // Backfill: re-derive for every existing row.
+            const rows = this.db.prepare("SELECT id, freshness_anchor, domain FROM pages").all();
+            const update = this.db.prepare("UPDATE pages SET sla_class = ? WHERE id = ?");
+            const backfill = this.db.transaction(() => {
+                for (const row of rows) {
+                    const klass = deriveSlaClass(row.freshness_anchor, row.domain);
+                    if (klass !== 'default') {
+                        update.run(klass, row.id);
+                    }
+                }
+            });
+            backfill();
+        }
+        // Actor attribution (t-675): identity that wrote v1 of the page. Set
+        // only at creation (writePage) — never backfilled, since there is no
+        // way to recover who actually wrote pre-existing rows.
+        if (!pageCols.includes('author')) {
+            this.db.prepare('ALTER TABLE pages ADD COLUMN author TEXT').run();
+        }
+        const revisionCols = this.db.prepare('PRAGMA table_info(page_revisions)').all().map((c) => c.name);
+        if (!revisionCols.includes('actor')) {
+            this.db.prepare('ALTER TABLE page_revisions ADD COLUMN actor TEXT').run();
+        }
     }
 }
 // ── Helpers ──
+/**
+ * SLA class derivation — deterministic, no model required (t-434).
+ *
+ * Priority:
+ *   1. version-anchored: freshness_anchor matches /v?\d+\.\d+/ → 'software' (14d)
+ *   2. device-domain: domain starts with a known device-domain prefix → 'device' (7d)
+ *   3. else → 'default' (30d)
+ *
+ * Callers may override with KnowledgePageInput.sla_class.
+ */
+const DEVICE_DOMAIN_PREFIXES = ['music/gear', 'monitor/hardware'];
+const RE_SLA_VERSION = /v?\d+\.\d+/i;
+export function deriveSlaClass(anchor, domain) {
+    if (anchor && RE_SLA_VERSION.test(anchor))
+        return 'software';
+    if (DEVICE_DOMAIN_PREFIXES.some((p) => domain === p || domain.startsWith(`${p}/`)))
+        return 'device';
+    return 'default';
+}
 function enforcePageBodyCap(body) {
     if (body.length > MAX_PAGE_BODY_LENGTH) {
         throw new Error(`Page body exceeds hard cap of ${MAX_PAGE_BODY_LENGTH} characters ` +

package/dist/backends/sqlite-vec.d.ts

@@ -1,5 +1,5 @@
 import { type Database } from 'better-sqlite3';
-import type { MemoryBackend, MemoryInput, MemoryRef, RecallInput, MemoryMatch, ForgetInput, ForgetResult, UpdateInput, UpdateResult, PruneResult, ListInput, MemoryEntry, EmbeddingProvider, FindSimilarInput, AuditOptions, AuditReport, ArchiveInput, ArchiveResult, RestoreInput, RestoreResult, RecallObservation, MemoryRevisionMeta, MemoryRevision, MemoryRevisionRestoreInput, MemoryRevisionRestoreResult, MemorySupersededInput, MemorySupersededResult } from './types.js';
+import type { MemoryBackend, MemoryInput, MemoryRef, RecallInput, MemoryMatch, ForgetInput, ForgetResult, UpdateInput, UpdateResult, PruneResult, ListInput, MemoryEntry, EmbeddingProvider, FindSimilarInput, AuditOptions, AuditReport, ArchiveInput, ArchiveResult, RestoreInput, RestoreResult, RecallObservation, MemoryRevisionMeta, MemoryRevision, MemoryRevisionRestoreInput, MemoryRevisionRestoreResult, MemorySupersededInput, MemorySupersededResult, MemoryMergeInput, MemoryMergeResult } from './types.js';
 export interface SqliteVecConfig {
     /** Absolute path to the SQLite database file */
     dbPath: string;
@@ -32,8 +32,24 @@ export declare class SqliteVecBackend implements MemoryBackend {
     getRevision(revisionId: number): Promise<MemoryRevision | null>;
     restoreRevision(input: MemoryRevisionRestoreInput): Promise<MemoryRevisionRestoreResult>;
     supersede(input: MemorySupersededInput): Promise<MemorySupersededResult>;
+    mergeMemories(input: MemoryMergeInput): Promise<MemoryMergeResult>;
     close(): void;
     getDatabase(): Database;
+    /**
+     * A transaction that reheats the active row holding `uniqKey` (times_seen
+     * + 1, updated = timestamp) and returns its ref, or returns undefined if no
+     * active row holds it. Run it with .immediate() on its own, or call it
+     * inside another transaction (better-sqlite3 nests it as a savepoint).
+     */
+    private reheatTx;
+    /**
+     * The dedup key a row should hold for the given body, or NULL when another
+     * ACTIVE row already holds that key — the existing holder keeps it, same
+     * policy as the migration backfill (rebuildUniqKeys). Call inside the
+     * write transaction that changes the body, so the check and the write see
+     * the same state.
+     */
+    private claimableUniq;
     /**
      * Insert a content snapshot into memory_revisions and prune beyond the per-memory
      * cap. Mirrors the knowledge wing's snapshotRevision() in sqlite-knowledge.ts.
@@ -60,5 +76,20 @@ export declare class SqliteVecBackend implements MemoryBackend {
     /** Stored embeddings for a set of memory ids (point lookups; pools are small). */
     private loadVectors;
     private initSchema;
+    /**
+     * Hard-delete rows by id. Every call is journaled to memory_deletions first
+     * (t-436) — this is the ONLY path that permanently destroys a memory, so it
+     * is the one place that must record what it destroyed. The journal table is
+     * standalone (keyed by ref, no FK to memories) so it survives the delete it
+     * describes.
+     */
     private deleteById;
+    /**
+     * The journal-then-delete transaction behind deleteById. Callers already
+     * inside a transaction (mergeMemories with hard_delete_losers) invoke it
+     * directly; better-sqlite3 nests it as a savepoint.
+     */
+    private deleteByIdTx;
 }
+/** Float32Array view of a Buffer; copies only when alignment forces it. */
+export declare function bufToF32(buf: Buffer): Float32Array;