@hcu-lab.me/mcp-device 1.0.9 → 1.0.12

package/dist/context/importer.d.ts

@@ -0,0 +1,8 @@
+import { ContextStore } from './store.js';
+/** Explicit trusted-local import. Missing scope is never inferred from the active pairing. */
+export declare function importLegacy(store: ContextStore, sourceFile: string): {
+    imported: number;
+    duplicates: number;
+    malformed: number;
+    quarantined: number;
+};

package/dist/context/importer.js

@@ -0,0 +1,69 @@
+import { readFileSync, statSync } from 'node:fs';
+import { createHash, randomBytes } from 'node:crypto';
+/** Explicit trusted-local import. Missing scope is never inferred from the active pairing. */
+export function importLegacy(store, sourceFile) {
+    if (statSync(sourceFile).size > 64 * 1024 * 1024)
+        throw new Error('BUDGET_EXCEEDED');
+    const result = { imported: 0, duplicates: 0, malformed: 0, quarantined: 0 };
+    const quarantine = (line, reason) => {
+        const fingerprint = createHash('sha256').update(reason).update(store.redactPayload(line).text).digest('hex');
+        store.registry.prepare('INSERT OR IGNORE INTO import_quarantine VALUES(?,?,?)').run(fingerprint, reason, Date.now());
+    };
+    for (const line of readFileSync(sourceFile, 'utf8').split(/\r?\n/)) {
+        if (!line.trim())
+            continue;
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch {
+            result.malformed++;
+            quarantine(line, 'malformed');
+            continue;
+        }
+        if (!event || typeof event !== 'object' || Array.isArray(event) ||
+            (typeof event.text !== 'string' && !(typeof event.toolName === 'string' && typeof event.timestamp === 'string' && event.output !== undefined))) {
+            result.malformed++;
+            quarantine(line, 'malformed');
+            continue;
+        }
+        const owner = event.owner_key, repo = event.repo_uuid;
+        if (typeof owner !== 'string' || typeof repo !== 'string' || owner !== store.activeOwner() ||
+            !store.registry.prepare('SELECT 1 FROM repositories WHERE owner_key=? AND repo_uuid=?').get(owner, repo)) {
+            result.quarantined++;
+            quarantine(line, 'unknown_scope');
+            continue;
+        }
+        const payload = typeof event.text === 'string' ? event.text : JSON.stringify({ toolName: event.toolName, arguments: event.arguments, output: event.output });
+        const path = typeof event.path === 'string' ? event.path : event.arguments?.path;
+        const safe = store.redactPayload(payload, { path: typeof path === 'string' ? path : undefined });
+        // Deduplication hashes retained redacted text only, never the raw secret-bearing payload.
+        const id = typeof event.id === 'string' || typeof event.id === 'number' ? store.redactPayload(String(event.id)).hash : safe.hash;
+        const db = store.repoDatabase(owner, repo);
+        store.quotaWrite(owner, repo, safe.retainedBytes * 4 + 65536, () => {
+            db.exec('BEGIN IMMEDIATE');
+            try {
+                const existing = db.prepare('SELECT evidence_ref FROM legacy_imports WHERE legacy_id=? OR content_hash=? LIMIT 1').get(id, safe.hash);
+                if (existing) {
+                    db.prepare('INSERT OR IGNORE INTO legacy_imports VALUES(?,?,?)').run(id, safe.hash, existing.evidence_ref);
+                    result.duplicates++;
+                }
+                else {
+                    const ref = randomBytes(24).toString('hex');
+                    db.prepare('INSERT INTO evidence(ref,text,hash,original_bytes,retained_bytes,redaction_state,partial) VALUES(?,?,?,?,?,?,?)')
+                        .run(ref, safe.text, safe.hash, safe.originalBytes, safe.retainedBytes, safe.state, Number(safe.partial));
+                    db.prepare('INSERT INTO events(invocation_id,accepted_at,payload_ref) VALUES(?,?,?)')
+                        .run(`legacy:${id}`, Number.isSafeInteger(event.accepted_at) ? event.accepted_at : Date.now(), ref);
+                    db.prepare('INSERT INTO legacy_imports VALUES(?,?,?)').run(id, safe.hash, ref);
+                    result.imported++;
+                }
+                store.commitRepository(db);
+            }
+            catch (error) {
+                db.exec('ROLLBACK');
+                throw error;
+            }
+        });
+    }
+    return result;
+}

package/dist/context/indexer.d.ts

@@ -0,0 +1,14 @@
+import { ContextStore } from './store.js';
+/** Incremental materialization of committed evidence, never filesystem discovery. */
+export declare function sync(store: ContextStore, owner: string, repo: string, options?: {
+    max_events?: number;
+    rebuild?: boolean;
+}): {
+    indexed: number;
+    generation: number | null;
+    indexed_through_event: number;
+    manifest_hash: string | number | bigint | Uint8Array<ArrayBufferLike> | null;
+    pending_events: number;
+    unknown_events: number;
+    fts_documents: number;
+};

package/dist/context/indexer.js

@@ -0,0 +1,57 @@
+import { createHash } from 'node:crypto';
+import { fold } from './text.js';
+import { materializeActivity } from './graph.js';
+/** Incremental materialization of committed evidence, never filesystem discovery. */
+export function sync(store, owner, repo, options = {}) {
+    const cap = options.max_events ?? 1000;
+    if (!Number.isInteger(cap) || cap < 1 || cap > 10000)
+        throw new Error('BUDGET_EXCEEDED');
+    const db = store.repoDatabase(owner, repo);
+    const currentManifest = store.manifest(owner, repo);
+    if (!options.rebuild && currentManifest.pending_events === 0 && currentManifest.generation !== null)
+        return { ...currentManifest, indexed: 0 };
+    const allocation = Number(db.prepare(`SELECT coalesce(sum(retained_bytes),0) AS n FROM
+    (SELECT p.retained_bytes FROM events e LEFT JOIN evidence p ON p.ref=e.payload_ref
+     WHERE e.event_id>? ORDER BY e.event_id LIMIT ?)`)
+        .get(options.rebuild ? 0 : currentManifest.indexed_through_event, cap)?.n) * 4 + cap * 1024 + 65536;
+    return store.quotaWrite(owner, repo, allocation, () => {
+        db.exec('BEGIN IMMEDIATE');
+        try {
+            const current = store.manifest(owner, repo);
+            if (options.rebuild && Number(db.prepare('SELECT count(*) AS n FROM events').get()?.n) > cap)
+                throw new Error('BUDGET_EXCEEDED');
+            const events = db.prepare(`SELECT e.event_id,e.accepted_at,e.payload_ref,p.text,p.retention_state FROM events e
+      LEFT JOIN evidence p ON p.ref=e.payload_ref WHERE e.event_id>? ORDER BY e.event_id LIMIT ?`).all(options.rebuild ? 0 : current.indexed_through_event, cap);
+            if (!options.rebuild && !events.length && current.generation !== null) {
+                store.commitRepository(db);
+                return { ...current, indexed: 0 };
+            }
+            const generation = Number(db.prepare("INSERT INTO generations(status,created_at) VALUES('shadow',?)").run(Date.now()).lastInsertRowid);
+            db.exec('CREATE INDEX IF NOT EXISTS activity_source ON activity_edges(source,edge_id); CREATE INDEX IF NOT EXISTS activity_target ON activity_edges(target,edge_id);');
+            if (options.rebuild)
+                db.exec('DELETE FROM evidence_fts');
+            for (const event of events) {
+                if (event.payload_ref === null || event.text === null || event.retention_state !== 'available')
+                    continue;
+                // A replay refreshes derived data but preserves original membership and tombstones.
+                db.prepare(`INSERT INTO search_documents(ref,source_kind,timestamp,first_indexed_generation,last_indexed_generation)
+        VALUES(?,?,?,?,?) ON CONFLICT(ref) DO UPDATE SET last_indexed_generation=excluded.last_indexed_generation`)
+                    .run(event.payload_ref, db.prepare("SELECT 1 FROM activity_nodes WHERE kind='checkpoint' AND evidence_ref=?").get(event.payload_ref) ? 'checkpoint' : 'history', event.accepted_at, generation, generation);
+                db.prepare('DELETE FROM evidence_fts WHERE ref=?').run(event.payload_ref);
+                materializeActivity(db, String(event.payload_ref), String(event.text));
+                // FTS receives folded redacted content only; evidence retains display text.
+                db.prepare('INSERT INTO evidence_fts(ref,text) VALUES(?,?)').run(event.payload_ref, fold(String(event.text)));
+            }
+            const through = events.length ? Number(events[events.length - 1].event_id) : current.indexed_through_event;
+            const digest = createHash('sha256').update(`${current.manifest_hash ?? ''}:${generation}:${through}`).digest('hex');
+            db.prepare("UPDATE generations SET status='published',indexed_through_event=?,manifest_hash=? WHERE generation_id=?").run(through, digest, generation);
+            db.prepare('UPDATE manifest SET generation=? WHERE singleton=1').run(generation);
+            store.commitRepository(db);
+            return { ...store.manifest(owner, repo), indexed: events.length };
+        }
+        catch (error) {
+            db.exec('ROLLBACK');
+            throw error;
+        }
+    });
+}

package/dist/context/migrations/index.d.ts

@@ -0,0 +1,4 @@
+import type { DatabaseSync } from 'node:sqlite';
+export declare function parseVersion(raw: unknown): number;
+/** Versioned transactional migration; future schema is never replaced by an empty DB. */
+export declare function migrate(db: DatabaseSync, kind: 'registry' | 'repo' | 'unscoped'): void;

package/dist/context/migrations/index.js

@@ -0,0 +1,87 @@
+import { fold } from '../text.js';
+const registry = `
+CREATE TABLE device_accounting(singleton INTEGER PRIMARY KEY CHECK(singleton=1), overhead_bytes INTEGER NOT NULL DEFAULT 0);
+INSERT INTO device_accounting VALUES(1,0);
+CREATE TABLE owners(owner_key TEXT PRIMARY KEY, pairing_hash TEXT NOT NULL, status TEXT NOT NULL CHECK(status IN ('active','sealed')), created_at INTEGER NOT NULL, accounted_bytes INTEGER NOT NULL DEFAULT 0);
+CREATE UNIQUE INDEX one_active_owner ON owners(status) WHERE status='active';
+CREATE TABLE repositories(repo_uuid TEXT PRIMARY KEY, owner_key TEXT NOT NULL REFERENCES owners(owner_key), identity TEXT NOT NULL, created_at INTEGER NOT NULL, accounted_bytes INTEGER NOT NULL DEFAULT 0, UNIQUE(owner_key,identity));
+CREATE TABLE worktrees(worktree_uuid TEXT PRIMARY KEY, repo_uuid TEXT NOT NULL REFERENCES repositories(repo_uuid), canonical_root TEXT NOT NULL, UNIQUE(repo_uuid,canonical_root));
+`;
+const repo = `
+CREATE TABLE evidence(ref TEXT PRIMARY KEY, text TEXT NOT NULL, hash TEXT NOT NULL, original_bytes INTEGER NOT NULL, retained_bytes INTEGER NOT NULL, redaction_state TEXT NOT NULL, partial INTEGER NOT NULL);
+CREATE TABLE events(event_id INTEGER PRIMARY KEY, invocation_id TEXT UNIQUE NOT NULL, accepted_at INTEGER NOT NULL, execution_status TEXT NOT NULL DEFAULT 'succeeded', recording_status TEXT NOT NULL DEFAULT 'committed', payload_ref TEXT REFERENCES evidence(ref));
+CREATE VIRTUAL TABLE evidence_fts USING fts5(ref UNINDEXED,text,tokenize='unicode61 remove_diacritics 2');
+CREATE TABLE activity_nodes(node_id TEXT PRIMARY KEY, kind TEXT NOT NULL, evidence_ref TEXT REFERENCES evidence(ref));
+CREATE TABLE activity_edges(edge_id TEXT PRIMARY KEY, source TEXT NOT NULL REFERENCES activity_nodes(node_id), target TEXT NOT NULL REFERENCES activity_nodes(node_id), relation TEXT NOT NULL, evidence_ref TEXT NOT NULL REFERENCES evidence(ref));
+CREATE TABLE generations(generation_id INTEGER PRIMARY KEY, status TEXT NOT NULL CHECK(status IN ('shadow','published')), indexed_through_event INTEGER NOT NULL DEFAULT 0, manifest_hash TEXT, created_at INTEGER NOT NULL);
+CREATE TABLE manifest(singleton INTEGER PRIMARY KEY CHECK(singleton=1), generation INTEGER REFERENCES generations(generation_id));
+INSERT INTO manifest VALUES(1,NULL);
+CREATE TABLE cursors(token_id TEXT PRIMARY KEY, generation INTEGER, query_hash TEXT NOT NULL, position INTEGER NOT NULL, expires_at INTEGER NOT NULL);
+`;
+const unscoped = `CREATE TABLE gaps(gap_id TEXT PRIMARY KEY, created_at INTEGER NOT NULL, reason TEXT NOT NULL CHECK(reason IN ('outside_repo','ambiguous_multi_repo','repo_resolution_failed','quota')));`;
+export function parseVersion(raw) {
+    if (typeof raw !== 'number' && (typeof raw !== 'string' || !/^(0|[1-9]\d*)$/.test(raw))) {
+        throw new Error('INDEX_INCOMPATIBLE');
+    }
+    const version = Number(raw);
+    if (!Number.isInteger(version) || version < 0 || version > 3) {
+        throw new Error('INDEX_INCOMPATIBLE');
+    }
+    return version;
+}
+/** Versioned transactional migration; future schema is never replaced by an empty DB. */
+export function migrate(db, kind) {
+    db.exec('PRAGMA busy_timeout=5000; PRAGMA secure_delete=ON');
+    let version = parseVersion(db.prepare('PRAGMA user_version').get()?.user_version);
+    if (version === 3)
+        return;
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        // Another opener may have migrated while we waited for the write lock.
+        version = parseVersion(db.prepare('PRAGMA user_version').get()?.user_version);
+        if (version === 3) {
+            db.exec('COMMIT');
+            return;
+        }
+        if (version === 0)
+            db.exec({ registry, repo, unscoped }[kind]);
+        if (kind === 'registry' && version < 2)
+            db.exec(`CREATE TABLE import_quarantine(fingerprint TEXT PRIMARY KEY, reason TEXT NOT NULL, first_seen INTEGER NOT NULL);`);
+        if (kind === 'repo' && version === 1) {
+            const fts = db.prepare("SELECT 1 FROM sqlite_master WHERE name='evidence_fts'").get();
+            if (fts)
+                db.exec(`
+        CREATE VIRTUAL TABLE evidence_fts_v2 USING fts5(ref UNINDEXED,text,tokenize='unicode61 remove_diacritics 2');
+        INSERT INTO evidence_fts_v2(ref,text) SELECT ref,text FROM evidence_fts;
+        DROP TABLE evidence_fts;
+        ALTER TABLE evidence_fts_v2 RENAME TO evidence_fts;
+      `);
+        }
+        if (kind === 'repo' && version < 2)
+            db.exec(`
+      CREATE TABLE legacy_imports(legacy_id TEXT PRIMARY KEY, content_hash TEXT NOT NULL, evidence_ref TEXT NOT NULL REFERENCES evidence(ref));
+      CREATE INDEX legacy_content ON legacy_imports(content_hash);
+      CREATE TABLE search_documents(ref TEXT PRIMARY KEY REFERENCES evidence(ref), source_kind TEXT NOT NULL, timestamp INTEGER NOT NULL,
+        first_indexed_generation INTEGER NOT NULL, last_indexed_generation INTEGER NOT NULL);
+      ALTER TABLE evidence ADD COLUMN retention_state TEXT NOT NULL DEFAULT 'available';
+    `);
+        if (kind === 'repo') {
+            db.exec('ALTER TABLE search_documents ADD COLUMN deleted_generation INTEGER;');
+            // Rebuild only already indexed redacted content with the new folding rule.
+            const rows = db.prepare('SELECT ref,text FROM evidence_fts').all();
+            db.exec('DELETE FROM evidence_fts');
+            const insert = db.prepare('INSERT INTO evidence_fts(ref,text) VALUES(?,?)');
+            for (const row of rows)
+                insert.run(row.ref, fold(String(row.text)));
+        }
+        db.exec('PRAGMA user_version=3; COMMIT');
+    }
+    catch (error) {
+        // COMMIT may already have released the transaction; preserve the original error.
+        try {
+            db.exec('ROLLBACK');
+        }
+        catch { /* No active transaction to roll back. */ }
+        throw error;
+    }
+}

package/dist/context/redact.d.ts

@@ -0,0 +1,15 @@
+export declare const MAX_PAYLOAD_BYTES: number;
+export interface RedactedPayload {
+    text: string;
+    hash: string;
+    originalBytes: number;
+    retainedBytes: number;
+    partial: boolean;
+    state: 'retained' | 'redacted' | 'excluded' | 'binary';
+}
+/** This is the sole payload persistence boundary. Hashes cover retained bytes only. */
+export declare function redact(input: string | Buffer, options?: {
+    path?: string;
+    maxBytes?: number;
+    key?: Buffer;
+}): RedactedPayload;

package/dist/context/redact.js

@@ -0,0 +1,43 @@
+import { createHash, createHmac, randomBytes } from 'node:crypto';
+import { utf8Prefix } from './text.js';
+// Non-persistence callers may redact without a store; persistence always supplies the installation key.
+const ephemeralKey = randomBytes(32);
+export const MAX_PAYLOAD_BYTES = 4 * 1024 * 1024;
+/** This is the sole payload persistence boundary. Hashes cover retained bytes only. */
+export function redact(input, options = {}) {
+    const cap = options.maxBytes ?? MAX_PAYLOAD_BYTES;
+    if (!Number.isInteger(cap) || cap < 0 || cap > MAX_PAYLOAD_BYTES)
+        throw new Error('BUDGET_EXCEEDED');
+    const tagKey = createHmac('sha256', options.key ?? ephemeralKey).update('redaction_tagging_v1').digest();
+    const bytes = Buffer.isBuffer(input) ? input : Buffer.from(input);
+    let text = bytes.toString('utf8');
+    let state = 'retained';
+    const path = options.path?.replace(/\\/g, '/');
+    if (path && /(?:^|\/)(?:\.env(?:\.[^/]*)?|id_(?:rsa|dsa|ecdsa|ed25519)(?:\.pub)?|credentials(?:\.[^/]*)?)(?:$|\/)/i.test(path)) {
+        text = '';
+        state = 'excluded';
+    }
+    else if (bytes.includes(0) || text.includes('\uFFFD') || /[\x01-\x08\x0e-\x1f]/.test(text) || /(?:^|\s)[A-Za-z0-9+/]{256,}={0,2}(?:$|\s)/.test(text)) {
+        text = '';
+        state = 'binary';
+    }
+    else {
+        const patterns = [
+            [/-----BEGIN (?:[A-Z ]+ )?PRIVATE KEY-----[\s\S]*?(?:-----END (?:[A-Z ]+ )?PRIVATE KEY-----|$)/g, 'private_key'],
+            [/\bBearer\s+[A-Za-z0-9._~+\/-]+=*/gi, 'bearer'],
+            [/\b(?:api[_-]?key|access[_-]?token|secret[_-]?key)["']?\s*[:=]\s*(?:"[^"\r\n]*"|'[^'\r\n]*'|[^\s,;"'\[\]{}]+)/gi, 'api_key'],
+            [/\b(?:password|passwd|pwd)["']?\s*[:=]\s*(?:"[^"\r\n]*"|'[^'\r\n]*'|[^\s,;"'\[\]{}]+)/gi, 'password'],
+            [/\b(?:sk-[A-Za-z0-9_-]{16,}|AKIA[A-Z0-9]{16}|gh[pousr]_[A-Za-z0-9]{20,})\b/g, 'api_key'],
+        ];
+        for (const [pattern, cls] of patterns)
+            text = text.replace(pattern, secret => {
+                state = 'redacted';
+                const tag = createHmac('sha256', tagKey).update(secret).digest('hex').slice(0, 16);
+                return `[REDACTED:${cls}:${tag}]`;
+            });
+    }
+    const partial = Buffer.byteLength(text) > cap;
+    text = utf8Prefix(text, cap);
+    return { text, hash: createHash('sha256').update(text).digest('hex'), originalBytes: bytes.length,
+        retainedBytes: Buffer.byteLength(text), partial, state };
+}

package/dist/context/repositories.d.ts

@@ -0,0 +1,9 @@
+export interface RepositoryResolution {
+    root: string;
+    identity: string;
+    worktree: string;
+    commonDir: string;
+}
+export type PathGuard = (path: string) => string | Promise<string>;
+/** Explicit trusted guard is mandatory; denial never falls back to a lexical path. */
+export declare function resolveRepository(cwd: unknown, guard: PathGuard): Promise<RepositoryResolution | null>;

package/dist/context/repositories.js

@@ -0,0 +1,45 @@
+import { execFileSync } from 'node:child_process';
+import { realpathSync, statSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+const hash = (value) => createHash('sha256').update(value).digest('hex');
+/** Explicit trusted guard is mandatory; denial never falls back to a lexical path. */
+export async function resolveRepository(cwd, guard) {
+    if (Array.isArray(cwd))
+        throw new Error('SCOPE_AMBIGUOUS');
+    if (typeof cwd !== 'string' || !cwd)
+        throw new Error('SCOPE_REQUIRED');
+    if (!isAbsolute(cwd) || cwd.split(/[\\/]/).includes('..'))
+        throw new Error('ACCESS_DENIED');
+    const approved = await guard(cwd);
+    let canonical;
+    try {
+        canonical = realpathSync(approved);
+        if (!statSync(canonical).isDirectory())
+            throw new Error();
+    }
+    catch {
+        throw new Error('REPOSITORY_NOT_FOUND');
+    }
+    // Guard the real target too if a symlink was resolved.
+    if (resolve(canonical) !== resolve(approved))
+        await guard(canonical);
+    const git = (...args) => execFileSync('git', ['-C', canonical, ...args], {
+        encoding: 'utf8', timeout: 5000, maxBuffer: 64 * 1024, stdio: ['ignore', 'pipe', 'pipe'],
+        env: { ...process.env, GIT_DIR: undefined, GIT_WORK_TREE: undefined, GIT_COMMON_DIR: undefined },
+    }).trim();
+    try {
+        const root = realpathSync(git('rev-parse', '--show-toplevel'));
+        const commonDir = realpathSync(resolve(canonical, git('rev-parse', '--git-common-dir')));
+        await guard(root);
+        await guard(commonDir);
+        return { root, commonDir, identity: hash(commonDir), worktree: hash(root) };
+    }
+    catch (error) {
+        // A confirmed non-repository is unscoped. Permission and subprocess failures are not.
+        const failure = error;
+        if (String(failure.stderr ?? '').includes('not a git repository'))
+            return null;
+        throw new Error('ACCESS_DENIED');
+    }
+}

package/dist/context/search.d.ts

@@ -0,0 +1,63 @@
+import { ContextStore } from './store.js';
+export interface SearchOptions {
+    query: string;
+    limit?: number;
+    max_bytes?: number;
+    cursor?: string;
+    source_types?: string[];
+    since?: number;
+    until?: number;
+    include_related?: boolean;
+}
+export interface ReadOptions {
+    refs: string[];
+    max_bytes?: number;
+    cursor?: string;
+    ranges?: {
+        ref: string;
+        start: number;
+        end?: number;
+    }[];
+}
+export declare function search(store: ContextStore, owner: string, repo: string, input: SearchOptions): {
+    schema_version: number;
+    ok: boolean;
+    scope: {
+        repository_ref: string;
+    };
+    index: {
+        generation: number | null;
+        indexed_through_event: number;
+        pending_events: number;
+        freshness: string;
+    };
+    coverage: {
+        complete: boolean;
+        reasons: string[];
+    };
+    items: Record<string, unknown>[];
+    partial: boolean;
+    next_cursor: string | null;
+    warnings: string[];
+};
+export declare function readEvidence(store: ContextStore, owner: string, repo: string, input: ReadOptions): {
+    schema_version: number;
+    ok: boolean;
+    scope: {
+        repository_ref: string;
+    };
+    index: {
+        generation: number | null;
+        indexed_through_event: number;
+        pending_events: number;
+        freshness: string;
+    };
+    coverage: {
+        complete: boolean;
+        reasons: string[];
+    };
+    items: Record<string, unknown>[];
+    partial: boolean;
+    next_cursor: string | null;
+    warnings: string[];
+};

package/dist/context/search.js

@@ -0,0 +1,207 @@
+import { createHash } from 'node:crypto';
+import { fold, utf8Prefix } from './text.js';
+import { queryActivityGraph } from './graph.js';
+const bytes = (value) => Buffer.byteLength(JSON.stringify(value));
+const digest = (value) => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+function budget(value, fallback, ceiling) {
+    const cap = value ?? fallback;
+    if (!Number.isInteger(cap) || cap < 1 || cap > ceiling)
+        throw new Error('BUDGET_EXCEEDED');
+    return cap;
+}
+function envelope(store, owner, repo) {
+    const manifest = store.inspectManifest(owner, repo);
+    const reasons = manifest.unknown_events ? ['unknown_after_restart'] : [];
+    return { schema_version: 1, ok: true, scope: { repository_ref: repo },
+        index: { generation: manifest.generation, indexed_through_event: manifest.indexed_through_event,
+            pending_events: manifest.pending_events, freshness: manifest.generation === null ? 'missing' : manifest.pending_events ? 'stale' : 'current' },
+        coverage: { complete: !reasons.length, reasons }, items: [],
+        partial: false, next_cursor: null, warnings: [] };
+}
+function continuation(store, owner, repo, key, generation, cursor, pinned = false) {
+    // First-page keyset sentinel is the all-null tuple (last_match,
+    // last_timestamp, last_ref), not bucket 0 / MAX_SAFE_INTEGER / ''. The
+    // Outer WHERE (? IS NULL OR ...) guard bypasses the keyset predicate entirely,
+    // including rows at timestamp bounds. Continuations carry the last row tuple.
+    if (!cursor)
+        return { generation, position: 0, offset: 0, last_match: null, last_timestamp: null, last_ref: null, expires_at: Date.now() + 600000 };
+    const state = store.parseReadCursor(owner, repo, cursor);
+    if (state.key !== key || !Number.isSafeInteger(state.position) || Number(state.position) < 0 ||
+        !Number.isSafeInteger(state.offset) || Number(state.offset) < 0)
+        throw new Error('CURSOR_INVALID');
+    const validGeneration = pinned
+        ? Number.isSafeInteger(state.generation) && Number(state.generation) >= 1 && generation !== null && Number(state.generation) <= generation
+        : state.generation === generation;
+    if (typeof state.expires_at !== 'number' || state.expires_at <= Date.now() || !validGeneration)
+        throw new Error('CURSOR_STALE');
+    if (pinned && !(state.last_match === null && state.last_timestamp === null && state.last_ref === null) &&
+        (![0, 1].includes(Number(state.last_match)) || typeof state.last_match !== 'number' || !Number.isSafeInteger(state.last_timestamp) || typeof state.last_ref !== 'string' || !/^[a-f0-9]{48}$/.test(state.last_ref)))
+        throw new Error('CURSOR_INVALID');
+    return { generation: state.generation, position: Number(state.position), offset: Number(state.offset),
+        last_match: state.last_match, last_timestamp: state.last_timestamp,
+        last_ref: state.last_ref, expires_at: state.expires_at };
+}
+export function search(store, owner, repo, input) {
+    store.authorize(owner, repo);
+    const query = input.query?.trim().normalize('NFC');
+    if (!query || Buffer.byteLength(query) > 4096)
+        throw new Error('BUDGET_EXCEEDED');
+    const limit = budget(input.limit, 8, 50), cap = budget(input.max_bytes, 65536, 131072);
+    const sources = input.source_types ?? ['history', 'checkpoint', 'activity'];
+    if (!Array.isArray(sources) || !sources.length || sources.some(s => !['history', 'checkpoint', 'activity'].includes(s)))
+        throw new Error('ACTION_UNSUPPORTED');
+    for (const time of [input.since, input.until])
+        if (time !== undefined && !Number.isSafeInteger(time))
+            throw new Error('BUDGET_EXCEEDED');
+    const result = envelope(store, owner, repo);
+    let generation = result.index.generation;
+    if (generation === null)
+        throw new Error('INDEX_MISSING');
+    if (input.include_related !== undefined && typeof input.include_related !== 'boolean')
+        throw new Error('ACTION_UNSUPPORTED');
+    const key = digest(['search', query, limit, sources, input.since, input.until, input.include_related]);
+    const state = continuation(store, owner, repo, key, generation, input.cursor, true);
+    generation = state.generation;
+    result.index.generation = generation;
+    const token = (row) => store.signReadCursor(owner, repo, { key, generation, position: 0, offset: 0, last_match: row?.score ?? state.last_match,
+        last_timestamp: row?.timestamp ?? state.last_timestamp,
+        last_ref: row?.ref ?? state.last_ref, expires_at: state.expires_at });
+    // Quote individual Unicode tokens; no user FTS operators or SQL are accepted.
+    const terms = fold(query).match(/[\p{L}\p{N}_]+/gu)?.slice(0, 64) ?? [];
+    const fts = terms.map(term => `"${term.replace(/"/g, '""')}"`).join(' OR ');
+    const ftsClause = terms.length ? 'UNION ALL SELECT ref,1 AS score FROM evidence_fts WHERE evidence_fts MATCH ?' : '';
+    return store.withReadDatabase(owner, repo, db => {
+        // Search ranks by discrete relevance buckets: 0 = exact substring, 1 = FTS
+        // token match, then timestamp DESC and ref ASC as stable tie-breakers.
+        // This deterministic ordering completely insulates keyset pagination from
+        // dynamic BM25 score shifts as corpus statistics change across generations.
+        // Current retention availability overrides pinned generation membership:
+        // purged evidence is never returned.
+        // Group each document before applying the keyset: filtering match rows first
+        // could resurrect an exact match as an FTS-only match on the next page.
+        // Bind order: substring, optional FTS, generation twice, each source, time
+        // bounds, then exactly seven keyset arguments in this SQL placeholder order:
+        // [last_match, last_match, last_match, last_timestamp,
+        //  last_match, last_timestamp, last_ref], followed by limit.
+        // All seven keyset arguments are null on the first page.
+        // Total placeholders = 13 + sources.length + (terms.length ? 1 : 0).
+        const rows = db.prepare(`WITH matches AS (
+      SELECT ref,0 AS score FROM evidence WHERE instr(lower(text),lower(?))>0
+      ${ftsClause}
+    ), ranked AS (
+      SELECT d.ref,d.source_kind,d.timestamp,p.text,p.partial,p.redaction_state,min(m.score) AS score
+      FROM matches m JOIN search_documents d ON d.ref=m.ref JOIN evidence p ON p.ref=d.ref
+      WHERE d.first_indexed_generation<=? AND (d.deleted_generation IS NULL OR d.deleted_generation>?) AND p.retention_state='available'
+      AND d.source_kind IN (${sources.map(() => '?').join(',')}) AND d.timestamp>=? AND d.timestamp<=?
+      GROUP BY d.ref
+    ) SELECT * FROM ranked
+      WHERE (? IS NULL OR score>? OR (score=? AND timestamp<?) OR (score=? AND timestamp=? AND ref>?))
+      ORDER BY score ASC,timestamp DESC,ref ASC LIMIT ?`)
+            .all(query, ...(terms.length ? [fts] : []), generation, generation, ...sources, input.since ?? 0, input.until ?? Number.MAX_SAFE_INTEGER, state.last_match, state.last_match, state.last_match, state.last_timestamp, state.last_match, state.last_timestamp, state.last_ref, limit + 1);
+        let count = 0;
+        for (const row of rows.slice(0, limit)) {
+            const item = { ref: row.ref, source_kind: row.source_kind, evidence_class: row.source_kind === 'checkpoint' ? 'reported' : 'observed', timestamp: row.timestamp,
+                label: 'Retained evidence', snippet: utf8Prefix(String(row.text), 512), match_reason: Number(row.score) === 0 ? 'exact' : 'fts',
+                redaction_state: row.redaction_state, truncated: Boolean(row.partial) || Buffer.byteLength(String(row.text)) > 512 };
+            const related = input.include_related ? queryActivityGraph(store, owner, repo, {
+                refs: [String(row.ref)], action: 'related', generation, max_nodes: 20, max_edges: 50, max_visited: 20, wall_ms: 10,
+            }) : undefined;
+            result.items.push(related ? { ...item, related_refs: [...new Set(related.nodes.filter(n => n.kind === 'event' && n.evidence_ref !== row.ref).map(n => n.evidence_ref))],
+                related_partial: related.partial, related_examined_edges: related.examined_edges } : item);
+            count++;
+            result.partial = rows.length > count;
+            result.next_cursor = result.partial ? token(rows[count - 1]) : null;
+            if (bytes(result) > cap) {
+                result.items.pop();
+                count--;
+                result.partial = true;
+                result.next_cursor = token(rows[count - 1]);
+                break;
+            }
+        }
+        if (bytes(result) > cap || (rows.length && count === 0))
+            throw new Error('BUDGET_EXCEEDED');
+        if (result.partial)
+            result.warnings = ['response_budget_or_limit'];
+        if (bytes(result) > cap)
+            throw new Error('BUDGET_EXCEEDED');
+        return result;
+    });
+}
+export function readEvidence(store, owner, repo, input) {
+    store.authorize(owner, repo);
+    if (!Array.isArray(input.refs) || input.refs.length < 1 || input.refs.length > 20 || input.refs.some(ref => typeof ref !== 'string' || ref.length > 128))
+        throw new Error('BUDGET_EXCEEDED');
+    const cap = budget(input.max_bytes, 262144, 1048576), result = envelope(store, owner, repo);
+    const ranges = input.ranges ?? [];
+    if (!Array.isArray(ranges) || ranges.length > 20 || new Set(ranges.map(range => range.ref)).size !== ranges.length || ranges.some(range => !input.refs.includes(range.ref) || !Number.isSafeInteger(range.start) || range.start < 0 || (range.end !== undefined && (!Number.isSafeInteger(range.end) || range.end < range.start))))
+        throw new Error('ACTION_UNSUPPORTED');
+    const key = digest(ranges.length ? ['read', input.refs, ranges] : ['read', input.refs]);
+    const state = continuation(store, owner, repo, key, result.index.generation, input.cursor);
+    const token = (position, offset) => store.signReadCursor(owner, repo, { key, generation: result.index.generation, position, offset, expires_at: state.expires_at });
+    return store.withReadDatabase(owner, repo, db => {
+        for (let i = state.position; i < input.refs.length; i++) {
+            const ref = input.refs[i], row = db.prepare('SELECT * FROM evidence WHERE ref=?').get(ref);
+            const range = ranges.find(range => range.ref === ref);
+            const start = i === state.position && state.offset > 0 ? state.offset : range?.start ?? 0;
+            const error = !row ? 'REF_NOT_FOUND' : ['expired', 'purged'].includes(String(row.retention_state)) ? 'EVIDENCE_EXPIRED' : null;
+            if (error) {
+                result.items.push({ ref, error });
+                result.partial = i + 1 < input.refs.length;
+                result.next_cursor = result.partial ? token(i + 1, 0) : null;
+                if (bytes(result) > cap) {
+                    result.items.pop();
+                    result.partial = true;
+                    result.next_cursor = token(i, 0);
+                    break;
+                }
+                continue;
+            }
+            const text = String(row.text), total = Buffer.byteLength(text);
+            const endLimit = Math.min(range?.end ?? total, total);
+            const buffer = Buffer.from(text);
+            const boundary = (offset) => offset === total || (buffer[offset] & 0xc0) !== 0x80;
+            if (start > total || start > endLimit || !boundary(start) || !boundary(endLimit))
+                throw new Error(range ? 'ACTION_UNSUPPORTED' : 'CURSOR_INVALID');
+            const remaining = buffer.subarray(start, endLimit).toString('utf8');
+            const isCheckpoint = Boolean(db.prepare("SELECT 1 FROM activity_nodes WHERE kind='checkpoint' AND evidence_ref=?").get(ref));
+            const item = { ref, source_kind: isCheckpoint ? 'checkpoint' : 'history', evidence_class: isCheckpoint ? 'reported' : 'observed', content: '', hash: row.hash,
+                captured_range: { start, end: start }, total_bytes: total, redaction_state: row.redaction_state,
+                retention_state: row.partial ? 'partial' : row.retention_state, truncated: Boolean(row.partial) };
+            result.items.push(item);
+            const fit = (length) => {
+                const content = utf8Prefix(remaining, length), end = start + Buffer.byteLength(content);
+                item.content = content;
+                item.captured_range = { start, end };
+                item.truncated = Boolean(row.partial) || start > 0 || end < total;
+                result.partial = end < endLimit || i + 1 < input.refs.length;
+                result.next_cursor = null;
+                if (end < endLimit)
+                    result.next_cursor = token(i, end);
+                else if (i + 1 < input.refs.length)
+                    result.next_cursor = token(i + 1, 0);
+                return bytes(result) <= cap;
+            };
+            let low = 0, high = Buffer.byteLength(remaining);
+            while (low < high) {
+                const mid = Math.ceil((low + high) / 2);
+                if (fit(mid))
+                    low = mid;
+                else
+                    high = mid - 1;
+            }
+            const fits = fit(low);
+            if (!fits || (endLimit > start && !String(item.content).length)) {
+                result.items.pop();
+                result.partial = true;
+                result.next_cursor = token(i, start);
+                break;
+            }
+            if (start + Buffer.byteLength(String(item.content)) < endLimit)
+                break;
+        }
+        if (bytes(result) > cap || !result.items.length)
+            throw new Error('BUDGET_EXCEEDED');
+        return result;
+    });
+}