@aitne/daemon 0.1.8 → 0.1.10

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;
+};