@cmetech/otto 1.1.1 → 1.2.4

package/packages/coworker-artifacts/src/types.ts

@@ -0,0 +1,61 @@
+// packages/coworker-artifacts/src/types.ts
+export type ArtifactKind = 'report';
+export const ARTIFACT_KINDS = ['report'] as const;
+
+export interface ArtifactHandle {
+  slug: string;
+  kind: ArtifactKind;
+  name: string;
+  dir: string;
+  uri: string;
+  primaryPath: string;
+  metadataPath: string;
+  provenancePath: string;
+  readmePath: string;
+}
+
+export interface ArtifactMetadata {
+  _schema: 1;
+  slug: string;
+  kind: ArtifactKind;
+  name: string;
+  created_at: string;
+  last_updated_at: string;
+  turn_count: number;
+  primary_file: string;
+  uri: string;
+}
+
+export interface TurnEntry {
+  _schema: 1;
+  ts: string;
+  action: 'create' | 'update';
+  turn_id: string;
+  agent_turn_id?: string;
+  user_prompt: string;
+  scratchpad_name?: string;
+  files_touched: string[];
+}
+
+export type Provenance = TurnEntry[];
+
+export interface DirSnapshotEntry {
+  mtimeNs: bigint;
+  sizeBytes: number;
+}
+
+export type DirSnapshot = Map<string, DirSnapshotEntry>;
+
+export interface FileWrite {
+  path: string;
+  content: string;
+}
+
+export interface ResolvedArtifactUri {
+  slug: string;
+  dir: string;
+  primaryPath: string;
+  metadataPath: string;
+  provenancePath: string;
+  readmePath: string;
+}

package/packages/coworker-artifacts/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "target": "ES2022",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "declaration": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"],
+  "exclude": ["src/**/*.test.ts"]
+}

package/packages/coworker-artifacts/tsconfig.publish.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": { "incremental": false }
+}

package/packages/coworker-memory/dist/context-injection.d.ts

@@ -0,0 +1,9 @@
+import type { ScopeMode } from './types.js';
+import type { LayerAStore } from './layer-a-store.js';
+export interface ContextInjectionArgs {
+    mode: ScopeMode;
+    globalStore: LayerAStore;
+    workspaceStore: LayerAStore;
+    tokenLimit: number;
+}
+export declare function buildLayerAContext(args: ContextInjectionArgs): Promise<string>;

package/packages/coworker-memory/dist/context-injection.js

@@ -0,0 +1,41 @@
+const CHARS_PER_TOKEN = 4;
+export async function buildLayerAContext(args) {
+    const charLimit = args.tokenLimit * CHARS_PER_TOKEN;
+    const readScopes = args.mode === 'global'
+        ? ['global']
+        : args.mode === 'per-project'
+            ? ['workspace']
+            : ['workspace', 'global'];
+    const sections = [];
+    const PRIORITIES = { profile: 0, rules: 1, lessons: 2 };
+    for (const scope of readScopes) {
+        const store = scope === 'global' ? args.globalStore : args.workspaceStore;
+        const profile = await store.read('profile');
+        const rules = await store.read('rule');
+        const lessons = await store.read('lesson');
+        if (profile)
+            sections.push({ title: `Profile (${scope})`, body: profile, priority: PRIORITIES.profile });
+        if (rules)
+            sections.push({ title: `Rules (${scope})`, body: rules, priority: PRIORITIES.rules });
+        if (lessons)
+            sections.push({ title: `Recent lessons (${scope})`, body: lessons, priority: PRIORITIES.lessons });
+    }
+    if (sections.length === 0)
+        return '';
+    // workspace comes first because we iterated readScopes in that order; stable sort by priority.
+    sections.sort((a, b) => a.priority - b.priority);
+    let total = 0;
+    const include = [];
+    for (const s of sections) {
+        const cost = s.title.length + s.body.length + 10;
+        if (total + cost > charLimit && include.length > 0)
+            break;
+        include.push(s);
+        total += cost;
+    }
+    const lines = ['## Memory (Layer A)\n'];
+    for (const s of include) {
+        lines.push(`### ${s.title}\n${s.body}\n`);
+    }
+    return lines.join('\n');
+}

package/packages/coworker-memory/dist/errors.d.ts

@@ -0,0 +1,25 @@
+export declare class MemoryNotInitialized extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+export declare class BackendUnavailable extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+export declare class DrawerKindRejected extends Error {
+    readonly kind: string;
+    constructor(kind: string);
+}
+export declare class LayerAWriteBlocked extends Error {
+    readonly secretKind: string;
+    constructor(secretKind: string);
+}
+export declare class RecallQueryMalformed extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+export declare class MemoryEntryMalformed extends Error {
+    readonly path: string;
+    readonly reason: string;
+    constructor(path: string, reason: string);
+}

package/packages/coworker-memory/dist/errors.js

@@ -0,0 +1,51 @@
+// packages/coworker-memory/src/errors.ts
+export class MemoryNotInitialized extends Error {
+    reason;
+    constructor(reason) {
+        super(`Memory not initialized: ${reason}. /memory status to inspect.`);
+        this.reason = reason;
+        this.name = 'MemoryNotInitialized';
+    }
+}
+export class BackendUnavailable extends Error {
+    reason;
+    constructor(reason) {
+        super(`Memory backend unavailable: ${reason}.`);
+        this.reason = reason;
+        this.name = 'BackendUnavailable';
+    }
+}
+export class DrawerKindRejected extends Error {
+    kind;
+    constructor(kind) {
+        super(`Drawer kind '${kind}' is not in v1 vocabulary. Allowed: turn, paste, file_load, ticket, email, rca, note.`);
+        this.kind = kind;
+        this.name = 'DrawerKindRejected';
+    }
+}
+export class LayerAWriteBlocked extends Error {
+    secretKind;
+    constructor(secretKind) {
+        super(`Refused to store: contains secret-shaped value (kind: ${secretKind}). Remove the secret and retry. Vault entries should land in /connect, not memorize.`);
+        this.secretKind = secretKind;
+        this.name = 'LayerAWriteBlocked';
+    }
+}
+export class RecallQueryMalformed extends Error {
+    reason;
+    constructor(reason) {
+        super(`Bad recall query: ${reason}.`);
+        this.reason = reason;
+        this.name = 'RecallQueryMalformed';
+    }
+}
+export class MemoryEntryMalformed extends Error {
+    path;
+    reason;
+    constructor(path, reason) {
+        super(`Layer A file ${path} is malformed: ${reason}. Move it aside and re-create.`);
+        this.path = path;
+        this.reason = reason;
+        this.name = 'MemoryEntryMalformed';
+    }
+}

package/packages/coworker-memory/dist/index.d.ts

@@ -0,0 +1,12 @@
+export * from './types.js';
+export * from './errors.js';
+export * from './memory-backend.js';
+export * from './workspace-id.js';
+export * from './scope-resolver.js';
+export * from './paste-detector.js';
+export * from './layer-a-store.js';
+export * from './local-sqlite-backend.js';
+export * from './memory-recorder.js';
+export * from './recall-formatter.js';
+export * from './context-injection.js';
+export * from './persona-seed.js';

package/packages/coworker-memory/dist/index.js

@@ -0,0 +1,12 @@
+export * from './types.js';
+export * from './errors.js';
+export * from './memory-backend.js';
+export * from './workspace-id.js';
+export * from './scope-resolver.js';
+export * from './paste-detector.js';
+export * from './layer-a-store.js';
+export * from './local-sqlite-backend.js';
+export * from './memory-recorder.js';
+export * from './recall-formatter.js';
+export * from './context-injection.js';
+export * from './persona-seed.js';

package/packages/coworker-memory/dist/layer-a-store.d.ts

@@ -0,0 +1,16 @@
+import { AuditLog, SecretScanner } from '@otto/coworker-utils';
+import type { LayerAEntry, LayerAKind } from './types.js';
+export interface LayerAStoreOptions {
+    scopeDir: string;
+    scope: 'global' | 'workspace';
+    audit: AuditLog;
+    scanner: SecretScanner;
+}
+export declare class LayerAStore {
+    private readonly opts;
+    constructor(opts: LayerAStoreOptions);
+    append(entry: LayerAEntry): Promise<void>;
+    read(kind: LayerAKind): Promise<string>;
+    private split;
+    private composeFile;
+}

package/packages/coworker-memory/dist/layer-a-store.js

@@ -0,0 +1,78 @@
+// packages/coworker-memory/src/layer-a-store.ts
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { LayerAWriteBlocked, MemoryEntryMalformed } from './errors.js';
+const FILE_FOR = {
+    profile: 'profile.md',
+    rule: 'rules.md',
+    lesson: 'lessons.md',
+};
+const TITLE_FOR = {
+    profile: 'Profile',
+    rule: 'Rules',
+    lesson: 'Lessons',
+};
+export class LayerAStore {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async append(entry) {
+        const hits = this.opts.scanner.scan(entry.text);
+        if (hits.length > 0) {
+            this.opts.audit.append({
+                _schema: 1, ts: new Date().toISOString(), producer: 'memory', action: 'block', severity: 'warn',
+                detail: { scope: this.opts.scope, kind: entry.kind, reason: 'secret', secret_kind: hits[0].kind },
+            });
+            throw new LayerAWriteBlocked(hits[0].kind);
+        }
+        mkdirSync(this.opts.scopeDir, { recursive: true, mode: 0o700 });
+        const path = join(this.opts.scopeDir, FILE_FOR[entry.kind]);
+        const existing = existsSync(path) ? readFileSync(path, 'utf8') : null;
+        const { body } = existing ? this.split(existing, path) : { body: '' };
+        const addition = entry.kind === 'lesson'
+            ? `- (${entry.ts}) ${entry.text}\n`
+            : `## ${entry.ts}\n${entry.text}\n\n`;
+        const newBody = (body && !body.endsWith('\n') ? body + '\n' : body) + addition;
+        const newFile = this.composeFile(entry.kind, newBody, entry.ts, entry.source);
+        const tmp = `${path}.tmp`;
+        writeFileSync(tmp, newFile, { mode: 0o600 });
+        chmodSync(tmp, 0o600);
+        renameSync(tmp, path);
+        this.opts.audit.append({
+            _schema: 1, ts: new Date().toISOString(), producer: 'memory', action: 'write-layer-a',
+            detail: { scope: this.opts.scope, kind: entry.kind, source: entry.source, byte_count: Buffer.byteLength(entry.text, 'utf8') },
+        });
+    }
+    async read(kind) {
+        const path = join(this.opts.scopeDir, FILE_FOR[kind]);
+        if (!existsSync(path))
+            return '';
+        const raw = readFileSync(path, 'utf8');
+        const { body } = this.split(raw, path);
+        return body.trim();
+    }
+    split(raw, path) {
+        if (!raw.startsWith('---')) {
+            return { frontmatter: {}, body: raw };
+        }
+        const end = raw.indexOf('\n---\n', 4);
+        if (end < 0)
+            throw new MemoryEntryMalformed(path, 'unterminated frontmatter');
+        try {
+            const fm = parseYaml(raw.slice(4, end));
+            const body = raw.slice(end + 5);
+            return { frontmatter: fm ?? {}, body };
+        }
+        catch (err) {
+            throw new MemoryEntryMalformed(path, `frontmatter parse: ${err.message}`);
+        }
+    }
+    composeFile(kind, body, ts, source) {
+        const fm = { schema_version: 1, last_modified_at: ts, source };
+        const fmStr = stringifyYaml(fm).trimEnd();
+        const header = `---\n${fmStr}\n---\n\n# ${TITLE_FOR[kind]}\n\n`;
+        return header + body.replace(new RegExp(`^\\n?# ${TITLE_FOR[kind]}\\n\\n?`), '');
+    }
+}

package/packages/coworker-memory/dist/local-sqlite-backend.d.ts

@@ -0,0 +1,28 @@
+import type { MemoryBackend } from './memory-backend.js';
+import type { Drawer, RecallQuery, RecallResult, BackendStatus, Wing, Room } from './types.js';
+export interface LocalSqliteBackendOptions {
+    dbPath: string;
+    now?: () => string;
+    busyTimeoutMs?: number;
+}
+export declare class LocalSqliteBackend implements MemoryBackend {
+    private db;
+    private readonly path;
+    private readonly now;
+    private readonly busyTimeoutMs;
+    constructor(opts: LocalSqliteBackendOptions);
+    open(): Promise<void>;
+    close(): Promise<void>;
+    private requireDb;
+    retain(input: Omit<Drawer, 'id' | 'created_at'>): Promise<Drawer>;
+    recall(query: RecallQuery): Promise<RecallResult[]>;
+    listRooms(wing?: Wing): Promise<Room[]>;
+    listWings(): Promise<Wing[]>;
+    status(): Promise<BackendStatus>;
+    clear(args: {
+        wing?: Wing;
+        confirm: true;
+    }): Promise<{
+        deleted: number;
+    }>;
+}

package/packages/coworker-memory/dist/local-sqlite-backend.js

@@ -0,0 +1,167 @@
+// packages/coworker-memory/src/local-sqlite-backend.ts
+import Database from 'better-sqlite3';
+import { readFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { v4 as uuid } from 'uuid';
+import { RecallQueryMalformed, BackendUnavailable } from './errors.js';
+function migrationDir() {
+    return join(dirname(fileURLToPath(import.meta.url)), 'migrations');
+}
+function escapeFts5(q) {
+    // Wrap each word containing special chars in double quotes; doubled internal quotes.
+    // Empty query → throw upstream.
+    const tokens = q.match(/\S+/g) ?? [];
+    return tokens.map(t => `"${t.replace(/"/g, '""')}"`).join(' OR ');
+}
+export class LocalSqliteBackend {
+    db = null;
+    path;
+    now;
+    busyTimeoutMs;
+    constructor(opts) {
+        this.path = opts.dbPath;
+        this.now = opts.now ?? (() => new Date().toISOString());
+        this.busyTimeoutMs = opts.busyTimeoutMs ?? 2000;
+    }
+    async open() {
+        if (this.db)
+            return;
+        mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+        try {
+            this.db = new Database(this.path);
+            this.db.pragma(`busy_timeout = ${this.busyTimeoutMs}`);
+            const dir = migrationDir();
+            const migrations = [
+                { version: 1, file: '001-init.sql' },
+                { version: 2, file: '002-artifact-kind.sql' },
+            ];
+            const userVersion = this.db.pragma('user_version', { simple: true });
+            for (const m of migrations) {
+                if (userVersion < m.version) {
+                    const sql = readFileSync(join(dir, m.file), 'utf8');
+                    this.db.exec(sql);
+                }
+            }
+        }
+        catch (err) {
+            throw new BackendUnavailable(`open failed: ${err.message}`);
+        }
+    }
+    async close() {
+        this.db?.close();
+        this.db = null;
+    }
+    requireDb() {
+        if (!this.db)
+            throw new BackendUnavailable('not opened');
+        return this.db;
+    }
+    async retain(input) {
+        const db = this.requireDb();
+        const id = uuid();
+        const created_at = this.now();
+        const stmt = db.prepare(`
+      INSERT INTO drawers (id, wing, room, kind, content, metadata_json, parent_id, redacted, created_at)
+      VALUES (@id, @wing, @room, @kind, @content, @metadata_json, @parent_id, @redacted, @created_at)
+    `);
+        stmt.run({
+            id, wing: input.wing, room: input.room, kind: input.kind, content: input.content,
+            metadata_json: JSON.stringify(input.metadata ?? {}),
+            parent_id: input.parent_id ?? null,
+            redacted: input.redacted ? 1 : 0,
+            created_at,
+        });
+        return { id, created_at, ...input };
+    }
+    async recall(query) {
+        if (!query.query || !query.query.trim())
+            throw new RecallQueryMalformed('empty query');
+        const db = this.requireDb();
+        const matchExpr = escapeFts5(query.query.trim());
+        const conditions = ['drawers_fts MATCH ?'];
+        const params = [matchExpr];
+        if (query.wing) {
+            if (Array.isArray(query.wing)) {
+                conditions.push(`d.wing IN (${query.wing.map(() => '?').join(',')})`);
+                params.push(...query.wing);
+            }
+            else {
+                conditions.push('d.wing = ?');
+                params.push(query.wing);
+            }
+        }
+        if (query.room) {
+            conditions.push('d.room = ?');
+            params.push(query.room);
+        }
+        if (query.kind) {
+            const kinds = Array.isArray(query.kind) ? query.kind : [query.kind];
+            conditions.push(`d.kind IN (${kinds.map(() => '?').join(',')})`);
+            params.push(...kinds);
+        }
+        if (query.days_back && query.days_back > 0) {
+            const cutoff = new Date(Date.now() - query.days_back * 86400_000).toISOString();
+            conditions.push('d.created_at >= ?');
+            params.push(cutoff);
+        }
+        const limit = Math.min(Math.max(query.max_results ?? 8, 1), 64);
+        params.push(limit);
+        const sql = `
+      SELECT d.id, d.wing, d.room, d.kind, d.content, d.metadata_json, d.parent_id, d.redacted, d.created_at,
+             bm25(drawers_fts) AS rank,
+             snippet(drawers_fts, 0, '<mark>', '</mark>', '...', 16) AS snippet
+      FROM drawers_fts
+      JOIN drawers d ON d.rowid = drawers_fts.rowid
+      WHERE ${conditions.join(' AND ')}
+      ORDER BY rank
+      LIMIT ?
+    `;
+        const rows = db.prepare(sql).all(...params);
+        return rows.map(r => ({
+            drawer: {
+                id: r.id, wing: r.wing, room: r.room, kind: r.kind, content: r.content,
+                metadata: JSON.parse(r.metadata_json),
+                parent_id: r.parent_id ?? undefined, redacted: r.redacted === 1,
+                created_at: r.created_at,
+            },
+            score: -r.rank, // BM25 lower=better in sqlite; invert for descending
+            snippet: r.snippet,
+        }));
+    }
+    async listRooms(wing) {
+        const db = this.requireDb();
+        const sql = wing
+            ? `SELECT DISTINCT room FROM drawers WHERE wing = ? ORDER BY room`
+            : `SELECT DISTINCT room FROM drawers ORDER BY room`;
+        const rows = wing ? db.prepare(sql).all(wing) : db.prepare(sql).all();
+        return rows.map(r => r.room);
+    }
+    async listWings() {
+        const db = this.requireDb();
+        const rows = db.prepare(`SELECT DISTINCT wing FROM drawers ORDER BY wing`).all();
+        return rows.map(r => r.wing);
+    }
+    async status() {
+        const db = this.requireDb();
+        const { c } = db.prepare(`SELECT COUNT(*) AS c FROM drawers`).get();
+        const { user_version } = db.prepare(`PRAGMA user_version`).get();
+        return {
+            ready: true,
+            workspace_wing: '', // caller (memory-singleton) overlays this from scope info
+            drawer_count: c,
+            layer_b_db_path: this.path,
+            schema_version: user_version,
+        };
+    }
+    async clear(args) {
+        if (args.confirm !== true)
+            throw new RecallQueryMalformed('confirm must be true');
+        const db = this.requireDb();
+        const stmt = args.wing
+            ? db.prepare(`DELETE FROM drawers WHERE wing = ?`)
+            : db.prepare(`DELETE FROM drawers`);
+        const result = args.wing ? stmt.run(args.wing) : stmt.run();
+        return { deleted: result.changes };
+    }
+}

package/packages/coworker-memory/dist/memory-backend.d.ts

@@ -0,0 +1,14 @@
+import type { Drawer, RecallQuery, RecallResult, BackendStatus, Wing, Room } from './types.js';
+export interface MemoryBackend {
+    recall(query: RecallQuery): Promise<RecallResult[]>;
+    retain(input: Omit<Drawer, 'id' | 'created_at'>): Promise<Drawer>;
+    listRooms(wing?: Wing): Promise<Room[]>;
+    listWings(): Promise<Wing[]>;
+    status(): Promise<BackendStatus>;
+    clear(args: {
+        wing?: Wing;
+        confirm: true;
+    }): Promise<{
+        deleted: number;
+    }>;
+}

package/packages/coworker-memory/dist/memory-backend.js

@@ -0,0 +1 @@
+export {};

package/packages/coworker-memory/dist/memory-recorder.d.ts

@@ -0,0 +1,50 @@
+import { AuditLog, SecretScanner } from '@otto/coworker-utils';
+import type { MemoryBackend } from './memory-backend.js';
+import type { Wing, Room, Drawer } from './types.js';
+export interface CurrentScratchpadProvider {
+    (sessionId: string): string | null;
+}
+export interface MemoryRecorderOptions {
+    backend: MemoryBackend;
+    scanner: SecretScanner;
+    audit: AuditLog;
+    writeWing: Wing;
+    currentScratchpadName: CurrentScratchpadProvider;
+    pasteOptions?: {
+        lengthThreshold?: number;
+        newlineThreshold?: number;
+    };
+}
+export declare class MemoryRecorder {
+    private readonly opts;
+    constructor(opts: MemoryRecorderOptions);
+    recordTurn(args: {
+        sessionId: string;
+        userText: string;
+        turnId: string;
+        room?: Room;
+    }): Promise<Drawer>;
+    recordPaste(args: {
+        sessionId: string;
+        content: string;
+        turnId: string;
+        room?: Room;
+    }): Promise<Drawer>;
+    recordFileLoad(args: {
+        scratchpadName: string;
+        collector: string;
+        uri: string;
+        bytes: number;
+        rows_loaded?: number;
+        schema?: object;
+        turnId: string;
+    }): Promise<Drawer>;
+    recordArtifact(args: {
+        scratchpadName: string;
+        slug: string;
+        kind: string;
+        uri: string;
+        turnId: string;
+    }): Promise<Drawer>;
+    private writeDrawer;
+}

package/packages/coworker-memory/dist/memory-recorder.js

@@ -0,0 +1,69 @@
+import { detectPaste } from './paste-detector.js';
+export class MemoryRecorder {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async recordTurn(args) {
+        const kind = detectPaste(args.userText, this.opts.pasteOptions);
+        const room = args.room ?? this.opts.currentScratchpadName(args.sessionId) ?? 'inbox';
+        return this.writeDrawer({
+            wing: this.opts.writeWing, room, kind,
+            content: args.userText, metadata: { turn_id: args.turnId, session_id: args.sessionId },
+        });
+    }
+    async recordPaste(args) {
+        const room = args.room ?? this.opts.currentScratchpadName(args.sessionId) ?? 'inbox';
+        return this.writeDrawer({
+            wing: this.opts.writeWing, room, kind: 'paste',
+            content: args.content, metadata: { turn_id: args.turnId, session_id: args.sessionId },
+        });
+    }
+    async recordFileLoad(args) {
+        const content = JSON.stringify({
+            collector: args.collector, uri: args.uri, bytes: args.bytes,
+            rows_loaded: args.rows_loaded, schema: args.schema,
+        });
+        return this.writeDrawer({
+            wing: this.opts.writeWing, room: args.scratchpadName, kind: 'file_load',
+            content, metadata: { turn_id: args.turnId, scratchpad: args.scratchpadName },
+        });
+    }
+    async recordArtifact(args) {
+        const content = JSON.stringify({
+            slug: args.slug, kind: args.kind, uri: args.uri,
+        });
+        return this.writeDrawer({
+            wing: this.opts.writeWing, room: args.scratchpadName, kind: 'artifact',
+            content, metadata: { turn_id: args.turnId, scratchpad: args.scratchpadName },
+        });
+    }
+    async writeDrawer(input) {
+        const hits = this.opts.scanner.scan(input.content);
+        let content = input.content;
+        let redacted = false;
+        if (hits.length > 0) {
+            content = this.opts.scanner.redact(input.content);
+            redacted = true;
+            const ts = new Date().toISOString();
+            for (const h of hits) {
+                this.opts.audit.append({
+                    _schema: 1, ts, producer: 'memory', action: 'redact', severity: 'warn',
+                    detail: {
+                        wing: input.wing, room: input.room, kind: input.kind,
+                        secret_kind: h.kind, offset: h.start, length: h.end - h.start,
+                    },
+                });
+            }
+        }
+        const drawer = await this.opts.backend.retain({ ...input, content, redacted });
+        this.opts.audit.append({
+            _schema: 1, ts: new Date().toISOString(), producer: 'memory', action: 'write-drawer',
+            detail: {
+                wing: drawer.wing, room: drawer.room, kind: drawer.kind,
+                byte_count: Buffer.byteLength(content, 'utf8'), redacted,
+            },
+        });
+        return drawer;
+    }
+}