@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/core/commandBudget.js

@@ -0,0 +1,62 @@
+// One command budget for every path that runs a shell command (PROP-0041). A blocking command is
+// how a reply spends a quarter of an hour: a default keeps ordinary commands honest, a ceiling
+// makes a long one an explicit choice, and a timeout returns what it saw instead of waiting.
+/** What a command gets when the caller says nothing. */
+export const DEFAULT_COMMAND_TIMEOUT_SECONDS = 120;
+/** Past this, a call must say why it needs longer. */
+export const COMMAND_TIMEOUT_CEILING_SECONDS = 300;
+/** The longest a single command may run at all. */
+export const COMMAND_TIMEOUT_MAX_SECONDS = 900;
+/** Resolves a requested timeout against the default, the ceiling and the maximum. */
+export function resolveCommandTimeout(requested, reason) {
+    const why = typeof reason === 'string' ? reason.trim() : '';
+    if (typeof requested !== 'number' || !Number.isFinite(requested))
+        return { ok: true, timeout: DEFAULT_COMMAND_TIMEOUT_SECONDS };
+    let timeout = Math.floor(requested);
+    if (timeout < 1)
+        return { ok: false, message: 'timeout must be a positive number of seconds.' };
+    // Some models send milliseconds (Claude Code's own bash tool takes them; GPT 6 Luna sends 120000).
+    // A value that only fits as milliseconds is read as milliseconds, instead of refusing every
+    // command that model sends.
+    if (timeout > COMMAND_TIMEOUT_MAX_SECONDS && timeout >= 1_000 && timeout / 1_000 <= COMMAND_TIMEOUT_MAX_SECONDS)
+        timeout = Math.ceil(timeout / 1_000);
+    if (timeout > COMMAND_TIMEOUT_MAX_SECONDS)
+        return { ok: false, message: `timeout is in seconds, and a command may run for at most ${COMMAND_TIMEOUT_MAX_SECONDS} seconds. Split it into smaller commands.` };
+    if (timeout > COMMAND_TIMEOUT_CEILING_SECONDS && !why) {
+        return { ok: false, message: `A command over ${COMMAND_TIMEOUT_CEILING_SECONDS} seconds needs a reason: pass reason with why it cannot be narrowed or run in smaller steps.` };
+    }
+    return { ok: true, timeout };
+}
+/** A command's result when it was stopped by the budget rather than finishing. */
+export function commandTimeoutText(seconds, output) {
+    return `The command was stopped after ${seconds} seconds by the command budget. Its output so far:\n${output || '(none)'}\n\nNarrow it: one test file, --grep for the failing case, or a line range, then run the full set at a checkpoint.`;
+}
+/**
+ * Runs a command with a wall-clock budget. The abort reaches the live shell, so the promise
+ * settles instead of leaving the reply blocked; a timeout is reported as a rejection the caller
+ * turns into a tool result.
+ */
+export async function withCommandBudget(run, abort, seconds) {
+    let timer;
+    try {
+        return await Promise.race([
+            run(),
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => {
+                    try {
+                        abort?.();
+                    }
+                    catch {
+                        // The abort is best effort; the timeout still settles the reply.
+                    }
+                    reject(new Error(commandTimeoutText(seconds, '')));
+                }, seconds * 1000);
+                timer.unref?.();
+            })
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}

package/dist/sdk/core/effort.d.ts

@@ -0,0 +1,2 @@
+export declare const EFFORTS: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+export type Effort = (typeof EFFORTS)[number];

package/dist/sdk/core/effort.js

@@ -0,0 +1 @@
+export const EFFORTS = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'];

package/dist/sdk/core/env.d.ts

@@ -0,0 +1,18 @@
+/** Names the harness shows but does not own. Every lookup may answer `null`. */
+export interface Directory {
+    /** An agent's display name. */
+    agentName(agentId: string): string | null;
+    /** The agent a conversation belongs to, when the session id is not the agent's own id. */
+    sessionAgent(sessionId: string): string | null;
+}
+/** The name used when an application gives none. */
+export declare const DEFAULT_PRODUCT_NAME = "Xingular Agent";
+export declare const EMPTY_DIRECTORY: Directory;
+export interface HarnessEnv {
+    /** The data root: `wiki/`, `registry/`, `runs/`, `config/`, `index.sqlite`. */
+    root: string;
+    directory: Directory;
+    /** How the harness names itself to a model and in the Wiki it creates. */
+    productName: string;
+}
+export declare function createEnv(root: string, options?: Partial<Omit<HarnessEnv, 'root'>>): HarnessEnv;

package/dist/sdk/core/env.js

@@ -0,0 +1,8 @@
+// What every harness module is given: where the data lives, and what the embedding application
+// knows that the harness does not.
+/** The name used when an application gives none. */
+export const DEFAULT_PRODUCT_NAME = 'Xingular Agent';
+export const EMPTY_DIRECTORY = { agentName: () => null, sessionAgent: () => null };
+export function createEnv(root, options = {}) {
+    return { root, directory: options.directory ?? EMPTY_DIRECTORY, productName: options.productName ?? DEFAULT_PRODUCT_NAME };
+}

package/dist/sdk/core/errors.d.ts

@@ -0,0 +1,15 @@
+/** A typed failure: a stable code, a message a person can read, and an optional hint on what to do next. */
+export declare class HarnessError extends Error {
+    readonly code: string;
+    readonly retryHint: string | null;
+    constructor(code: string, message: string, retryHint?: string | null);
+    withHint(hint: string): HarnessError;
+}
+export declare const invalid: (message: string) => HarnessError;
+export declare const notFound: (what: string) => HarnessError;
+export interface ErrorShape {
+    code: string;
+    message: string;
+    retryHint?: string | null;
+}
+export declare function toErrorShape(error: unknown, fallbackCode?: string): ErrorShape;

package/dist/sdk/core/errors.js

@@ -0,0 +1,24 @@
+/** A typed failure: a stable code, a message a person can read, and an optional hint on what to do next. */
+export class HarnessError extends Error {
+    code;
+    retryHint;
+    constructor(code, message, retryHint = null) {
+        super(message);
+        this.name = 'HarnessError';
+        this.code = code;
+        this.retryHint = retryHint;
+    }
+    withHint(hint) {
+        return new HarnessError(this.code, this.message, hint);
+    }
+}
+export const invalid = (message) => new HarnessError('invalid_request', message);
+export const notFound = (what) => new HarnessError('not_found', `${what} was not found.`);
+export function toErrorShape(error, fallbackCode = 'harness_error') {
+    if (error instanceof HarnessError)
+        return { code: error.code, message: error.message, retryHint: error.retryHint };
+    const code = error?.code;
+    if (error instanceof Error && typeof code === 'string' && code.startsWith('E'))
+        return { code: 'io_error', message: error.message };
+    return { code: fallbackCode, message: error instanceof Error ? error.message : String(error) };
+}

package/dist/sdk/core/frontmatter.d.ts

@@ -0,0 +1,12 @@
+export declare function split(text: string): {
+    yaml: string;
+    body: string;
+} | null;
+/** The frontmatter as a plain object and the body, or `null` when the block is missing or is not a mapping. */
+export declare function parse(text: string): {
+    front: Record<string, unknown>;
+    body: string;
+} | null;
+/** The text after a readable frontmatter block, or the whole text when there is none. */
+export declare function bodyOf(text: string): string;
+export declare function serialize(front: Record<string, unknown>, body: string): string;

package/dist/sdk/core/frontmatter.js

@@ -0,0 +1,50 @@
+// Markdown files with a YAML frontmatter block (`---` … `---`), used by Wiki pages, facts, blocks and registry items.
+import { parse as parseYaml, stringify } from 'yaml';
+import { HarnessError } from "./errors.js";
+export function split(text) {
+    const rest = text.startsWith('---\n') ? text.slice(4) : text.startsWith('---\r\n') ? text.slice(5) : null;
+    if (rest === null)
+        return null;
+    const end = rest.indexOf('\n---');
+    if (end < 0)
+        return null;
+    return { yaml: rest.slice(0, end), body: rest.slice(end + 4).replace(/^[\r\n]+/, '') };
+}
+/** The frontmatter as a plain object and the body, or `null` when the block is missing or is not a mapping. */
+export function parse(text) {
+    const parts = split(text);
+    if (!parts)
+        return null;
+    try {
+        const front = parseYaml(parts.yaml);
+        if (!front || typeof front !== 'object' || Array.isArray(front))
+            return null;
+        return { front: front, body: parts.body };
+    }
+    catch {
+        return null;
+    }
+}
+/** The text after a readable frontmatter block, or the whole text when there is none. */
+export function bodyOf(text) {
+    const parts = split(text);
+    if (!parts)
+        return text;
+    try {
+        parseYaml(parts.yaml);
+        return parts.body;
+    }
+    catch {
+        return text;
+    }
+}
+export function serialize(front, body) {
+    let yaml;
+    try {
+        yaml = stringify(front, { lineWidth: 0 });
+    }
+    catch (error) {
+        throw new HarnessError('invalid_data', error instanceof Error ? error.message : String(error));
+    }
+    return `---\n${yaml}---\n\n${body.trimEnd()}\n`;
+}

package/dist/sdk/core/fs.d.ts

@@ -0,0 +1,18 @@
+/** Writes through a temporary sibling file and renames it into place so readers never see a partial file. */
+export declare function atomicWrite(path: string, contents: string | Uint8Array): void;
+export declare function writeJson(path: string, value: unknown): void;
+/** `null` when the file does not exist; a file that exists but does not parse is an error. */
+export declare function readJson<T>(path: string): T | null;
+/** `readJson` for callers that treat an unreadable file like a missing one. */
+export declare function readJsonOr<T>(path: string, fallback: T): T;
+export declare function readText(path: string): string | null;
+export declare function appendLine(path: string, line: string): void;
+/** Accepts only IDs that are safe as a single path segment. */
+export declare function safeId(id: string): string;
+/** Accepts a relative path that stays inside its base directory. */
+export declare function safeRelative(path: string): string;
+/** Millisecond UTC timestamp, the format every record uses. */
+export declare function now(): string;
+export declare function newId(): string;
+export declare function isDir(path: string): boolean;
+export declare function isFile(path: string): boolean;

package/dist/sdk/core/fs.js

@@ -0,0 +1,106 @@
+import { randomUUID } from 'node:crypto';
+import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, normalize, sep } from 'node:path';
+import { HarnessError, invalid } from "./errors.js";
+/** Writes through a temporary sibling file and renames it into place so readers never see a partial file. */
+export function atomicWrite(path, contents) {
+    const parent = dirname(path);
+    mkdirSync(parent, { recursive: true });
+    const temporary = join(parent, `.${basename(path)}.${randomUUID()}.tmp`);
+    const file = openSync(temporary, 'w');
+    try {
+        writeSync(file, contents);
+        fsyncSync(file);
+    }
+    finally {
+        closeSync(file);
+    }
+    try {
+        renameSync(temporary, path);
+    }
+    catch (error) {
+        rmSync(temporary, { force: true });
+        throw error;
+    }
+}
+export function writeJson(path, value) {
+    atomicWrite(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+/** `null` when the file does not exist; a file that exists but does not parse is an error. */
+export function readJson(path) {
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw new HarnessError('invalid_data', `Stored data could not be read: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/** `readJson` for callers that treat an unreadable file like a missing one. */
+export function readJsonOr(path, fallback) {
+    try {
+        return readJson(path) ?? fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+export function readText(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+export function appendLine(path, line) {
+    let next = readText(path) ?? '';
+    if (next && !next.endsWith('\n'))
+        next += '\n';
+    atomicWrite(path, `${next}${line}\n`);
+}
+/** Accepts only IDs that are safe as a single path segment. */
+export function safeId(id) {
+    if (id.length > 0 && id.length <= 128 && /^[A-Za-z0-9_-]+$/.test(id))
+        return id;
+    throw invalid('Invalid identifier.');
+}
+/** Accepts a relative path that stays inside its base directory. */
+export function safeRelative(path) {
+    const parts = path.split(/[\\/]/);
+    if (!path || isAbsolute(path) || parts.some((part) => part === '' || part === '.' || part === '..')) {
+        throw invalid('Path must stay inside the working directory.');
+    }
+    return normalize(path).split(sep).join('/');
+}
+/** Millisecond UTC timestamp, the format every record uses. */
+export function now() {
+    return new Date().toISOString();
+}
+export function newId() {
+    return randomUUID();
+}
+export function isDir(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function isFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/sdk/core/index.d.ts

@@ -0,0 +1,24 @@
+import { DatabaseSync, type SQLInputValue } from 'node:sqlite';
+/** Ordered, append-only migrations. Each runs in one transaction; the file is backed up first. */
+export declare const MIGRATIONS: readonly string[];
+export declare function dbPath(root: string): string;
+/** Runs `work` inside one transaction, rolling back if it throws. */
+export declare function transaction<T>(database: DatabaseSync, work: () => T): T;
+/**
+ * Applies pending migrations. The database file is copied first; if any migration fails, the
+ * copy is restored and the error is reported.
+ */
+export declare function migrate(path: string, migrations: readonly string[]): DatabaseSync;
+/** Runs `work` with the shared connection for this data root, opening and migrating it on first use. */
+export declare function withIndex<T>(root: string, work: (database: DatabaseSync) => T): T;
+/** Closes this data root's connection, if one is open. */
+export declare function closeIndex(root: string): void;
+/** Closes the connection and removes the index files; the next use rebuilds the schema. */
+export declare function deleteIndex(root: string): void;
+export type Param = SQLInputValue;
+export declare function all<T>(database: DatabaseSync, sql: string, ...params: Param[]): T[];
+export declare function run(database: DatabaseSync, sql: string, ...params: Param[]): void;
+/** Folder names under `<data root>/runs`. */
+export declare function runFolders(root: string): string[];
+/** Turns free text into an FTS5 query: each word becomes a quoted prefix term. */
+export declare function ftsQuery(query: string): string | null;

package/dist/sdk/core/index.js

@@ -0,0 +1,203 @@
+// Derived SQLite index at `<data root>/index.sqlite`: full-text search over every Wiki entry
+// (pages, facts, blocks, registry skills/prompts/rules), links, sources, revisions, run
+// metadata, and recall passages. Markdown, raw sources, revision manifests, registry files, and
+// run files stay canonical; the index can always be deleted and rebuilt from them.
+import { copyFileSync, existsSync, readdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { HarnessError } from "./errors.js";
+/** Index migration 4: recall, the searchable record of conversations and runs. */
+const RECALL_SCHEMA = `CREATE TABLE recall_runs (run_id TEXT PRIMARY KEY, passages INTEGER NOT NULL, status TEXT NOT NULL);
+     CREATE VIRTUAL TABLE recall_fts USING fts5(run_id UNINDEXED, seq UNINDEXED, role UNINDEXED, at UNINDEXED,
+        mode UNINDEXED, session_id UNINDEXED, project_id UNINDEXED, text, tokenize = 'unicode61 remove_diacritics 2');`;
+/** Ordered, append-only migrations. Each runs in one transaction; the file is backed up first. */
+export const MIGRATIONS = [
+    // 1: initial schema
+    `CREATE TABLE pages (scope TEXT NOT NULL, id TEXT NOT NULL, title TEXT NOT NULL, type TEXT NOT NULL,
+        updated_at TEXT, path TEXT NOT NULL, source_ids TEXT NOT NULL, PRIMARY KEY (scope, id));
+     CREATE VIRTUAL TABLE pages_fts USING fts5(scope UNINDEXED, id UNINDEXED, title, body, links, sources,
+        tokenize = 'unicode61 remove_diacritics 2');
+     CREATE TABLE links (scope TEXT NOT NULL, from_id TEXT NOT NULL, to_id TEXT NOT NULL, type TEXT NOT NULL);
+     CREATE INDEX links_to ON links (scope, to_id);
+     CREATE TABLE sources (scope TEXT NOT NULL, id TEXT NOT NULL, name TEXT NOT NULL, imported_at TEXT, version INTEGER,
+        PRIMARY KEY (scope, id));
+     CREATE TABLE revisions (scope TEXT NOT NULL, page_id TEXT NOT NULL, id TEXT NOT NULL, created_at TEXT, actor TEXT,
+        PRIMARY KEY (scope, id));
+     CREATE TABLE runs (id TEXT PRIMARY KEY, project_id TEXT, mode TEXT, harness TEXT, session_type TEXT,
+        session_id TEXT, status TEXT, started_at TEXT, ended_at TEXT);
+     CREATE INDEX runs_session ON runs (session_id, started_at);`,
+    // 2: accounts and token usage per run
+    `ALTER TABLE runs ADD COLUMN account_id TEXT;
+     CREATE INDEX runs_account ON runs (account_id, started_at);
+     CREATE TABLE usage (run_id TEXT PRIMARY KEY, account_id TEXT, harness TEXT, model TEXT, day TEXT NOT NULL,
+        input_tokens INTEGER NOT NULL DEFAULT 0, output_tokens INTEGER NOT NULL DEFAULT 0);
+     CREATE INDEX usage_account ON usage (account_id, day);`,
+    // 3: one global Wiki; entries replace per-scope pages and include facts and registry items
+    `DROP TABLE IF EXISTS pages_fts; DROP TABLE IF EXISTS pages; DROP TABLE IF EXISTS links;
+     DROP TABLE IF EXISTS sources; DROP TABLE IF EXISTS revisions;
+     CREATE TABLE entries (id TEXT PRIMARY KEY, kind TEXT NOT NULL, title TEXT NOT NULL, type TEXT, path TEXT NOT NULL,
+        namespace TEXT NOT NULL, file TEXT NOT NULL, updated_at TEXT, source_ids TEXT NOT NULL);
+     CREATE VIRTUAL TABLE entries_fts USING fts5(id UNINDEXED, kind UNINDEXED, namespace UNINDEXED, title, body, links, sources,
+        tokenize = 'unicode61 remove_diacritics 2');
+     CREATE TABLE links (from_id TEXT NOT NULL, to_id TEXT NOT NULL, type TEXT NOT NULL);
+     CREATE INDEX links_to ON links (to_id);
+     CREATE TABLE sources (id TEXT PRIMARY KEY, name TEXT NOT NULL, imported_at TEXT, version INTEGER);
+     CREATE TABLE revisions (entry_id TEXT NOT NULL, id TEXT PRIMARY KEY, created_at TEXT, actor TEXT);
+     CREATE INDEX revisions_entry ON revisions (entry_id, created_at);`,
+    RECALL_SCHEMA,
+    // 5: a per-run summary cache for the embedding application's analytics
+    `CREATE TABLE run_stats (run_id TEXT PRIMARY KEY, session_id TEXT NOT NULL, version INTEGER NOT NULL, stats TEXT NOT NULL);
+     CREATE INDEX run_stats_session ON run_stats (session_id, version);`,
+    // 6: the agent that replied, so one agent's runs can be read across its sessions
+    `ALTER TABLE runs ADD COLUMN agent_id TEXT;
+     CREATE INDEX runs_agent ON runs (agent_id, started_at);
+     CREATE INDEX runs_started ON runs (started_at);`,
+    // 7: the per-account usage table goes
+    'DROP TABLE IF EXISTS usage;',
+    // 8: the usage ledger behind `/usage:analysis`, rebuilt from each run's `usage.updated` events
+    `CREATE TABLE usage_requests (run_id TEXT NOT NULL, sequence INTEGER NOT NULL, request_index INTEGER NOT NULL,
+        at TEXT NOT NULL, day TEXT NOT NULL, account_id TEXT, project_id TEXT, session_id TEXT NOT NULL,
+        agent_id TEXT, mode TEXT NOT NULL, trigger TEXT, provider TEXT, model TEXT,
+        input_tokens INTEGER NOT NULL DEFAULT 0, cache_read_tokens INTEGER NOT NULL DEFAULT 0,
+        cache_write_tokens INTEGER NOT NULL DEFAULT 0, output_tokens INTEGER NOT NULL DEFAULT 0,
+        reasoning_tokens INTEGER NOT NULL DEFAULT 0, cost_usd REAL, cost_source TEXT,
+        context_tokens INTEGER, context_window INTEGER, duration_ms INTEGER, ttft_ms INTEGER,
+        requests INTEGER NOT NULL DEFAULT 0,
+        PRIMARY KEY (run_id, sequence, request_index));
+     CREATE INDEX usage_at ON usage_requests (at);
+     CREATE INDEX usage_day ON usage_requests (day);
+     CREATE INDEX usage_account_day ON usage_requests (account_id, day);
+     CREATE INDEX usage_session_day ON usage_requests (session_id, day);
+     CREATE INDEX usage_model_day ON usage_requests (model, day);
+     CREATE TABLE usage_indexed (run_id TEXT PRIMARY KEY, indexed_at TEXT NOT NULL, rows INTEGER NOT NULL);`
+];
+const connections = new Map();
+export function dbPath(root) {
+    return join(root, 'index.sqlite');
+}
+function sqlError(error) {
+    return new HarnessError('index_error', error instanceof Error ? error.message : String(error), 'Settings → Projects and Storage → Repair index.');
+}
+function schemaVersion(database) {
+    database.exec('CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);');
+    const row = database.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get();
+    const version = Number.parseInt(row?.value ?? '', 10);
+    return Number.isInteger(version) && version >= 0 ? version : 0;
+}
+/** Runs `work` inside one transaction, rolling back if it throws. */
+export function transaction(database, work) {
+    database.exec('BEGIN');
+    try {
+        const result = work();
+        database.exec('COMMIT');
+        return result;
+    }
+    catch (error) {
+        try {
+            database.exec('ROLLBACK');
+        }
+        catch {
+            // The transaction is already gone.
+        }
+        throw error;
+    }
+}
+/**
+ * Applies pending migrations. The database file is copied first; if any migration fails, the
+ * copy is restored and the error is reported.
+ */
+export function migrate(path, migrations) {
+    let database;
+    let current;
+    try {
+        database = new DatabaseSync(path);
+        current = schemaVersion(database);
+    }
+    catch (error) {
+        throw sqlError(error);
+    }
+    if (current >= migrations.length)
+        return database;
+    const backup = `${path.replace(/\.sqlite$/, '')}.sqlite.bak-v${current}`;
+    const hadFile = existsSync(path) && current > 0;
+    if (hadFile) {
+        try {
+            database.exec('PRAGMA wal_checkpoint(TRUNCATE);');
+        }
+        catch {
+            // A checkpoint that cannot run leaves the copy slightly behind, which a rebuild repairs.
+        }
+        copyFileSync(path, backup);
+    }
+    for (let index = current; index < migrations.length; index += 1) {
+        try {
+            transaction(database, () => {
+                database.exec(migrations[index]);
+                database.prepare("INSERT INTO meta (key, value) VALUES ('schema_version', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(String(index + 1));
+            });
+        }
+        catch (error) {
+            database.close();
+            if (hadFile)
+                copyFileSync(backup, path);
+            else
+                rmSync(path, { force: true });
+            throw new HarnessError('migration_failed', `Index migration ${index + 1} failed and the previous index was restored: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return database;
+}
+/** Runs `work` with the shared connection for this data root, opening and migrating it on first use. */
+export function withIndex(root, work) {
+    const path = dbPath(root);
+    let database = connections.get(path);
+    if (!database) {
+        database = migrate(path, MIGRATIONS);
+        try {
+            database.exec('PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON; PRAGMA busy_timeout = 5000;');
+        }
+        catch (error) {
+            database.close();
+            throw sqlError(error);
+        }
+        connections.set(path, database);
+    }
+    try {
+        return work(database);
+    }
+    catch (error) {
+        throw error instanceof HarnessError ? error : sqlError(error);
+    }
+}
+/** Closes this data root's connection, if one is open. */
+export function closeIndex(root) {
+    const path = dbPath(root);
+    connections.get(path)?.close();
+    connections.delete(path);
+}
+/** Closes the connection and removes the index files; the next use rebuilds the schema. */
+export function deleteIndex(root) {
+    closeIndex(root);
+    for (const suffix of ['', '-wal', '-shm'])
+        rmSync(`${dbPath(root)}${suffix}`, { force: true });
+}
+export function all(database, sql, ...params) {
+    return database.prepare(sql).all(...params);
+}
+export function run(database, sql, ...params) {
+    database.prepare(sql).run(...params);
+}
+/** Folder names under `<data root>/runs`. */
+export function runFolders(root) {
+    try {
+        return readdirSync(join(root, 'runs'));
+    }
+    catch {
+        return [];
+    }
+}
+/** Turns free text into an FTS5 query: each word becomes a quoted prefix term. */
+export function ftsQuery(query) {
+    const terms = query.split(/[^\p{Alphabetic}\p{N}]+/u).filter(Boolean).map((term) => `"${term.replaceAll('"', '')}"*`);
+    return terms.length ? terms.join(' ') : null;
+}

package/dist/sdk/core/interactiveProfile.d.ts

@@ -0,0 +1,46 @@
+import { type SecretStore } from "../accounts/secrets.js";
+export type SecretBackendDescriptor = {
+    kind: 'file';
+    path: string;
+} | {
+    kind: 'host';
+    id: string;
+};
+export interface InteractiveProfile {
+    version: 1;
+    dataRoot: string;
+    stateDir: string;
+    defaultVariantScope: string;
+    secretBackend: SecretBackendDescriptor;
+}
+export type InteractiveProfileOverrides = Partial<Omit<InteractiveProfile, 'version'>>;
+export interface InteractiveProfileLocation {
+    /** Overrides the home used for the default profile path. */
+    home?: string;
+    /** Selects a profile file directly, without searching any application-specific locations. */
+    configPath?: string;
+}
+/** Strict, bounded, credential-free configuration. Unknown fields are errors, not ignored secrets. */
+export declare function validateInteractiveProfile(value: unknown): InteractiveProfile;
+export declare function interactiveProfilePath(home?: string): string;
+/** Read only. Missing is legacy mode; malformed or inaccessible is never silently ignored. */
+export declare function readInteractiveProfile(location?: InteractiveProfileLocation): InteractiveProfile | null;
+/** Explicit roots > selected profile > caller's legacy defaults. Never creates roots or merges data. */
+export declare function resolveInteractiveProfile(options?: InteractiveProfileLocation & {
+    legacyDefaults?: InteractiveProfileOverrides;
+    overrides?: InteractiveProfileOverrides;
+}): InteractiveProfile;
+/**
+ * Explicit adoption only. Creates the profile file, never roots or credentials; it never replaces
+ * an existing profile or merges data. A pre-profile host must supply its selected backend in
+ * `legacyDefaults` so an absent profile cannot silently downgrade it to the file store.
+ */
+export declare function adoptInteractiveProfile(profile: InteractiveProfile, location?: InteractiveProfileLocation): void;
+/**
+ * Every participating process must map this host id to the same credential store. The account
+ * lock serializes access but cannot unify distinct native Keychain identities; no file fallback is
+ * allowed when a selected host adapter is unavailable.
+ */
+export declare function interactiveProfileSecretStore(profile: InteractiveProfile, host?: (descriptor: Extract<SecretBackendDescriptor, {
+    kind: 'host';
+}>) => SecretStore | Promise<SecretStore>): Promise<SecretStore>;