@astragenie/astramemory-local 0.7.2

package/dist/memory-tool/adapter.js

@@ -0,0 +1,269 @@
+/**
+ * Anthropic memory-tool backend adapter (ADR-007 Wave 4a, migration-map 4a).
+ *
+ * Anthropic's client-side memory tool (docs.claude.com memory-tool) expects
+ * the HARNESS to execute file-like commands (view/create/str_replace/insert/
+ * delete/rename) against a virtual `/memories` filesystem. This module maps
+ * those commands onto astramem memories so any Claude app using the memory
+ * tool can be backed by the daemon — see docs/memory-tool-adapter.md for the
+ * full command-mapping table and limitations.
+ *
+ * Virtual filesystem shape:
+ *   /memories                    -> directory listing of "<type>.md" files
+ *   /memories/<type>.md          -> markdown bullet list of current valid
+ *                                    memories of that type, one line per
+ *                                    memory: "- [<id>] <text>"
+ *   /memories/<type>.md/<id>     -> addresses a single memory (delete only)
+ *
+ * `<type>` must be one of the MemoryType enum values (decision, fact,
+ * lesson, command, todo, note, event). For create/insert, an unrecognized
+ * type slug in the path falls back to 'note' rather than erroring — the
+ * model may invent filenames the harness has never seen before.
+ *
+ * Design rulings (binding, see dispatch prompt for Wave 4a):
+ *   - create/insert: file_text/insert_text becomes ONE memory's text (no
+ *     bullet parsing — parsing markdown bullets back into memories is lossy
+ *     and was explicitly rejected). Redacted via redactIfEnabled, inserted
+ *     via MemoryRepo.insertWithCreateEvent (mirrors POST /remember), but
+ *     WITHOUT embedding metadata — embedding is not required synchronously,
+ *     the memory is FTS-searchable immediately and vec-indexed on reembed.
+ *   - str_replace: finds the single valid memory of that type whose text
+ *     contains old_str, then supersedes it (insert new + MemoryEventRepo
+ *     .supersede) rather than mutating the row in place — every memory
+ *     write goes through the ADR-002 event log.
+ *   - delete: whole-file (`/memories/<type>.md`) erases every current
+ *     memory of that type; per-id (`/memories/<type>.md/<id>`) erases just
+ *     that one. Both use MemoryEventRepo.erase (hard delete + tombstone
+ *     event, ADR-006 W5) — never a soft invalidate.
+ *   - rename: NOT supported v1 (a "rename" would mean changing an atom's
+ *     type, which isn't modeled) — always returns an error result.
+ *   - Unknown paths/commands never throw; they return { error }.
+ */
+import { createHash } from 'node:crypto';
+import { MemoryRepo } from '../storage/memories.js';
+import { MemoryEventRepo, MemoryNotFoundError, MemoryConflictError } from '../storage/memory-events.js';
+import { redactIfEnabled } from '../redact/index.js';
+import { recordRedactionEvents } from '../storage/redaction-log.js';
+const MEMORY_TYPES = ['decision', 'fact', 'lesson', 'command', 'todo', 'note', 'event'];
+function isMemoryType(x) {
+    return MEMORY_TYPES.includes(x);
+}
+/** Parses a virtual path under /memories. Returns null for anything outside that tree. */
+function parseMemoriesPath(path) {
+    if (path === '/memories' || path === '/memories/')
+        return { kind: 'root' };
+    const m = /^\/memories\/([^/]+)\.md(?:\/(.+))?$/.exec(path);
+    if (!m || !m[1])
+        return null;
+    return m[2] ? { kind: 'type-file-item', typeSlug: m[1], itemId: m[2] } : { kind: 'type-file', typeSlug: m[1] };
+}
+function listValidMemoriesByType(db, type) {
+    return db
+        .prepare(`SELECT id, type, text, created_at FROM memories WHERE type = ? AND valid_to IS NULL ORDER BY created_at ASC`)
+        .all(type);
+}
+function listTypesWithValidMemories(db) {
+    const rows = db.prepare(`SELECT DISTINCT type FROM memories WHERE valid_to IS NULL ORDER BY type ASC`).all();
+    return rows.map(r => r.type);
+}
+function renderTypeFile(rows) {
+    return rows.map(r => `- [${r.id}] ${r.text}`).join('\n');
+}
+/** Applies text-editor-style view_range (1-indexed, inclusive; end === -1 means to EOF). */
+function applyViewRange(content, range) {
+    if (!range)
+        return { content };
+    const lines = content.split('\n');
+    const [start, endRaw] = range;
+    const end = endRaw === -1 ? lines.length : endRaw;
+    if (!Number.isInteger(start) || !Number.isInteger(end) || start < 1 || start > lines.length || end < start) {
+        return { error: `invalid view_range: [${start}, ${endRaw}] for a ${lines.length}-line file` };
+    }
+    return { content: lines.slice(start - 1, end).join('\n') };
+}
+function handleView(db, cmd) {
+    const parsed = parseMemoriesPath(cmd.path);
+    if (!parsed)
+        return { error: `no such file: ${cmd.path}` };
+    if (parsed.kind === 'root') {
+        const listing = listTypesWithValidMemories(db)
+            .map(t => `${t}.md`)
+            .join('\n');
+        return applyViewRange(listing, cmd.view_range);
+    }
+    if (parsed.kind === 'type-file') {
+        if (!isMemoryType(parsed.typeSlug))
+            return { error: `no such file: ${cmd.path}` };
+        const rows = listValidMemoriesByType(db, parsed.typeSlug);
+        return applyViewRange(renderTypeFile(rows), cmd.view_range);
+    }
+    // type-file-item: viewing a single memory by id is not part of the v1
+    // contract (view is documented only for the root and whole type files).
+    return { error: `view does not support a single memory id — view /memories/${parsed.typeSlug}.md instead` };
+}
+function handleCreateOrInsert(db, config, cmd) {
+    const parsed = parseMemoriesPath(cmd.path);
+    if (!parsed || parsed.kind !== 'type-file') {
+        return { error: `invalid path for ${cmd.command}: ${cmd.path}` };
+    }
+    const rawText = cmd.command === 'create' ? cmd.file_text : cmd.insert_text;
+    if (typeof rawText !== 'string' || rawText.length === 0) {
+        const field = cmd.command === 'create' ? 'file_text' : 'insert_text';
+        return { error: `missing ${field} for ${cmd.command}` };
+    }
+    const type = isMemoryType(parsed.typeSlug) ? parsed.typeSlug : 'note';
+    // Same choke point as POST /remember (SEC-3/5): redact before persistence.
+    const { text, events: redactionEvents } = redactIfEnabled(rawText, config);
+    recordRedactionEvents(db, redactionEvents, null);
+    const hash = createHash('sha256').update(text).digest('hex').slice(0, 32);
+    const repo = new MemoryRepo(db);
+    const events = new MemoryEventRepo(db);
+    const { id } = repo.insertWithCreateEvent({
+        type,
+        text,
+        normalized_text: text.toLowerCase(),
+        repo: null,
+        project: null,
+        branch: null,
+        agent: null,
+        session_id: null,
+        hash,
+        source_hash: null,
+        importance: 0.5,
+        confidence: 0.5,
+        // Deliberately no embedding metadata (KF-B/Wave-4a ruling): FTS-searchable
+        // immediately; vec index catches up on reembed rather than blocking here.
+        embedding_provider: null,
+        embedding_model: null,
+        embedding_dim: null,
+    }, events);
+    return { content: `created memory ${id} in ${type}.md` };
+}
+function handleStrReplace(db, config, cmd) {
+    const parsed = parseMemoriesPath(cmd.path);
+    if (!parsed || parsed.kind !== 'type-file') {
+        return { error: `invalid path for str_replace: ${cmd.path}` };
+    }
+    if (!isMemoryType(parsed.typeSlug))
+        return { error: `no such file: ${cmd.path}` };
+    if (typeof cmd.old_str !== 'string' || cmd.old_str.length === 0)
+        return { error: 'missing old_str' };
+    if (typeof cmd.new_str !== 'string')
+        return { error: 'missing new_str' };
+    const type = parsed.typeSlug;
+    const rows = listValidMemoriesByType(db, type);
+    const matches = rows.filter(r => r.text.includes(cmd.old_str));
+    if (matches.length === 0)
+        return { error: `old_str not found in ${cmd.path}` };
+    if (matches.length > 1) {
+        return { error: `old_str matches ${matches.length} memories in ${cmd.path} — must match exactly one` };
+    }
+    const old = matches[0];
+    const occurrences = old.text.split(cmd.old_str).length - 1;
+    if (occurrences !== 1) {
+        return { error: `old_str must occur exactly once within the matched memory (found ${occurrences})` };
+    }
+    const replacedText = old.text.replace(cmd.old_str, cmd.new_str);
+    const { text, events: redactionEvents } = redactIfEnabled(replacedText, config);
+    recordRedactionEvents(db, redactionEvents, null);
+    const hash = createHash('sha256').update(text).digest('hex').slice(0, 32);
+    const repo = new MemoryRepo(db);
+    const events = new MemoryEventRepo(db);
+    const { id: newId } = repo.insertWithCreateEvent({
+        type,
+        text,
+        normalized_text: text.toLowerCase(),
+        repo: null,
+        project: null,
+        branch: null,
+        agent: null,
+        session_id: null,
+        hash,
+        source_hash: null,
+        importance: 0.5,
+        confidence: 0.5,
+        embedding_provider: null,
+        embedding_model: null,
+        embedding_dim: null,
+    }, events);
+    if (newId !== old.id) {
+        try {
+            events.supersede(old.id, newId);
+        }
+        catch (err) {
+            if (err instanceof MemoryNotFoundError || err instanceof MemoryConflictError) {
+                return { error: err.message };
+            }
+            throw err;
+        }
+    }
+    return { content: `superseded memory ${old.id} with ${newId} in ${type}.md` };
+}
+function handleDelete(db, cmd) {
+    const parsed = parseMemoriesPath(cmd.path);
+    if (!parsed)
+        return { error: `no such file: ${cmd.path}` };
+    const events = new MemoryEventRepo(db);
+    if (parsed.kind === 'type-file-item') {
+        if (!isMemoryType(parsed.typeSlug))
+            return { error: `no such file: ${cmd.path}` };
+        const memory = new MemoryRepo(db).get(parsed.itemId);
+        if (!memory || memory.type !== parsed.typeSlug || memory.valid_to !== null) {
+            return { error: `no such memory: ${cmd.path}` };
+        }
+        try {
+            events.erase(parsed.itemId);
+        }
+        catch (err) {
+            if (err instanceof MemoryNotFoundError)
+                return { error: err.message };
+            throw err;
+        }
+        return { content: `erased memory ${parsed.itemId}` };
+    }
+    if (parsed.kind === 'type-file') {
+        if (!isMemoryType(parsed.typeSlug))
+            return { error: `no such file: ${cmd.path}` };
+        const rows = listValidMemoriesByType(db, parsed.typeSlug);
+        for (const row of rows) {
+            events.erase(row.id);
+        }
+        return { content: `erased ${rows.length} memories from ${parsed.typeSlug}.md` };
+    }
+    return { error: `cannot delete: ${cmd.path}` };
+}
+function handleRename() {
+    return {
+        error: 'rename is not supported by the memory-tool adapter (v1) — a rename would mean changing a memory\'s type, ' +
+            'which is not modeled; delete and re-create under the new type instead',
+    };
+}
+/**
+ * Maps one Anthropic memory-tool command onto astramem memories. Never
+ * throws — every failure path (bad path, unknown command, storage error)
+ * comes back as { error } so the caller can relay it straight into a
+ * tool_result without its own try/catch.
+ */
+export function handleMemoryToolCommand(db, config, cmd) {
+    try {
+        switch (cmd.command) {
+            case 'view':
+                return handleView(db, cmd);
+            case 'create':
+            case 'insert':
+                return handleCreateOrInsert(db, config, cmd);
+            case 'str_replace':
+                return handleStrReplace(db, config, cmd);
+            case 'delete':
+                return handleDelete(db, cmd);
+            case 'rename':
+                return handleRename();
+            default:
+                return { error: `unknown command: ${String(cmd.command)}` };
+        }
+    }
+    catch (err) {
+        return { error: err instanceof Error ? err.message : String(err) };
+    }
+}
+//# sourceMappingURL=adapter.js.map

package/dist/memory-tool/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../src/memory-tool/adapter.ts"],"names":[],"mappings":"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"}

package/dist/pipeline/errors.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Typed pipeline errors for failure classification.
+ *
+ * Throw TransientError for recoverable conditions (network failures, rate limits,
+ * server-side 5xx) where retrying has a meaningful chance of success.
+ *
+ * Throw DeterministicError for conditions that will not self-heal (bad schema,
+ * parse failure, 4xx auth/validation) where retrying wastes LLM budget.
+ */
+export declare class TransientError extends Error {
+    readonly cause?: unknown | undefined;
+    readonly kind: "transient";
+    constructor(message: string, cause?: unknown | undefined);
+    static is(err: unknown): err is TransientError;
+}
+export declare class DeterministicError extends Error {
+    readonly cause?: unknown | undefined;
+    readonly kind: "deterministic";
+    constructor(message: string, cause?: unknown | undefined);
+    static is(err: unknown): err is DeterministicError;
+}

package/dist/pipeline/errors.js

@@ -0,0 +1,34 @@
+/**
+ * Typed pipeline errors for failure classification.
+ *
+ * Throw TransientError for recoverable conditions (network failures, rate limits,
+ * server-side 5xx) where retrying has a meaningful chance of success.
+ *
+ * Throw DeterministicError for conditions that will not self-heal (bad schema,
+ * parse failure, 4xx auth/validation) where retrying wastes LLM budget.
+ */
+export class TransientError extends Error {
+    cause;
+    kind = 'transient';
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'TransientError';
+    }
+    static is(err) {
+        return err instanceof Error && err.kind === 'transient';
+    }
+}
+export class DeterministicError extends Error {
+    cause;
+    kind = 'deterministic';
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'DeterministicError';
+    }
+    static is(err) {
+        return err instanceof Error && err.kind === 'deterministic';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/pipeline/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/pipeline/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,OAAO,cAAe,SAAQ,KAAK;IAGM;IAFpC,IAAI,GAAG,WAAoB,CAAC;IAErC,YAAY,OAAe,EAAkB,KAAe;QAC1D,KAAK,CAAC,OAAO,CAAC,CAAC;QAD4B,UAAK,GAAL,KAAK,CAAU;QAE1D,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;IAED,MAAM,CAAC,EAAE,CAAC,GAAY;QACpB,OAAO,GAAG,YAAY,KAAK,IAAK,GAA0B,CAAC,IAAI,KAAK,WAAW,CAAC;IAClF,CAAC;CACF;AAED,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAGE;IAFpC,IAAI,GAAG,eAAwB,CAAC;IAEzC,YAAY,OAAe,EAAkB,KAAe;QAC1D,KAAK,CAAC,OAAO,CAAC,CAAC;QAD4B,UAAK,GAAL,KAAK,CAAU;QAE1D,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;IAED,MAAM,CAAC,EAAE,CAAC,GAAY;QACpB,OAAO,GAAG,YAAY,KAAK,IAAK,GAA0B,CAAC,IAAI,KAAK,eAAe,CAAC;IACtF,CAAC;CACF"}

package/dist/pipeline/failure-classifier.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Failure classifier for the worker retry router.
+ *
+ * Distinguishes transient failures (retry with backoff) from deterministic
+ * failures (immediate poison — no further LLM budget spent).
+ *
+ * Priority:
+ *   1. Explicit typed errors (TransientError / DeterministicError) — authoritative.
+ *   2. Message heuristics — cover unwrapped errors from providers / stages.
+ *   3. Default: transient (conservative — retry rather than silently drop).
+ */
+export type FailureKind = 'transient' | 'deterministic';
+export declare function classifyError(err: unknown): FailureKind;

package/dist/pipeline/failure-classifier.js

@@ -0,0 +1,72 @@
+/**
+ * Failure classifier for the worker retry router.
+ *
+ * Distinguishes transient failures (retry with backoff) from deterministic
+ * failures (immediate poison — no further LLM budget spent).
+ *
+ * Priority:
+ *   1. Explicit typed errors (TransientError / DeterministicError) — authoritative.
+ *   2. Message heuristics — cover unwrapped errors from providers / stages.
+ *   3. Default: transient (conservative — retry rather than silently drop).
+ */
+import { TransientError, DeterministicError } from './errors.js';
+/** Heuristic substrings that classify a message as transient. */
+const TRANSIENT_PATTERNS = [
+    'econnrefused',
+    'etimedout',
+    'econnreset',
+    'enetunreach',
+    'ehostunreach',
+    'epipe',
+    'rate limit',
+    'rate-limit',
+    'ratelimit',
+    '429',
+    '500',
+    '502',
+    '503',
+    '504',
+];
+/** Heuristic substrings that classify a message as deterministic. */
+const DETERMINISTIC_PATTERNS = [
+    'zod',
+    'safeParse',
+    'json parse',
+    'json.parse',
+    'unexpected token',
+    'unexpected end of json',
+    'invalid json',
+    'parse error',
+    'parse fail',
+    'schema',
+    'validation fail',
+    'validation error',
+    '400',
+    '401',
+    '403',
+    '404',
+    '422',
+];
+export function classifyError(err) {
+    // Explicit typed errors — highest authority
+    if (TransientError.is(err))
+        return 'transient';
+    if (DeterministicError.is(err))
+        return 'deterministic';
+    if (!(err instanceof Error))
+        return 'transient'; // conservative default
+    const m = err.message.toLowerCase();
+    // Check transient patterns first (rate-limit / network errors should not be
+    // misclassified as deterministic even if the message also contains "400").
+    for (const p of TRANSIENT_PATTERNS) {
+        if (m.includes(p))
+            return 'transient';
+    }
+    for (const p of DETERMINISTIC_PATTERNS) {
+        if (m.includes(p))
+            return 'deterministic';
+    }
+    // Conservative default: retry rather than silently poison
+    return 'transient';
+}
+//# sourceMappingURL=failure-classifier.js.map

package/dist/pipeline/failure-classifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure-classifier.js","sourceRoot":"","sources":["../../src/pipeline/failure-classifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAIjE,iEAAiE;AACjE,MAAM,kBAAkB,GAAa;IACnC,cAAc;IACd,WAAW;IACX,YAAY;IACZ,aAAa;IACb,cAAc;IACd,OAAO;IACP,YAAY;IACZ,YAAY;IACZ,WAAW;IACX,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;CACN,CAAC;AAEF,qEAAqE;AACrE,MAAM,sBAAsB,GAAa;IACvC,KAAK;IACL,WAAW;IACX,YAAY;IACZ,YAAY;IACZ,kBAAkB;IAClB,wBAAwB;IACxB,cAAc;IACd,aAAa;IACb,YAAY;IACZ,QAAQ;IACR,iBAAiB;IACjB,kBAAkB;IAClB,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;CACN,CAAC;AAEF,MAAM,UAAU,aAAa,CAAC,GAAY;IACxC,4CAA4C;IAC5C,IAAI,cAAc,CAAC,EAAE,CAAC,GAAG,CAAC;QAAE,OAAO,WAAW,CAAC;IAC/C,IAAI,kBAAkB,CAAC,EAAE,CAAC,GAAG,CAAC;QAAE,OAAO,eAAe,CAAC;IAEvD,IAAI,CAAC,CAAC,GAAG,YAAY,KAAK,CAAC;QAAE,OAAO,WAAW,CAAC,CAAC,uBAAuB;IAExE,MAAM,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;IAEpC,4EAA4E;IAC5E,2EAA2E;IAC3E,KAAK,MAAM,CAAC,IAAI,kBAAkB,EAAE,CAAC;QACnC,IAAI,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;YAAE,OAAO,WAAW,CAAC;IACxC,CAAC;IAED,KAAK,MAAM,CAAC,IAAI,sBAAsB,EAAE,CAAC;QACvC,IAAI,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;YAAE,OAAO,eAAe,CAAC;IAC5C,CAAC;IAED,0DAA0D;IAC1D,OAAO,WAAW,CAAC;AACrB,CAAC"}

package/dist/pipeline/handler-ctx-ext.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Extended HandlerCtx for Wave 3 distillation.
+ *
+ * Wave 3 adds providers, vector store, and repos to the handler context.
+ * We define an extended type here WITHOUT editing the frozen src/contracts/*
+ * or the base HandlerCtx in handler.ts.
+ *
+ * The startWorker() call in serve.ts/worker will be updated to pass an
+ * ExtendedHandlerCtx. Handlers that need providers type-assert to this.
+ */
+import type { HandlerCtx } from './handler.js';
+import type { MemoryRepo } from '../storage/memories.js';
+import type { SqliteVecStore } from '../vector/sqlite-vec.js';
+import type { ProviderSet } from '../providers/index.js';
+export interface ExtendedHandlerCtx extends HandlerCtx {
+    providers: ProviderSet;
+    memoryRepo: MemoryRepo;
+    vecStore: SqliteVecStore;
+}
+/**
+ * Type guard — true when ctx has the Wave 3 provider extensions.
+ */
+export declare function isExtendedCtx(ctx: HandlerCtx): ctx is ExtendedHandlerCtx;

package/dist/pipeline/handler-ctx-ext.js

@@ -0,0 +1,19 @@
+/**
+ * Extended HandlerCtx for Wave 3 distillation.
+ *
+ * Wave 3 adds providers, vector store, and repos to the handler context.
+ * We define an extended type here WITHOUT editing the frozen src/contracts/*
+ * or the base HandlerCtx in handler.ts.
+ *
+ * The startWorker() call in serve.ts/worker will be updated to pass an
+ * ExtendedHandlerCtx. Handlers that need providers type-assert to this.
+ */
+/**
+ * Type guard — true when ctx has the Wave 3 provider extensions.
+ */
+export function isExtendedCtx(ctx) {
+    return ('providers' in ctx &&
+        ctx.providers !== null &&
+        typeof ctx.providers === 'object');
+}
+//# sourceMappingURL=handler-ctx-ext.js.map

package/dist/pipeline/handler-ctx-ext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler-ctx-ext.js","sourceRoot":"","sources":["../../src/pipeline/handler-ctx-ext.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAcH;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,GAAe;IAC3C,OAAO,CACL,WAAW,IAAI,GAAG;QAClB,GAAG,CAAC,SAAS,KAAK,IAAI;QACtB,OAAO,GAAG,CAAC,SAAS,KAAK,QAAQ,CAClC,CAAC;AACJ,CAAC"}

package/dist/pipeline/handler.d.ts

@@ -0,0 +1,20 @@
+import type { DB } from '../storage/db.js';
+import type { Config } from '../config/config.js';
+import type { JobKind } from '../contracts/index.js';
+/**
+ * Context passed to every job handler.
+ * Wave 3 extends this via module augmentation to add:
+ *   llm: LLMProvider, embed: EmbedProvider, vector: VectorStore, memoryRepo: MemoryRepo
+ */
+export interface HandlerCtx {
+    db: DB;
+    config: Config;
+}
+/**
+ * A job handler is a named unit of async work keyed to a JobKind.
+ * Throw to signal failure; the worker increments attempts and transitions state.
+ */
+export interface JobHandler {
+    kind: JobKind;
+    handle(payload: unknown, ctx: HandlerCtx): Promise<void>;
+}

package/dist/pipeline/handler.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=handler.js.map

package/dist/pipeline/handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.js","sourceRoot":"","sources":["../../src/pipeline/handler.ts"],"names":[],"mappings":""}

package/dist/pipeline/handlers/cleanup.d.ts

@@ -0,0 +1,14 @@
+import type { JobHandler } from '../handler.js';
+/**
+ * Cleanup handler — IMPLEMENTED.
+ *
+ * Prunes jobs in the 'completed' state whose updated_at is older than
+ * `older_than_days` (default 30). Other states (pending, running, failed,
+ * poison, paused) are never touched so the operator can inspect them.
+ *
+ * Also runs the memory TTL/archival policy pass (FEAT-404) on the same
+ * cadence — config.archival.enabled === false (the default) makes it a
+ * no-op, so existing cleanup-job behavior is unchanged unless an operator
+ * opts in.
+ */
+export declare const cleanupHandler: JobHandler;

package/dist/pipeline/handlers/cleanup.js

@@ -0,0 +1,47 @@
+import { CleanupPayloadSchema } from '../../contracts/index.js';
+import { runArchivalPass } from '../../storage/archival.js';
+/**
+ * Cleanup handler — IMPLEMENTED.
+ *
+ * Prunes jobs in the 'completed' state whose updated_at is older than
+ * `older_than_days` (default 30). Other states (pending, running, failed,
+ * poison, paused) are never touched so the operator can inspect them.
+ *
+ * Also runs the memory TTL/archival policy pass (FEAT-404) on the same
+ * cadence — config.archival.enabled === false (the default) makes it a
+ * no-op, so existing cleanup-job behavior is unchanged unless an operator
+ * opts in.
+ */
+export const cleanupHandler = {
+    kind: 'cleanup',
+    async handle(payload, ctx) {
+        const parsed = CleanupPayloadSchema.safeParse(payload);
+        if (!parsed.success) {
+            throw new Error(`Invalid cleanup payload: ${parsed.error.message}`);
+        }
+        const { older_than_days } = parsed.data;
+        const cutoffMs = Date.now() - older_than_days * 24 * 60 * 60 * 1000;
+        const result = ctx.db.prepare(`
+      DELETE FROM jobs
+      WHERE state = 'completed'
+        AND updated_at < ?
+    `).run(cutoffMs);
+        // Poison jobs are kept 30 days for `queue` forensics, then purged —
+        // without this they accumulate forever (nothing else ever re-reads them).
+        const POISON_RETENTION_DAYS = 30;
+        const poisonCutoffMs = Date.now() - POISON_RETENTION_DAYS * 24 * 60 * 60 * 1000;
+        const poisonResult = ctx.db.prepare(`
+      DELETE FROM jobs
+      WHERE state = 'poison'
+        AND updated_at < ?
+    `).run(poisonCutoffMs);
+        console.log(`[cleanup] pruned ${result.changes} completed job(s) older than ${older_than_days} day(s), ` +
+            `${poisonResult.changes} poison job(s) older than ${POISON_RETENTION_DAYS} day(s)`);
+        const archival = runArchivalPass(ctx.db, ctx.config);
+        if (archival.candidates > 0) {
+            console.log(`[cleanup] archival pass: ${archival.archived}/${archival.candidates} stale low-usefulness ` +
+                `memories archived`);
+        }
+    }
+};
+//# sourceMappingURL=cleanup.js.map

package/dist/pipeline/handlers/cleanup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup.js","sourceRoot":"","sources":["../../../src/pipeline/handlers/cleanup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAEhE,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAE5D;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,cAAc,GAAe;IACxC,IAAI,EAAE,SAAS;IAEf,KAAK,CAAC,MAAM,CAAC,OAAgB,EAAE,GAAe;QAC5C,MAAM,MAAM,GAAG,oBAAoB,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACvD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CAAC,4BAA4B,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACtE,CAAC;QAED,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC;QACxC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,eAAe,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;QAEpE,MAAM,MAAM,GAAG,GAAG,CAAC,EAAE,CAAC,OAAO,CAAC;;;;KAI7B,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAEjB,oEAAoE;QACpE,0EAA0E;QAC1E,MAAM,qBAAqB,GAAG,EAAE,CAAC;QACjC,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,qBAAqB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;QAChF,MAAM,YAAY,GAAG,GAAG,CAAC,EAAE,CAAC,OAAO,CAAC;;;;KAInC,CAAC,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;QAEvB,OAAO,CAAC,GAAG,CACT,oBAAoB,MAAM,CAAC,OAAO,gCAAgC,eAAe,WAAW;YAC5F,GAAG,YAAY,CAAC,OAAO,6BAA6B,qBAAqB,SAAS,CACnF,CAAC;QAEF,MAAM,QAAQ,GAAG,eAAe,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QACrD,IAAI,QAAQ,CAAC,UAAU,GAAG,CAAC,EAAE,CAAC;YAC5B,OAAO,CAAC,GAAG,CACT,4BAA4B,QAAQ,CAAC,QAAQ,IAAI,QAAQ,CAAC,UAAU,wBAAwB;gBAC5F,mBAAmB,CACpB,CAAC;QACJ,CAAC;IACH,CAAC;CACF,CAAC"}

package/dist/pipeline/handlers/consolidate.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `consolidate` job handler — scheduled/queued entry point for the ADR-004
+ * stage 9 pass. The pass itself is deterministic and synchronous (no LLM in
+ * v1); this wrapper exists so consolidation can ride the jobs table like
+ * every other pipeline stage.
+ */
+import type { JobHandler } from '../handler.js';
+export declare const consolidateHandler: JobHandler;

package/dist/pipeline/handlers/consolidate.js

@@ -0,0 +1,23 @@
+/**
+ * `consolidate` job handler — scheduled/queued entry point for the ADR-004
+ * stage 9 pass. The pass itself is deterministic and synchronous (no LLM in
+ * v1); this wrapper exists so consolidation can ride the jobs table like
+ * every other pipeline stage.
+ */
+import { z } from 'zod';
+import { runConsolidation } from '../../consolidate/consolidate.js';
+const ConsolidatePayloadSchema = z.object({
+    merge_threshold: z.number().min(0).max(1).optional(),
+    propose_threshold: z.number().min(0).max(1).optional(),
+});
+export const consolidateHandler = {
+    kind: 'consolidate',
+    async handle(payload, ctx) {
+        const parsed = ConsolidatePayloadSchema.parse(payload ?? {});
+        runConsolidation(ctx.db, {
+            mergeThreshold: parsed.merge_threshold,
+            proposeThreshold: parsed.propose_threshold,
+        });
+    },
+};
+//# sourceMappingURL=consolidate.js.map

package/dist/pipeline/handlers/consolidate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consolidate.js","sourceRoot":"","sources":["../../../src/pipeline/handlers/consolidate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAEpE,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACpD,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;CACvD,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,kBAAkB,GAAe;IAC5C,IAAI,EAAE,aAAa;IACnB,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG;QACvB,MAAM,MAAM,GAAG,wBAAwB,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;QAC7D,gBAAgB,CAAC,GAAG,CAAC,EAAE,EAAE;YACvB,cAAc,EAAE,MAAM,CAAC,eAAe;YACtC,gBAAgB,EAAE,MAAM,CAAC,iBAAiB;SAC3C,CAAC,CAAC;IACL,CAAC;CACF,CAAC"}

package/dist/pipeline/handlers/distill-events.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Distill-events handler — ADR-008 `events` capture kind.
+ *
+ * Pre-typed atom candidates (runner-plugin grades/lessons/review verdicts)
+ * are already atom-shaped when they hit the wire, so this handler skips
+ * pipeline stages 1-5 (cleanup/normalize/chunk/compact/extract — the raw-text
+ * and LLM stages) and enters directly at stage 6 (reduce), chaining straight
+ * through stage 7 (memory-normalize) and stage 8 (embed+index), mirroring
+ * the same three-stage tail src/distill/pipeline.ts runs for the transcript
+ * path. No LLMProvider is used here (no compaction/extraction call), so the
+ * BudgetExceeded semantics distillHandler has for stages 4/5 do not apply —
+ * only the embed provider is exercised (stage 8).
+ */
+import type { JobHandler } from '../handler.js';
+export declare const distillEventsHandler: JobHandler;