@aitne/daemon 0.1.8 → 0.1.9

package/dist/db/managed-chromium-sites-store.js

@@ -0,0 +1,174 @@
+/**
+ * Per-site authenticated-session state store for Instance A
+ * (Phase B-2.5).
+ *
+ * MANAGED_CHROMIUM_IMPLEMENTATION_PLAN.md §16.7.
+ *
+ * Two `runtime_state` keys per site:
+ *   - `managed_chromium.sites.<siteKey>`            — persistent connection
+ *     record. Created by the bootstrap finalize path; read by the
+ *     workflow runner to decide `site_not_connected` vs proceed.
+ *   - `managed_chromium.site_bootstrap.<siteKey>`   — transient sign-in
+ *     handle. Created when the user clicks "Connect <site>"; cleared
+ *     by finalize / disconnect / orphan-reap.
+ *
+ * No new tables. The §16.7 doc commits explicitly to "All B-2.5 state
+ * fits in runtime_state".
+ */
+import { z } from "zod";
+import { createLogger } from "../logging.js";
+import { deleteRuntimeState, readRuntimeState, writeRuntimeState, } from "./runtime-state.js";
+const logger = createLogger("managed-chromium-sites-store");
+const SITE_KEY_REGEX = /^[a-z][a-z0-9_]*$/;
+const SITES_KEY_PREFIX = "managed_chromium.sites.";
+const SITE_BOOTSTRAP_KEY_PREFIX = "managed_chromium.site_bootstrap.";
+/**
+ * Validate a `siteKey` before composing a runtime_state row key —
+ * registry validation guarantees this for shipping sites, this is the
+ * defence-in-depth path-shape contract for anything that builds the
+ * composite runtime_state key from external input (route params).
+ */
+function assertSiteKey(siteKey) {
+    if (!SITE_KEY_REGEX.test(siteKey)) {
+        throw new Error(`managed-chromium-sites-store: siteKey "${siteKey}" violates naming convention`);
+    }
+}
+export function siteConnectionKey(siteKey) {
+    assertSiteKey(siteKey);
+    return `${SITES_KEY_PREFIX}${siteKey}`;
+}
+export function siteBootstrapKey(siteKey) {
+    assertSiteKey(siteKey);
+    return `${SITE_BOOTSTRAP_KEY_PREFIX}${siteKey}`;
+}
+const siteConnectionSchema = z.object({
+    schemaVersion: z.literal(1),
+    connectedAt: z.number().int().nonnegative(),
+    accountLabel: z.string().max(120).nullable(),
+    lastWorkflowAt: z.number().int().nonnegative().nullable(),
+});
+const siteBootstrapSchema = z.object({
+    pid: z.number().int().positive(),
+    deadlineAt: z.number().int().nonnegative(),
+    reauth: z.boolean(),
+    cdpPort: z.number().int().min(1).max(65535),
+});
+/**
+ * Read the persistent connection record for `siteKey`. Returns null
+ * when the row is absent or fails schema validation — a corrupt row is
+ * treated as "never connected" so the runner reports
+ * `site_not_connected` and the dashboard prompts a fresh sign-in. The
+ * profile dir is unaffected by the read; only the metadata row is
+ * discarded.
+ */
+export function readSiteConnection(db, siteKey) {
+    const raw = readRuntimeState(db, siteConnectionKey(siteKey));
+    if (raw == null)
+        return null;
+    const parsed = siteConnectionSchema.safeParse(raw);
+    if (!parsed.success) {
+        logger.warn({ issues: parsed.error.issues, siteKey }, "managed_chromium site connection row parse failed; treating as disconnected");
+        return null;
+    }
+    return parsed.data;
+}
+export function writeSiteConnection(db, siteKey, value) {
+    const validated = siteConnectionSchema.parse(value);
+    writeRuntimeState(db, siteConnectionKey(siteKey), validated);
+}
+export function clearSiteConnection(db, siteKey) {
+    deleteRuntimeState(db, siteConnectionKey(siteKey));
+}
+/**
+ * Atomic read-modify-write helper used by the runner to advance
+ * `lastWorkflowAt`. Caller's mutator receives a shallow copy and
+ * returns the new value (or void to mutate in place). Writes the
+ * result through the schema so an accidentally-out-of-shape update
+ * fails fast in tests.
+ */
+export function updateSiteConnection(db, siteKey, mutate) {
+    const current = readSiteConnection(db, siteKey);
+    if (!current)
+        return null;
+    const draft = { ...current };
+    const next = mutate(draft) ?? draft;
+    const validated = siteConnectionSchema.parse(next);
+    writeRuntimeState(db, siteConnectionKey(siteKey), validated);
+    return validated;
+}
+export function readSiteBootstrap(db, siteKey) {
+    const raw = readRuntimeState(db, siteBootstrapKey(siteKey));
+    if (raw == null)
+        return null;
+    const parsed = siteBootstrapSchema.safeParse(raw);
+    if (!parsed.success) {
+        logger.warn({ issues: parsed.error.issues, siteKey }, "managed_chromium site bootstrap row parse failed; treating as idle");
+        return null;
+    }
+    return parsed.data;
+}
+export function writeSiteBootstrap(db, siteKey, value) {
+    const validated = siteBootstrapSchema.parse(value);
+    writeRuntimeState(db, siteBootstrapKey(siteKey), validated);
+}
+export function clearSiteBootstrap(db, siteKey) {
+    deleteRuntimeState(db, siteBootstrapKey(siteKey));
+}
+/**
+ * Enumerate every persisted (connection row, siteKey) pair. Used by
+ * the supervisor's orphan reaper to sweep stale bootstrap PIDs across
+ * every connected site without needing a registry import (the reaper
+ * cleans up whatever rows happen to exist, including rows for sites
+ * that were removed from the registry in a later release).
+ *
+ * Returns rows in alphabetical site-key order so output is stable for
+ * tests and audit logs.
+ */
+export function listSiteConnectionKeys(db) {
+    let rows;
+    try {
+        rows = db
+            .prepare(`SELECT key FROM runtime_state
+         WHERE key LIKE ?
+         ORDER BY key ASC`)
+            .all(`${SITES_KEY_PREFIX}%`);
+    }
+    catch (err) {
+        logger.error({ err }, "site-connection enumeration failed");
+        return [];
+    }
+    const out = [];
+    for (const { key } of rows) {
+        const siteKey = key.slice(SITES_KEY_PREFIX.length);
+        if (SITE_KEY_REGEX.test(siteKey))
+            out.push(siteKey);
+    }
+    return out;
+}
+export function listSiteBootstrapKeys(db) {
+    let rows;
+    try {
+        rows = db
+            .prepare(`SELECT key FROM runtime_state
+         WHERE key LIKE ?
+         ORDER BY key ASC`)
+            .all(`${SITE_BOOTSTRAP_KEY_PREFIX}%`);
+    }
+    catch (err) {
+        logger.error({ err }, "site-bootstrap enumeration failed");
+        return [];
+    }
+    const out = [];
+    for (const { key } of rows) {
+        const siteKey = key.slice(SITE_BOOTSTRAP_KEY_PREFIX.length);
+        if (SITE_KEY_REGEX.test(siteKey))
+            out.push(siteKey);
+    }
+    return out;
+}
+export const __testing = {
+    siteConnectionSchema,
+    siteBootstrapSchema,
+    SITES_KEY_PREFIX,
+    SITE_BOOTSTRAP_KEY_PREFIX,
+};

package/dist/db/managed-chromium-state.d.ts

@@ -0,0 +1,58 @@
+import type Database from "better-sqlite3";
+import { z } from "zod";
+import { type ManagedChromiumState } from "../services/browser-history/managed-chromium/types.js";
+/**
+ * Read the singleton managed-chromium state blob. Returns the canonical
+ * default shape when the row is absent or fails schema validation —
+ * corrupt rows are treated as "never written" rather than throwing, so a
+ * malformed runtime_state row cannot brick the daemon's boot path.
+ */
+export declare function readManagedChromiumState(db: Database.Database): ManagedChromiumState;
+/**
+ * Atomic read-modify-write helper. The mutator receives a deep copy and
+ * returns the new value (or void to mutate in place); the resulting
+ * value is validated through the same schema before persistence so an
+ * accidentally-out-of-shape update fails fast in tests.
+ */
+export declare function updateManagedChromiumState(db: Database.Database, mutate: (current: ManagedChromiumState) => ManagedChromiumState | void): ManagedChromiumState;
+/**
+ * Reset to the default shape. Called on disconnect and during the
+ * Danger-Zone context wipe.
+ */
+export declare function clearManagedChromiumState(db: Database.Database): void;
+export declare const __testing: {
+    stateSchema: z.ZodObject<{
+        schemaVersion: z.ZodLiteral<1>;
+        enabled: z.ZodBoolean;
+        state: z.ZodEnum<{
+            off: "off";
+            needs_setup: "needs_setup";
+            missing_binary: "missing_binary";
+            missing_sandbox: "missing_sandbox";
+            ready: "ready";
+            needs_reauth: "needs_reauth";
+            disconnected: "disconnected";
+        }>;
+        signedInUser: z.ZodNullable<z.ZodString>;
+        lastCheckAt: z.ZodNullable<z.ZodNumber>;
+        lastSyncAt: z.ZodNullable<z.ZodNumber>;
+        recentRowCount: z.ZodNullable<z.ZodNumber>;
+        bootstrap: z.ZodNullable<z.ZodObject<{
+            pid: z.ZodNumber;
+            deadlineAt: z.ZodNumber;
+            reauth: z.ZodBoolean;
+        }, z.core.$strip>>;
+        lastDmAt: z.ZodDefault<z.ZodObject<{
+            healthy: z.ZodOptional<z.ZodNumber>;
+            sync_silent: z.ZodOptional<z.ZodNumber>;
+            account_changed: z.ZodOptional<z.ZodNumber>;
+            corrupt_local_state: z.ZodOptional<z.ZodNumber>;
+            signed_out: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        consecutiveFailures: z.ZodNumber;
+        pausedUntil: z.ZodNullable<z.ZodNumber>;
+        unsandboxedOptIn: z.ZodBoolean;
+    }, z.core.$strip>;
+    REAUTH_KINDS: readonly ["healthy", "sync_silent", "account_changed", "corrupt_local_state", "signed_out"];
+    STATE_VALUES: readonly ["off", "needs_setup", "missing_binary", "missing_sandbox", "ready", "needs_reauth", "disconnected"];
+};

package/dist/db/managed-chromium-state.js

@@ -0,0 +1,104 @@
+import { z } from "zod";
+import { DEFAULT_MANAGED_CHROMIUM_STATE, MANAGED_CHROMIUM_STATE_KEY, } from "../services/browser-history/managed-chromium/types.js";
+import { createLogger } from "../logging.js";
+import { deleteRuntimeState, readRuntimeState, writeRuntimeState, } from "./runtime-state.js";
+const logger = createLogger("managed-chromium-state");
+/**
+ * Reauth kinds known to the state shape. Mirrors
+ * `ManagedChromiumReauthKind` — kept in sync via the matching test.
+ */
+const REAUTH_KINDS = [
+    "healthy",
+    "sync_silent",
+    "account_changed",
+    "corrupt_local_state",
+    "signed_out",
+];
+const STATE_VALUES = [
+    "off",
+    "needs_setup",
+    "missing_binary",
+    "missing_sandbox",
+    "ready",
+    "needs_reauth",
+    "disconnected",
+];
+const bootstrapSchema = z.object({
+    pid: z.number().int().positive(),
+    deadlineAt: z.number().int().nonnegative(),
+    reauth: z.boolean(),
+});
+const stateSchema = z.object({
+    schemaVersion: z.literal(1),
+    enabled: z.boolean(),
+    state: z.enum(STATE_VALUES),
+    signedInUser: z.string().nullable(),
+    lastCheckAt: z.number().int().nonnegative().nullable(),
+    lastSyncAt: z.number().int().nonnegative().nullable(),
+    recentRowCount: z.number().int().nonnegative().nullable(),
+    bootstrap: bootstrapSchema.nullable(),
+    // Per-kind DM rate-limit timestamps. Each known kind is optional —
+    // an absent key means "never DMed". Modeled as `z.object({...optional})`
+    // rather than `z.record(z.enum(...), …)` because the latter requires
+    // every enum key to be present in the persisted value to typecheck,
+    // which contradicts the in-memory `Partial<Record<…>>` shape.
+    lastDmAt: z
+        .object({
+        healthy: z.number().int().nonnegative().optional(),
+        sync_silent: z.number().int().nonnegative().optional(),
+        account_changed: z.number().int().nonnegative().optional(),
+        corrupt_local_state: z.number().int().nonnegative().optional(),
+        signed_out: z.number().int().nonnegative().optional(),
+    })
+        .default({}),
+    consecutiveFailures: z.number().int().nonnegative(),
+    pausedUntil: z.number().int().nonnegative().nullable(),
+    unsandboxedOptIn: z.boolean(),
+});
+/**
+ * Read the singleton managed-chromium state blob. Returns the canonical
+ * default shape when the row is absent or fails schema validation —
+ * corrupt rows are treated as "never written" rather than throwing, so a
+ * malformed runtime_state row cannot brick the daemon's boot path.
+ */
+export function readManagedChromiumState(db) {
+    const raw = readRuntimeState(db, MANAGED_CHROMIUM_STATE_KEY);
+    if (raw == null)
+        return { ...DEFAULT_MANAGED_CHROMIUM_STATE };
+    const parsed = stateSchema.safeParse(raw);
+    if (!parsed.success) {
+        logger.warn({ issues: parsed.error.issues }, "managed_chromium state parse failed; using default shape");
+        return { ...DEFAULT_MANAGED_CHROMIUM_STATE };
+    }
+    return parsed.data;
+}
+/**
+ * Atomic read-modify-write helper. The mutator receives a deep copy and
+ * returns the new value (or void to mutate in place); the resulting
+ * value is validated through the same schema before persistence so an
+ * accidentally-out-of-shape update fails fast in tests.
+ */
+export function updateManagedChromiumState(db, mutate) {
+    const current = readManagedChromiumState(db);
+    const draft = {
+        ...current,
+        bootstrap: current.bootstrap ? { ...current.bootstrap } : null,
+        lastDmAt: { ...current.lastDmAt },
+    };
+    const next = mutate(draft) ?? draft;
+    const validated = stateSchema.parse(next);
+    writeRuntimeState(db, MANAGED_CHROMIUM_STATE_KEY, validated);
+    return validated;
+}
+/**
+ * Reset to the default shape. Called on disconnect and during the
+ * Danger-Zone context wipe.
+ */
+export function clearManagedChromiumState(db) {
+    deleteRuntimeState(db, MANAGED_CHROMIUM_STATE_KEY);
+}
+export const __testing = {
+    stateSchema,
+    REAUTH_KINDS,
+    STATE_VALUES,
+};

package/dist/db/managed-tasks-store.d.ts

@@ -127,4 +127,3 @@ export declare function deleteManagedTask(db: Database.Database, id: string): bo
  * registration time (§10.1 step 2).
  */
 export declare function findManagedTaskByAppCadence(db: Database.Database, app: string, cadence: string): ManagedTask | null;
-//# sourceMappingURL=managed-tasks-store.d.ts.map

package/dist/db/managed-tasks-store.js

@@ -235,4 +235,3 @@ export function findManagedTaskByAppCadence(db, app, cadence) {
         .get(normalizeAppLabel(app), cadence);
     return row ? rowToManagedTask(row) : null;
 }
-//# sourceMappingURL=managed-tasks-store.js.map

package/dist/db/management-parse-failures-store.d.ts

@@ -42,4 +42,3 @@ export declare function listManagementParseFailures(db: Database.Database, limit
  */
 export declare function clearManagementParseFailures(db: Database.Database): number;
 export {};
-//# sourceMappingURL=management-parse-failures-store.d.ts.map

package/dist/db/management-parse-failures-store.js

@@ -33,4 +33,3 @@ export function clearManagementParseFailures(db) {
     const result = db.prepare("DELETE FROM management_parse_failures").run();
     return result.changes;
 }
-//# sourceMappingURL=management-parse-failures-store.js.map

package/dist/db/migrations/context-vault-restructure.d.ts

@@ -0,0 +1,263 @@
+/**
+ * Context vault restructure — manifest-driven filesystem + SQLite
+ * migration that reshapes `~/.personal-agent/context/` into the six
+ * authority-class layout (CONTEXT_VAULT_REDESIGN_PLAN.md §11).
+ *
+ * Triggered from the standard `db/migrations.ts:runMigrations` runner
+ * via the `0004-context-vault-restructure` entry. The runner gives us a
+ * `MigrationContext` with `db`, `dataDir`, and `contextDir` so the body
+ * can touch the filesystem in addition to SQLite.
+ *
+ * **Two layers of idempotency** (§11.10):
+ *
+ *  1. `schema_migrations` row — once written, the standard runner skips
+ *     this body.
+ *  2. `<contextDir>/.context-vault-version` — written last by the body
+ *     itself. Survives DB restore-from-backup scenarios where the row
+ *     would otherwise wrongly mark the migration as applied. The
+ *     post-migration boot preflight (`assertContextVaultVersion`)
+ *     re-runs the body if the marker is missing but the row exists.
+ *
+ * **Per-entry idempotency**: each manifest row uses the
+ * `if-from-exists-and-to-does-not` contract. Re-running on a
+ * partially-completed vault skips already-applied entries; a
+ * conflicting both-exist state raises `MigrationConflict` instead of
+ * clobbering data (§11.10).
+ */
+import type Database from "better-sqlite3";
+import { mergeReconcilerBlock } from "../../core/context/reconciler-section.js";
+/**
+ * Version marker file written at `<contextDir>/.context-vault-version`.
+ * `"2"` means "post-restructure layout active". Absent file or `"1"`
+ * means pre-restructure; anything else throws.
+ */
+export declare const VAULT_LAYOUT_VERSION = "2";
+export declare const VAULT_VERSION_FILE = ".context-vault-version";
+/** Migration id — matches `db/migrations.ts:MIGRATIONS`. */
+export declare const MIGRATION_ID = "0004-context-vault-restructure";
+/** Bookkeeping shape returned by the runner for tests + telemetry. */
+export interface ContextVaultMigrationResult {
+    /** True if any filesystem move ran. False on no-op (already migrated). */
+    moved: boolean;
+    /** Per-manifest-entry outcomes for audit replay. */
+    entries: Array<{
+        from: string;
+        to: string;
+        outcome: "moved" | "skip-no-source" | "skip-already-applied" | "merged";
+    }>;
+    /** Backup directory written before any move, or `null` on no-op. */
+    backupDir: string | null;
+    /** Number of `wiki_workspaces.root_path` rows updated. */
+    wikiWorkspacesRewritten: number;
+    /** Counts from each SQLite-path-key UPDATE pass (V13). */
+    sqlitePathKeysRewritten: {
+        mdFileSnapshots: number;
+        entities: number;
+        entitySourceKeys: number;
+        managedTasks: number;
+    };
+    /** JSON-blob rewrites by oldPrefix (V17). */
+    jsonBlobRewrites: Array<{
+        oldPrefix: string;
+        newPrefix: string;
+        rowsRewritten: number;
+    }>;
+}
+/**
+ * The manifest. Each entry tells the runner how to translate one
+ * legacy path into its canonical class-prefixed destination.
+ *
+ * **Kinds**:
+ *  - `file` — move a single file. `from` and `to` are vault-relative.
+ *  - `dir-rename` — atomically rename a single directory.
+ *  - `fanout` — slug-bearing pattern. `from` has a `*` segment; the
+ *    runner enumerates direct children of `from` (sans `*`) and emits
+ *    one move per match. `to`'s `*` is replaced with the same slug.
+ *  - `merge` — move the source into a reserved block inside the target
+ *    rather than replacing it (currently only `context-index.md` →
+ *    `_index.md` `<!-- reconciler-section -->`).
+ */
+export type MoveEntry = {
+    kind: "file";
+    from: string;
+    to: string;
+} | {
+    kind: "dir-rename";
+    from: string;
+    to: string;
+} | {
+    kind: "fanout";
+    from: string;
+    to: string;
+} | {
+    kind: "merge";
+    from: string;
+    to: string;
+    strategy: "reconciler-block";
+};
+/** §11.9 manifest. Longest-prefix-first where multiple entries share a stem. */
+export declare const MOVES: ReadonlyArray<MoveEntry>;
+/**
+ * Recognised management domains (mirrors
+ * `packages/shared/src/management-domains.ts`). The fanout runner only
+ * expands the `{domain}` placeholder against this list — arbitrary
+ * top-level directories the user may have under the vault root are
+ * preserved as-is.
+ */
+export declare const MANAGEMENT_DOMAINS: readonly ["work", "travel", "finance", "personal", "health", "learning"];
+export declare class MigrationConflict extends Error {
+    readonly entry: MoveEntry;
+    readonly fromAbs: string;
+    readonly toAbs: string;
+    constructor(entry: MoveEntry, fromAbs: string, toAbs: string);
+}
+export declare class VerificationFailed extends Error {
+    constructor(detail: string);
+}
+/**
+ * Entry point invoked from the `MIGRATIONS[].up()` body.
+ *
+ * **Order**:
+ *  1. Read the version marker → fast no-op if `=== "2"`.
+ *  2. Plan moves against the manifest; identify what needs to run.
+ *  3. Take backup (only if at least one move is queued).
+ *  4. Run filesystem moves (per-entry idempotency).
+ *  5. Move out-of-contextDir paths: `integrations.md`, internal wiki,
+ *     user skills, skill curation overlays.
+ *  6. UPDATE wiki_workspaces.root_path + rebuild fts_wiki.
+ *  7. UPDATE V13 typed path columns.
+ *  8. Run V17 JSON-blob rewrites via `rewritePathsInDb`.
+ *  9. Run §11.11 verification sweep (incl. step 7 V17 second-pass).
+ * 10. Write `.context-vault-version=2`.
+ */
+export declare function runContextVaultRestructure(args: {
+    db: Database.Database;
+    dataDir: string;
+    contextDir: string;
+}): ContextVaultMigrationResult;
+/**
+ * True if `abs` is a directory whose tree contains zero files — only
+ * (possibly nested) empty directories.
+ *
+ * `initDirectories` mkdirs every entry in `CONTEXT_DIR_NAMES`, including
+ * nested ones like `policies/routines` AND `policies/routines/custom`.
+ * On boot the target of a manifest `dir-rename` like `routines →
+ * policies/routines` therefore comes with `custom/` already inside it
+ * (also empty). That isn't a real conflict — no user data is at risk —
+ * so we walk the tree and only the presence of an actual file
+ * disqualifies the directory as "empty for migration purposes".
+ */
+declare function isEmptyDirectory(abs: string): boolean;
+/**
+ * Expand fanout / placeholder entries into concrete (from, to) pairs.
+ */
+declare function expandEntry(entry: MoveEntry, contextDir: string): Array<{
+    from: string;
+    to: string;
+}>;
+export { mergeReconcilerBlock };
+interface OutOfContextMove {
+    from: string;
+    to: string;
+    /** Set after `executeOutOfContextMove` runs. */
+    applied: boolean;
+    /** `dir` for directory contents move, `file` for single file. */
+    kind: "file" | "dir";
+}
+declare function planOutOfContextDirMoves(args: {
+    dataDir: string;
+    contextDir: string;
+}): OutOfContextMove[];
+interface InternalWikiMove {
+    workspaceId: number;
+    oldRoot: string;
+    newRoot: string;
+}
+declare function planInternalWikiMoves(args: {
+    dataDir: string;
+    contextDir: string;
+    db: Database.Database;
+}): InternalWikiMove[];
+declare function translateSnapshotStem(stem: string): string | null;
+/**
+ * Translate `entities.path` / `entity_source_keys.path` /
+ * `managed_tasks.output_path` legacy spellings to the new
+ * `knowledge/entities/<domain>/...` layout. Returns `null` if no
+ * translation applies — caller leaves the row untouched.
+ */
+declare function translateEntityPath(path: string): string | null;
+/**
+ * Build the `(oldPrefix, newPrefix)` pair list for `rewritePathsInDb`.
+ * The order is longest-prefix-first so `<contextDir>/rules/policies`
+ * rewrites before `<contextDir>/rules`. The list is derived
+ * programmatically from the MOVES manifest plus the out-of-contextDir
+ * moves so it stays in lockstep with the source of truth.
+ */
+export declare function buildAbsolutePathRewrites(args: {
+    dataDir: string;
+    contextDir: string;
+}): Array<readonly [string, string]>;
+declare function verifyMigrationCompleteness(args: {
+    contextDir: string;
+    dataDir: string;
+    db: Database.Database;
+    absoluteRewrites: ReadonlyArray<readonly [string, string]>;
+}): void;
+interface UnmanifestedCapture {
+    from: string;
+    to: string;
+}
+/**
+ * §11.9 "no omissions" safety net. After the manifest loop runs, walk every
+ * legacy top-level entry still surviving with content. Anything left over
+ * is **user-added** (the manifest covers every shape we ship). Rather than
+ * silently dropping it or failing the verifier, copy each entry into
+ * `state/scratch/legacy-unmanifested-<date>-<slug>.md` so the user can
+ * recover it. The source entry is then removed so `removeEmptyLegacyDirs`
+ * + the verifier can complete.
+ *
+ * Files are inlined as Markdown code-fence blocks; directory trees are
+ * flattened into a single artifact per file under the parent name.
+ */
+declare function captureUnmanifestedEntries(contextDir: string): UnmanifestedCapture[];
+/**
+ * Best-effort removal of empty legacy parent directories. After a
+ * `rename` move the source filename disappears but its parent dir
+ * remains as an empty husk; this helper sweeps the known parents.
+ *
+ * Non-empty dirs are preserved (the verifier catches them and raises
+ * VerificationFailed). Removal errors are swallowed — the next boot
+ * will retry, and a stuck non-empty dir surfaces at verification.
+ */
+declare function removeEmptyLegacyDirs(contextDir: string): void;
+/**
+ * Boot-time preflight (§11.10 #2). Compares the filesystem marker against
+ * the `schema_migrations` row. Returns the action the caller should take.
+ */
+export type VaultVersionAction = "noop" | "run-migration" | "throw-unknown-version";
+export declare function assessVaultVersion(args: {
+    contextDir: string;
+}): {
+    action: VaultVersionAction;
+    observedVersion: string | null;
+};
+/**
+ * Internal helpers surfaced for the peer test only. These are pure-ish
+ * units (path translation, manifest expansion, the verification sweep,
+ * the unmanifested-capture safety net) whose individual branches are
+ * awkward to drive through the full `runContextVaultRestructure` orchestrator
+ * — exposing them lets the test exercise each branch directly. Runtime
+ * callers must continue to go through the exported entry points above.
+ */
+export declare const __testing: {
+    verifyMigrationCompleteness: typeof verifyMigrationCompleteness;
+    expandEntry: typeof expandEntry;
+    isEmptyDirectory: typeof isEmptyDirectory;
+    captureUnmanifestedEntries: typeof captureUnmanifestedEntries;
+    removeEmptyLegacyDirs: typeof removeEmptyLegacyDirs;
+    translateSnapshotStem: typeof translateSnapshotStem;
+    translateEntityPath: typeof translateEntityPath;
+    planOutOfContextDirMoves: typeof planOutOfContextDirMoves;
+    planInternalWikiMoves: typeof planInternalWikiMoves;
+    VerificationFailed: typeof VerificationFailed;
+};