@jbarket/loomai 0.5.0 → 0.6.0

package/dist/backends/proposals.js

@@ -43,7 +43,7 @@ function hasTable(db, table) {
 function openProposalsDb(contextDir) {
     const dbPath = resolveSqliteDbPath(contextDir);
     const db = new BetterSqlite3(dbPath);
-    db.pragma('busy_timeout = 0');
+    db.pragma('busy_timeout = 5000');
     if (!hasTable(db, 'proposals'))
         runMigrations(db, { strict: false });
     return db;

package/dist/backends/recorder-health.d.ts

@@ -0,0 +1,34 @@
+export interface RecorderHealth {
+    /** How many episode write-or-read attempts have failed in a row since lastSuccess. */
+    consecutiveFailures: number;
+    /** ISO timestamp of the first failure in the current streak, null when healthy. */
+    failingSince: string | null;
+    /** Scrubbed error string from the last failure (≤200 chars, no absolute paths). */
+    lastError: string | null;
+    /** ISO timestamp of the last successful episode write, null if never recorded. */
+    lastSuccess: string | null;
+}
+/** Number of consecutive failures before identity.ts injects the warning block. */
+export declare const FAILURE_THRESHOLD = 3;
+export declare function ledgerPath(contextDir: string): string;
+/** Read the health ledger synchronously. Returns HEALTHY when absent or unreadable. */
+export declare function readHealth(contextDir: string): RecorderHealth;
+/**
+ * Record a successful episode write. Resets the consecutive failure streak.
+ * The lastError field is preserved so diagnostics survive a single success.
+ */
+export declare function recordSuccess(contextDir: string): void;
+/**
+ * Record a failed episode write or tape-read attempt. Increments the streak.
+ * failingSince is set to the first failure's timestamp and never moved forward
+ * until a success resets the streak.
+ */
+export declare function recordFailure(contextDir: string, error: unknown): void;
+/**
+ * Build the warning block to inject into the boot context, or null when healthy.
+ *
+ * Returned string is a complete markdown section. Callers append it BELOW the
+ * rest of the identity payload — placed last so it is freshest in the model's
+ * working memory when its first reply fires.
+ */
+export declare function warningBlock(health: RecorderHealth): string | null;

package/dist/backends/recorder-health.js

@@ -0,0 +1,117 @@
+/**
+ * Recorder health ledger (t-562) — tracks consecutive episode-write failures.
+ *
+ * Written by:
+ *   - the episode write path (remember.ts) on success and failure
+ *   - the tape-read path (identity.ts catch) on failure
+ * Read by:
+ *   - identity.ts, which appends a warning block below the identity payload
+ *     when the recorder has failed FAILURE_THRESHOLD consecutive times.
+ *
+ * Inspired by observer-health.ts in claude-mem @ fd0ecf0. The ledger is a
+ * small JSON file in the context dir alongside memories.db — one per agent.
+ * All reads/writes are synchronous and never throw: the health ledger must
+ * never cascade into a deeper failure.
+ */
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+/** Number of consecutive failures before identity.ts injects the warning block. */
+export const FAILURE_THRESHOLD = 3;
+const LEDGER_FILENAME = 'recorder-health.json';
+const HEALTHY = {
+    consecutiveFailures: 0,
+    failingSince: null,
+    lastError: null,
+    lastSuccess: null,
+};
+export function ledgerPath(contextDir) {
+    return join(contextDir, LEDGER_FILENAME);
+}
+/** Read the health ledger synchronously. Returns HEALTHY when absent or unreadable. */
+export function readHealth(contextDir) {
+    try {
+        const path = ledgerPath(contextDir);
+        if (!existsSync(path))
+            return { ...HEALTHY };
+        const raw = readFileSync(path, 'utf-8');
+        const parsed = JSON.parse(raw);
+        return {
+            consecutiveFailures: typeof parsed.consecutiveFailures === 'number' ? parsed.consecutiveFailures : 0,
+            failingSince: typeof parsed.failingSince === 'string' ? parsed.failingSince : null,
+            lastError: typeof parsed.lastError === 'string' ? parsed.lastError : null,
+            lastSuccess: typeof parsed.lastSuccess === 'string' ? parsed.lastSuccess : null,
+        };
+    }
+    catch {
+        return { ...HEALTHY };
+    }
+}
+/** Scrub a raw error for the ledger: trim to 200 chars, redact absolute paths. */
+function scrubError(error) {
+    const raw = error instanceof Error ? error.message : String(error);
+    return raw.replace(/\/[^\s:,'"]+/g, '<path>').slice(0, 200);
+}
+/** Write the health ledger synchronously. Silently swallows write errors. */
+function writeHealth(contextDir, health) {
+    try {
+        writeFileSync(ledgerPath(contextDir), JSON.stringify(health, null, 2), 'utf-8');
+    }
+    catch {
+        // writing the health ledger must never block or throw
+    }
+}
+/**
+ * Record a successful episode write. Resets the consecutive failure streak.
+ * The lastError field is preserved so diagnostics survive a single success.
+ */
+export function recordSuccess(contextDir) {
+    const prev = readHealth(contextDir);
+    writeHealth(contextDir, {
+        consecutiveFailures: 0,
+        failingSince: null,
+        lastError: prev.lastError,
+        lastSuccess: new Date().toISOString(),
+    });
+}
+/**
+ * Record a failed episode write or tape-read attempt. Increments the streak.
+ * failingSince is set to the first failure's timestamp and never moved forward
+ * until a success resets the streak.
+ */
+export function recordFailure(contextDir, error) {
+    const prev = readHealth(contextDir);
+    const now = new Date().toISOString();
+    writeHealth(contextDir, {
+        consecutiveFailures: prev.consecutiveFailures + 1,
+        failingSince: prev.failingSince ?? now,
+        lastError: scrubError(error),
+        lastSuccess: prev.lastSuccess,
+    });
+}
+/**
+ * Build the warning block to inject into the boot context, or null when healthy.
+ *
+ * Returned string is a complete markdown section. Callers append it BELOW the
+ * rest of the identity payload — placed last so it is freshest in the model's
+ * working memory when its first reply fires.
+ */
+export function warningBlock(health) {
+    if (health.consecutiveFailures < FAILURE_THRESHOLD)
+        return null;
+    const since = health.failingSince ? ` since ${health.failingSince}` : '';
+    const errLine = health.lastError
+        ? `\n\nLast error: \`${health.lastError}\``
+        : '';
+    const successLine = health.lastSuccess
+        ? `\nLast success: ${health.lastSuccess}`
+        : '\nNo successful write on record.';
+    return (`# ⚠️ Recorder Health Warning\n\n` +
+        `The episode recorder has failed **${health.consecutiveFailures} consecutive` +
+        ` time${health.consecutiveFailures === 1 ? '' : 's'}**${since}.\n` +
+        `Episodes may not be reaching the tape — future bodies will wake without context.\n` +
+        successLine +
+        errLine +
+        `\n\n` +
+        `Check \`~/.local/state/art-episodes/hook.log\` and the loom episode store. ` +
+        `Call \`mcp__loom__remember\` with category \`episode\` to exercise the write path.`);
+}

package/dist/backends/salience.d.ts

@@ -10,6 +10,41 @@ export declare const DEFAULT_HALF_LIFE_DAYS = 30;
 export declare function temperature(lastTouchIso: string, category: string, nowMs: number): number;
 export type Tier = 'Hot' | 'Warm' | 'Cool';
 export declare function tierOf(temp: number): Tier;
+/**
+ * Feedback confidence model (t-338, parent t-325).
+ *
+ * Stolen from affaan-m/ECC's instinct design (confidence range 0.3-0.9,
+ * evidence-backed, +0.05 per confirming observation, -0.1 per contradicting
+ * one) — deliberately NOT their implementation. In ECC that arithmetic lives
+ * only as prose in a prompt (agents/observer.md) fed to an LLM; instinct-cli.py
+ * never computes, adjusts, or decays the number anywhere. Here the arithmetic
+ * is plain functions loom's own code calls from remember()/update() — never a
+ * prompt. Decay reuses `temperature()` above (same HALF_LIVES table) instead
+ * of a second, separate -0.02/week rule: one decay mechanism, not two.
+ */
+export declare const FEEDBACK_CONFIDENCE_MIN = 0.3;
+export declare const FEEDBACK_CONFIDENCE_MAX = 0.9;
+/** Starting value for a newly observed feedback memory, and the value decay relaxes toward. */
+export declare const FEEDBACK_CONFIDENCE_DEFAULT = 0.6;
+export declare const FEEDBACK_CONFIRM_DELTA = 0.05;
+export declare const FEEDBACK_CONTRADICT_DELTA = -0.1;
+export declare function clampConfidence(value: number): number;
+/** Apply one confirming or contradicting observation to a stored confidence value. */
+export declare function applyObservation(current: number, kind: 'confirm' | 'contradict'): number;
+/**
+ * Confidence after decay: relax the evidence-weighted raw value toward the
+ * neutral default as the memory cools, scaled by the SAME exponential
+ * half-life curve as salience (`temperature()`, same HALF_LIVES table) — a
+ * fully-decayed (temp→0) memory reads as neutral, a freshly-touched one
+ * (temp=1) reads as its raw evidence-backed value.
+ *
+ * `lastTouchIso` should be the last OBSERVATION time (the row's
+ * `observed_at`, falling back to `created`) — not `updated` and not
+ * `last_accessed`. A recall, an edit, an archive or a restore isn't
+ * evidence and mustn't reheat confidence; only a confirm/contradict (which
+ * goes through update() and stamps `observed_at`) is.
+ */
+export declare function decayedConfidence(rawConfidence: number, lastTouchIso: string, category: string, nowMs: number): number;
 /**
  * Recompute and STORE the salience scalar for every non-archived memory. Called
  * by the consolidation lane (stored + lane-refresh, not computed-on-read).
@@ -21,6 +56,8 @@ export interface DigestRow {
     category: string;
     content: string;
     salience: number;
+    /** Sourcing tier — null on legacy records without the column. */
+    sourcing: string | null;
 }
 export interface DigestOptions {
     /** Approximate token budget for the whole digest. */
@@ -43,6 +80,8 @@ export interface DigestAtom {
     content: string;
     salience: number;
     tier: Tier;
+    /** Sourcing tier — null on legacy records. */
+    sourcing: string | null;
 }
 /**
  * Structured salience digest for a UI widget: the hottest authored atoms,

package/dist/backends/salience.js

@@ -48,6 +48,49 @@ export function tierOf(temp) {
         return 'Warm';
     return 'Cool';
 }
+/**
+ * Feedback confidence model (t-338, parent t-325).
+ *
+ * Stolen from affaan-m/ECC's instinct design (confidence range 0.3-0.9,
+ * evidence-backed, +0.05 per confirming observation, -0.1 per contradicting
+ * one) — deliberately NOT their implementation. In ECC that arithmetic lives
+ * only as prose in a prompt (agents/observer.md) fed to an LLM; instinct-cli.py
+ * never computes, adjusts, or decays the number anywhere. Here the arithmetic
+ * is plain functions loom's own code calls from remember()/update() — never a
+ * prompt. Decay reuses `temperature()` above (same HALF_LIVES table) instead
+ * of a second, separate -0.02/week rule: one decay mechanism, not two.
+ */
+export const FEEDBACK_CONFIDENCE_MIN = 0.3;
+export const FEEDBACK_CONFIDENCE_MAX = 0.9;
+/** Starting value for a newly observed feedback memory, and the value decay relaxes toward. */
+export const FEEDBACK_CONFIDENCE_DEFAULT = 0.6;
+export const FEEDBACK_CONFIRM_DELTA = 0.05;
+export const FEEDBACK_CONTRADICT_DELTA = -0.1;
+export function clampConfidence(value) {
+    return Math.min(FEEDBACK_CONFIDENCE_MAX, Math.max(FEEDBACK_CONFIDENCE_MIN, value));
+}
+/** Apply one confirming or contradicting observation to a stored confidence value. */
+export function applyObservation(current, kind) {
+    const delta = kind === 'confirm' ? FEEDBACK_CONFIRM_DELTA : FEEDBACK_CONTRADICT_DELTA;
+    return clampConfidence(current + delta);
+}
+/**
+ * Confidence after decay: relax the evidence-weighted raw value toward the
+ * neutral default as the memory cools, scaled by the SAME exponential
+ * half-life curve as salience (`temperature()`, same HALF_LIVES table) — a
+ * fully-decayed (temp→0) memory reads as neutral, a freshly-touched one
+ * (temp=1) reads as its raw evidence-backed value.
+ *
+ * `lastTouchIso` should be the last OBSERVATION time (the row's
+ * `observed_at`, falling back to `created`) — not `updated` and not
+ * `last_accessed`. A recall, an edit, an archive or a restore isn't
+ * evidence and mustn't reheat confidence; only a confirm/contradict (which
+ * goes through update() and stamps `observed_at`) is.
+ */
+export function decayedConfidence(rawConfidence, lastTouchIso, category, nowMs) {
+    const temp = temperature(lastTouchIso, category, nowMs);
+    return FEEDBACK_CONFIDENCE_DEFAULT + (rawConfidence - FEEDBACK_CONFIDENCE_DEFAULT) * temp;
+}
 /** Most-recent-touch timestamp for a row (recall/write reheat through these). */
 function lastTouch(r) {
     return r.last_accessed ?? r.updated ?? r.created;
@@ -77,7 +120,10 @@ const DEFAULT_CHARS_PER_TOKEN = 4;
 function atomLine(r) {
     const body = r.content.replace(/\s+/g, ' ').trim();
     const clipped = body.length > 200 ? body.slice(0, 197).trimEnd() + '…' : body;
-    return `- **${r.title}** (${r.category}) — ${clipped}`;
+    // Show sourcing tag when present so readers calibrate confidence on inject.
+    // 'inferred' is the critical one: AI-generated reasoning, not ground truth.
+    const tag = r.sourcing ? `, ${r.sourcing}` : '';
+    return `- **${r.title}** (${r.category}${tag}) — ${clipped}`;
 }
 /**
  * Assemble the boot digest from already-recomputed salience: order hottest-first,
@@ -120,7 +166,7 @@ function openMemoriesDb(contextDir, readonly) {
     if (!existsSync(dbPath))
         return null;
     const db = new BetterSqlite3(dbPath, { readonly });
-    db.pragma('busy_timeout = 0');
+    db.pragma('busy_timeout = 5000');
     return db;
 }
 /** Lane entry point: recompute + store salience for a context. Returns count (or null if no store). */
@@ -153,7 +199,7 @@ export function digestData(contextDir, limit = 40) {
             return { atoms: [], total: 0 };
         const total = db.prepare('SELECT COUNT(*) AS n FROM memories WHERE archived = 0').get().n;
         const rows = db
-            .prepare('SELECT title, category, content, salience FROM memories WHERE archived = 0 AND category != ? ORDER BY salience DESC LIMIT ?')
+            .prepare('SELECT title, category, content, salience, sourcing FROM memories WHERE archived = 0 AND category != ? ORDER BY salience DESC LIMIT ?')
             .all(EPISODE_CATEGORY, limit);
         const atoms = rows.map((r) => ({ ...r, tier: tierOf(r.salience) }));
         return { atoms, total };
@@ -176,7 +222,9 @@ export function digestForContext(contextDir, opts = {}) {
             .prepare(
         // Episodes are the tape, not the digest: a fresh episode is always
         // salience 1.0 and would crowd Top of Mind with what just happened.
-        'SELECT title, category, content, salience FROM memories WHERE archived = 0 AND category != ? ORDER BY salience DESC LIMIT 100')
+        // sourcing: LEFT JOIN-style null-safe select — old stores without the
+        // column return NULL which DigestRow.sourcing accepts.
+        'SELECT title, category, content, salience, sourcing FROM memories WHERE archived = 0 AND category != ? ORDER BY salience DESC LIMIT 100')
             .all(EPISODE_CATEGORY);
         return assembleDigest(rows, opts);
     }

package/dist/backends/scope.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Memory scope discipline (t-337b, from the 2026-09-01 affaan-m/ECC teardown).
+ *
+ * loom has always carried a `project` tag on memories, but nothing stopped a
+ * preference learned while working on one project from surfacing while the
+ * agent is working on an unrelated one — the tag was metadata, not a filter.
+ *
+ * Every memory now has an *effective scope*: 'project' (only visible when
+ * recalling within the project it was written for) or 'global' (visible
+ * everywhere). ECC's instinct-promotion model is the source: default to the
+ * narrower scope, promote to global only on deliberate signal — here, an
+ * explicit `scope` at write time, since loom has no cross-project id to
+ * watch for repetition against.
+ *
+ * The category split below follows ECC's scope-decision table as far as
+ * loom's own category vocabulary lets it: 'user' (a fact about the person)
+ * and 'reference' (a pointer to an external system) are inherently
+ * cross-project, so they default global even when a project happens to be
+ * attached. Every other category defaults to 'project' — including 'self'
+ * and 'feedback', where ECC's real split lives (language/framework/style/
+ * error-handling feedback is project-specific; security/git/tool-workflow
+ * feedback is universal). Category alone can't tell those apart; that's a
+ * per-memory authoring call, made with `scope: 'global'` at write time, not
+ * a product decision this module can bake in — see t-337's comment thread
+ * for the open question on backfilling existing records.
+ */
+/** A memory's visibility: 'project' (scoped) or 'global' (everywhere). */
+export type MemoryScope = 'project' | 'global';
+/** Default scope for a category, 'project' for anything not in the table (safe default). */
+export declare function defaultScopeForCategory(category: string): MemoryScope;
+/** The subset of a memory record that scope decisions need. */
+export interface ScopableMemory {
+    category: string;
+    project?: string | null;
+    /** Explicit author override from write time, if any. Anything else is ignored (treated as unset). */
+    scope?: string | null;
+}
+/**
+ * The scope actually in force for a memory: the explicit override if one was
+ * set at write time, else the category default — but only when the memory
+ * is tagged to a project at all. A memory with no project has nothing to
+ * scope against and is global regardless of category.
+ */
+export declare function effectiveScope(mem: ScopableMemory): MemoryScope;
+/**
+ * Recall-time enforcement: is `mem` visible to a caller currently working
+ * within `recallProject`?
+ *
+ * `recallProject` null/undefined means the caller isn't scoping their recall
+ * to a project — there is nothing to enforce, so every memory stays visible
+ * (unchanged pre-t-337 behaviour: an unscoped recall searches everything).
+ * Once a project is given: memories tagged to that exact project are always
+ * visible, everything else is visible only if its effective scope is
+ * 'global'.
+ */
+export declare function isVisibleInProject(mem: ScopableMemory, recallProject: string | null | undefined): boolean;

package/dist/backends/scope.js

@@ -0,0 +1,75 @@
+/**
+ * Memory scope discipline (t-337b, from the 2026-09-01 affaan-m/ECC teardown).
+ *
+ * loom has always carried a `project` tag on memories, but nothing stopped a
+ * preference learned while working on one project from surfacing while the
+ * agent is working on an unrelated one — the tag was metadata, not a filter.
+ *
+ * Every memory now has an *effective scope*: 'project' (only visible when
+ * recalling within the project it was written for) or 'global' (visible
+ * everywhere). ECC's instinct-promotion model is the source: default to the
+ * narrower scope, promote to global only on deliberate signal — here, an
+ * explicit `scope` at write time, since loom has no cross-project id to
+ * watch for repetition against.
+ *
+ * The category split below follows ECC's scope-decision table as far as
+ * loom's own category vocabulary lets it: 'user' (a fact about the person)
+ * and 'reference' (a pointer to an external system) are inherently
+ * cross-project, so they default global even when a project happens to be
+ * attached. Every other category defaults to 'project' — including 'self'
+ * and 'feedback', where ECC's real split lives (language/framework/style/
+ * error-handling feedback is project-specific; security/git/tool-workflow
+ * feedback is universal). Category alone can't tell those apart; that's a
+ * per-memory authoring call, made with `scope: 'global'` at write time, not
+ * a product decision this module can bake in — see t-337's comment thread
+ * for the open question on backfilling existing records.
+ */
+/**
+ * Default scope by category, applied only when a memory carries a project
+ * tag. An untagged memory has nothing to scope against and is global by
+ * construction — see `effectiveScope`.
+ */
+const CATEGORY_DEFAULT_SCOPE = {
+    user: 'global',
+    reference: 'global',
+    project: 'project',
+    pursuit: 'project',
+    episode: 'project',
+    self: 'project',
+    feedback: 'project',
+};
+/** Default scope for a category, 'project' for anything not in the table (safe default). */
+export function defaultScopeForCategory(category) {
+    return CATEGORY_DEFAULT_SCOPE[category] ?? 'project';
+}
+/**
+ * The scope actually in force for a memory: the explicit override if one was
+ * set at write time, else the category default — but only when the memory
+ * is tagged to a project at all. A memory with no project has nothing to
+ * scope against and is global regardless of category.
+ */
+export function effectiveScope(mem) {
+    if (mem.scope === 'project' || mem.scope === 'global')
+        return mem.scope;
+    if (!mem.project)
+        return 'global';
+    return defaultScopeForCategory(mem.category);
+}
+/**
+ * Recall-time enforcement: is `mem` visible to a caller currently working
+ * within `recallProject`?
+ *
+ * `recallProject` null/undefined means the caller isn't scoping their recall
+ * to a project — there is nothing to enforce, so every memory stays visible
+ * (unchanged pre-t-337 behaviour: an unscoped recall searches everything).
+ * Once a project is given: memories tagged to that exact project are always
+ * visible, everything else is visible only if its effective scope is
+ * 'global'.
+ */
+export function isVisibleInProject(mem, recallProject) {
+    if (!recallProject)
+        return true;
+    if ((mem.project ?? null) === recallProject)
+        return true;
+    return effectiveScope(mem) === 'global';
+}

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

@@ -1,7 +1,13 @@
-import type { KnowledgeBackend, KnowledgePageInput, KnowledgeCitationInput, KnowledgePageWithCitations, KnowledgeQueryInput, KnowledgeWriteResult, KnowledgeArchiveInput, KnowledgeArchiveResult, KnowledgeRestoreInput, KnowledgeRestoreResult, KnowledgeSupersededInput, KnowledgeSupersededResult, KnowledgeMoveInput, KnowledgeMoveResult, KnowledgeMergeInput, KnowledgeMergeResult, KnowledgePurgeInput, KnowledgePurgeResult, KnowledgeVerifyInput, KnowledgeVerifyResult, KnowledgeRevision, KnowledgeRevisionMeta, KnowledgeRevisionRestoreInput, KnowledgeRevisionRestoreResult } from './types.js';
+import type { KnowledgeBackend, KnowledgePageInput, KnowledgeCitationInput, KnowledgePageWithCitations, KnowledgeQueryInput, KnowledgeWriteResult, KnowledgeArchiveInput, KnowledgeArchiveResult, KnowledgeRestoreInput, KnowledgeRestoreResult, KnowledgeSupersededInput, KnowledgeSupersededResult, KnowledgeMoveInput, KnowledgeMoveResult, KnowledgeMergeInput, KnowledgeMergeResult, KnowledgePurgeInput, KnowledgePurgeResult, KnowledgeVerifyInput, KnowledgeVerifyResult, KnowledgeVerificationRecord, KnowledgeRevision, KnowledgeRevisionMeta, KnowledgeRevisionRestoreInput, KnowledgeRevisionRestoreResult, KnowledgeAccessStat } from './types.js';
 export interface SqliteKnowledgeConfig {
     /** Absolute path to the knowledge SQLite database file */
     dbPath: string;
+    /**
+     * SQLite busy_timeout in ms — how long to retry a locked write before
+     * surfacing SQLITE_BUSY. Defaults to 5000; pass a small value in tests
+     * that exercise the SQLITE_BUSY path so they don't wait the full window.
+     */
+    busyTimeoutMs?: number;
 }
 export declare class SqliteKnowledgeBackend implements KnowledgeBackend {
     private readonly config;
@@ -10,6 +16,7 @@ export declare class SqliteKnowledgeBackend implements KnowledgeBackend {
     writePage(input: KnowledgePageInput): Promise<KnowledgeWriteResult>;
     getPage(slug: string, opts?: {
         stampAccess?: boolean;
+        identity?: string;
     }): Promise<KnowledgePageWithCitations | null>;
     listPages(input?: KnowledgeQueryInput): Promise<KnowledgePageWithCitations[]>;
     queryPages(input: KnowledgeQueryInput): Promise<KnowledgePageWithCitations[]>;
@@ -20,18 +27,31 @@ export declare class SqliteKnowledgeBackend implements KnowledgeBackend {
     mergePages(input: KnowledgeMergeInput): Promise<KnowledgeMergeResult>;
     purgePages(input: KnowledgePurgeInput): Promise<KnowledgePurgeResult>;
     verifyPages(input: KnowledgeVerifyInput): Promise<KnowledgeVerifyResult>;
+    getVerifications(slug: string): Promise<KnowledgeVerificationRecord[]>;
     listRevisions(slug: string): Promise<KnowledgeRevisionMeta[]>;
     getRevision(revisionId: number): Promise<KnowledgeRevision | null>;
     restoreRevision(input: KnowledgeRevisionRestoreInput): Promise<KnowledgeRevisionRestoreResult>;
     /**
-     * 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.
      */
     private snapshotRevision;
     addCitations(slug: string, citations: KnowledgeCitationInput[]): Promise<number>;
+    getAccessStats(pageId: number): Promise<KnowledgeAccessStat[]>;
     close(): void;
+    /**
+     * 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.
+     */
+    private recordAccess;
     private ensureOpen;
     private fetchCitationsForPage;
     private initSchema;
 }
+export declare function deriveSlaClass(anchor: string | null | undefined, domain: string): 'device' | 'software' | 'default';