@astragenie/astramemory-local 0.7.2

package/dist/cli/reembed-dim.js

@@ -0,0 +1,199 @@
+/**
+ * `astramem-local reembed-dim --dim <N> [--yes] [--batch-size N] [--json]`
+ *
+ * FEAT-409 AC-4 — resumable procedure for changing the embedding dimension
+ * on an EXISTING database with live data. See docs/embed-dim-migration.md
+ * for the full runbook (backup-first, stop-daemon, run, restart sequence).
+ *
+ * WHY this can't be a plain schema migration: sqlite-vec's `memories_vec`
+ * vec0 virtual table bakes its dim into `CREATE VIRTUAL TABLE ... FLOAT[N]`
+ * DDL — there is no ALTER for it. Changing dim therefore means:
+ *   1. Recreating `memories_vec` at the new dim (DESTRUCTIVE — drops every
+ *      existing vector). This is why a pre-change backup is the rollback
+ *      (AC-4): there is no in-place undo once this step runs.
+ *   2. Re-embedding every memory's text with the newly-configured provider
+ *      and upserting into the recreated table.
+ *
+ * RESUMABILITY: migration 011 added `dim_migration_progress`, a checkpoint
+ * table keyed by (memory_id, target_dim). Step 2 commits a checkpoint row
+ * right after each memory's vec upsert, so an interrupted run (Ctrl+C,
+ * crash, a transient Ollama/Azure failure) resumes on the next invocation
+ * by skipping memory ids already checkpointed for this target dim — no
+ * re-work, no memory permanently stuck without a vector. Step 1 (the
+ * destructive recreate) only runs once per target dim: it is skipped
+ * whenever a checkpoint row for that target dim already exists, which is
+ * exactly the signal that step 1 already ran for this target.
+ *
+ * `runReembedDim` is the testable core (no process.exit, no config.yaml
+ * I/O, injectable embed provider). `reembedDimCommand` is the CLI wrapper:
+ * arg parsing, confirmation prompt, config.yaml persistence, exit codes.
+ */
+import { join } from 'node:path';
+import { resolveRuntimeConfig } from '../config/resolve-runtime.js';
+import { defaultConfigDir } from '../config/datadir.js';
+import { writeConfig } from '../config/writer.js';
+import { getOrCreateKey } from '../storage/keystore.js';
+import { openDb } from '../storage/db.js';
+import { getProviders } from '../providers/index.js';
+import { makeMockProviders } from '../pipeline/mock-providers.js';
+import { SqliteVecStore } from '../vector/sqlite-vec.js';
+function parseArg(args, flag) {
+    const i = args.indexOf(flag);
+    return i >= 0 ? args[i + 1] : undefined;
+}
+/** Recreate memories_vec at the new dim — destructive, resumability guard
+ * is: only do this when NO checkpoint rows exist yet for target_dim (i.e.
+ * this is the first invocation for this target, not a resume). */
+function maybeRecreateVecSchema(db, targetDim) {
+    const existing = db
+        .prepare('SELECT COUNT(*) AS n FROM dim_migration_progress WHERE target_dim = ?')
+        .get(targetDim);
+    if (existing.n > 0)
+        return false; // resume — schema already recreated
+    db.exec('DROP TABLE IF EXISTS memories_vec');
+    db.exec(`CREATE VIRTUAL TABLE memories_vec USING vec0(embedding FLOAT[${targetDim}])`);
+    return true;
+}
+/**
+ * Testable core: no process.exit, no config.yaml writes, no provider
+ * resolution — the caller supplies `embed` (already verified to produce
+ * `targetDim`-shaped vectors). Safe to call repeatedly against the same DB
+ * for the same targetDim (resumable — see module doc).
+ */
+export async function runReembedDim(db, targetDim, embed, batchSize = 20) {
+    // Same guard migrate() applies (src/storage/migrate.ts) — this is the
+    // exported core function, callable directly by anything that imports it
+    // (not just the CLI wrapper below, which already validates --dim), so it
+    // must be self-guarding rather than trusting the caller to have checked.
+    // Fails fast, before maybeRecreateVecSchema ever interpolates targetDim
+    // into DROP/CREATE VIRTUAL TABLE DDL.
+    if (!Number.isInteger(targetDim) || targetDim <= 0) {
+        throw new Error(`invalid embedding dim: ${targetDim} (must be a positive integer)`);
+    }
+    const schemaRecreated = maybeRecreateVecSchema(db, targetDim);
+    const vecStore = new SqliteVecStore(db, targetDim);
+    const candidates = db
+        .prepare(`
+      SELECT id, text FROM memories
+      WHERE id NOT IN (SELECT memory_id FROM dim_migration_progress WHERE target_dim = ?)
+      ORDER BY created_at ASC
+    `)
+        .all(targetDim);
+    const alreadyDoneBefore = db.prepare('SELECT COUNT(*) AS n FROM dim_migration_progress WHERE target_dim = ?').get(targetDim).n;
+    const failed = [];
+    let reembedded = 0;
+    for (let i = 0; i < candidates.length; i += batchSize) {
+        const batch = candidates.slice(i, i + batchSize);
+        for (const mem of batch) {
+            try {
+                const [vec] = await embed.embed([mem.text]);
+                if (!vec)
+                    throw new Error('embed provider returned no vector');
+                if (vec.length !== targetDim) {
+                    throw new Error(`provider returned dim=${vec.length}, expected ${targetDim}`);
+                }
+                // upsert(), the memories row update, then the checkpoint INSERT —
+                // each is individually atomic (single-statement better-sqlite3
+                // writes). If the process dies between them, resume just re-embeds
+                // this one memory again on the next run: embed+upsert+update is
+                // idempotent, so at-least-once is safe.
+                await vecStore.upsert(mem.id, vec);
+                // Mirror pipeline/handlers/reembed.ts: memories.embedding_* must
+                // track what's actually in memories_vec, or API/MCP callers get a
+                // silent lie about which provider/model/dim produced the vector.
+                db.prepare('UPDATE memories SET embedding_provider = ?, embedding_model = ?, embedding_dim = ?, updated_at = ? WHERE id = ?').run(embed.name, embed.model, targetDim, Date.now(), mem.id);
+                db.prepare('INSERT INTO dim_migration_progress (memory_id, target_dim, completed_at) VALUES (?, ?, ?)').run(mem.id, targetDim, Date.now());
+                reembedded++;
+            }
+            catch (err) {
+                failed.push({ memoryId: mem.id, error: err instanceof Error ? err.message : String(err) });
+            }
+        }
+    }
+    return {
+        targetDim,
+        totalCandidates: candidates.length,
+        alreadyDone: alreadyDoneBefore,
+        reembedded,
+        failed,
+        schemaRecreated,
+    };
+}
+export async function reembedDimCommand(args) {
+    const jsonMode = args.includes('--json');
+    const yes = args.includes('--yes');
+    const dimArg = parseArg(args, '--dim');
+    const batchArg = parseArg(args, '--batch-size');
+    const batchSize = batchArg ? Math.max(1, Number(batchArg)) : 20;
+    const targetDim = dimArg !== undefined ? Number(dimArg) : NaN;
+    if (!Number.isInteger(targetDim) || targetDim <= 0) {
+        console.error('reembed-dim: --dim <positive integer> is required');
+        process.exit(1);
+    }
+    const { cfg, dataDir } = resolveRuntimeConfig();
+    const dbPath = dataDir === ':memory:' ? ':memory:' : join(dataDir, 'memory.sqlite');
+    if (!yes && !jsonMode) {
+        console.log('');
+        console.log('  AstraMemory Reembed-Dim');
+        console.log('  ──────────────────────────────');
+        console.log(`  Target dim   : ${targetDim} (current config: ${cfg.embedding.dim})`);
+        console.log(`  Data dir     : ${dataDir}`);
+        console.log('  This DROPS and recreates memories_vec — all existing vectors are');
+        console.log('  discarded, then every memory is re-embedded with the configured provider.');
+        console.log('  A pre-change backup (`astramem-local backup`) is your rollback — there is');
+        console.log('  no undo once the schema recreate step runs.');
+        console.log('  Re-run with --yes to proceed (safe to Ctrl+C and resume — see docs/embed-dim-migration.md).');
+        console.log('');
+        process.exit(1);
+    }
+    const key = cfg.security.encryption.enabled ? getOrCreateKey(defaultConfigDir()).key : undefined;
+    const db = openDb(dbPath, key ? { key } : {});
+    // New config with the target dim — used both to persist config.yaml AND
+    // to build the embed provider that will actually produce target-dim
+    // vectors below (provider.dim flows from config.embedding.dim, FEAT-409).
+    const newCfg = { ...cfg, embedding: { ...cfg.embedding, dim: targetDim } };
+    const useMock = process.env.ASTRA_MEMORY_MOCK_PROVIDERS === '1';
+    const embed = useMock ? makeMockProviders(targetDim).embed : getProviders(newCfg).embed;
+    if (embed.dim !== targetDim) {
+        console.error(`reembed-dim: configured provider (${embed.name}/${embed.model}) produces dim=${embed.dim}, ` +
+            `not the requested --dim ${targetDim}. Update config.embedding.model to a model that ` +
+            `natively produces ${targetDim} dims (or one that supports it via a dimensions param) before retrying.`);
+        db.close();
+        process.exit(1);
+    }
+    const result = await runReembedDim(db, targetDim, embed, batchSize);
+    // Persist the new dim (+ provider/model already matched above) so the
+    // next daemon boot's preflight (AC-3) sees a config that matches the
+    // schema we just recreated. Skipped for :memory: (no real config to
+    // update — dev/test throwaway state, same guard the sync shipper uses).
+    let configPath;
+    if (dataDir !== ':memory:') {
+        configPath = join(defaultConfigDir(), 'config.yaml');
+        writeConfig(newCfg, configPath);
+    }
+    db.close();
+    if (jsonMode) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        console.log('');
+        console.log('  AstraMemory Reembed-Dim — complete');
+        console.log('  ──────────────────────────────');
+        console.log(`  Target dim        : ${targetDim}`);
+        console.log(`  Schema recreated  : ${result.schemaRecreated ? 'yes (fresh run)' : 'no (resumed run)'}`);
+        console.log(`  Already done      : ${result.alreadyDone}`);
+        console.log(`  Reembedded now    : ${result.reembedded}`);
+        console.log(`  Failed            : ${result.failed.length}`);
+        if (result.failed.length > 0) {
+            console.log('  Re-run this command to retry failed memories (resumable).');
+        }
+        if (configPath) {
+            console.log(`  config.yaml updated: embedding.dim=${targetDim} at ${configPath}`);
+            console.log('  Restart the daemon (`astramem-local reinstall` or `service restart`) to pick this up.');
+        }
+        console.log('');
+    }
+    if (result.failed.length > 0)
+        process.exit(1);
+}
+//# sourceMappingURL=reembed-dim.js.map

package/dist/cli/reembed-dim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reembed-dim.js","sourceRoot":"","sources":["../../src/cli/reembed-dim.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,MAAM,EAAW,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAIzD,SAAS,QAAQ,CAAC,IAAc,EAAE,IAAY;IAC5C,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC1C,CAAC;AAWD;;kEAEkE;AAClE,SAAS,sBAAsB,CAAC,EAAM,EAAE,SAAiB;IACvD,MAAM,QAAQ,GAAG,EAAE;SAChB,OAAO,CAAC,uEAAuE,CAAC;SAChF,GAAG,CAAC,SAAS,CAAkB,CAAC;IACnC,IAAI,QAAQ,CAAC,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC,CAAC,oCAAoC;IAEtE,EAAE,CAAC,IAAI,CAAC,mCAAmC,CAAC,CAAC;IAC7C,EAAE,CAAC,IAAI,CAAC,gEAAgE,SAAS,IAAI,CAAC,CAAC;IACvF,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,EAAM,EACN,SAAiB,EACjB,KAAoB,EACpB,SAAS,GAAG,EAAE;IAEd,sEAAsE;IACtE,wEAAwE;IACxE,yEAAyE;IACzE,yEAAyE;IACzE,wEAAwE;IACxE,sCAAsC;IACtC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;QACnD,MAAM,IAAI,KAAK,CAAC,0BAA0B,SAAS,+BAA+B,CAAC,CAAC;IACtF,CAAC;IAED,MAAM,eAAe,GAAG,sBAAsB,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;IAC9D,MAAM,QAAQ,GAAG,IAAI,cAAc,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;IAEnD,MAAM,UAAU,GAAG,EAAE;SAClB,OAAO,CAAC;;;;KAIR,CAAC;SACD,GAAG,CAAC,SAAS,CAAwC,CAAC;IAEzD,MAAM,iBAAiB,GACrB,EAAE,CAAC,OAAO,CAAC,uEAAuE,CAAC,CAAC,GAAG,CAAC,SAAS,CAClG,CAAC,CAAC,CAAC;IAEJ,MAAM,MAAM,GAA+C,EAAE,CAAC;IAC9D,IAAI,UAAU,GAAG,CAAC,CAAC;IAEnB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC,IAAI,SAAS,EAAE,CAAC;QACtD,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC;QACjD,KAAK,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC;YACxB,IAAI,CAAC;gBACH,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;gBAC5C,IAAI,CAAC,GAAG;oBAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;gBAC/D,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;oBAC7B,MAAM,IAAI,KAAK,CAAC,yBAAyB,GAAG,CAAC,MAAM,cAAc,SAAS,EAAE,CAAC,CAAC;gBAChF,CAAC;gBACD,kEAAkE;gBAClE,+DAA+D;gBAC/D,mEAAmE;gBACnE,gEAAgE;gBAChE,wCAAwC;gBACxC,MAAM,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;gBACnC,iEAAiE;gBACjE,kEAAkE;gBAClE,iEAAiE;gBACjE,EAAE,CAAC,OAAO,CACR,iHAAiH,CAClH,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;gBAC9D,EAAE,CAAC,OAAO,CACR,2FAA2F,CAC5F,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;gBACrC,UAAU,EAAE,CAAC;YACf,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,EAAE,EAAE,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC7F,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO;QACL,SAAS;QACT,eAAe,EAAE,UAAU,CAAC,MAAM;QAClC,WAAW,EAAE,iBAAiB;QAC9B,UAAU;QACV,MAAM;QACN,eAAe;KAChB,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,IAAc;IACpD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACzC,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACnC,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACvC,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;IAChD,MAAM,SAAS,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAEhE,MAAM,SAAS,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IAC9D,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;QACnD,OAAO,CAAC,KAAK,CAAC,mDAAmD,CAAC,CAAC;QACnE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,oBAAoB,EAAE,CAAC;IAChD,MAAM,MAAM,GAAG,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;IAEpF,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;QACtB,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChB,OAAO,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;QACzC,OAAO,CAAC,GAAG,CAAC,kCAAkC,CAAC,CAAC;QAChD,OAAO,CAAC,GAAG,CAAC,oBAAoB,SAAS,qBAAqB,GAAG,CAAC,SAAS,CAAC,GAAG,GAAG,CAAC,CAAC;QACpF,OAAO,CAAC,GAAG,CAAC,oBAAoB,OAAO,EAAE,CAAC,CAAC;QAC3C,OAAO,CAAC,GAAG,CAAC,oEAAoE,CAAC,CAAC;QAClF,OAAO,CAAC,GAAG,CAAC,6EAA6E,CAAC,CAAC;QAC3F,OAAO,CAAC,GAAG,CAAC,6EAA6E,CAAC,CAAC;QAC3F,OAAO,CAAC,GAAG,CAAC,+CAA+C,CAAC,CAAC;QAC7D,OAAO,CAAC,GAAG,CAAC,+FAA+F,CAAC,CAAC;QAC7G,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,GAAG,GAAG,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,cAAc,CAAC,gBAAgB,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;IACjG,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAE9C,wEAAwE;IACxE,oEAAoE;IACpE,0EAA0E;IAC1E,MAAM,MAAM,GAAW,EAAE,GAAG,GAAG,EAAE,SAAS,EAAE,EAAE,GAAG,GAAG,CAAC,SAAS,EAAE,GAAG,EAAE,SAAS,EAAE,EAAE,CAAC;IACnF,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,2BAA2B,KAAK,GAAG,CAAC;IAChE,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC;IACxF,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO,CAAC,KAAK,CACX,qCAAqC,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,KAAK,kBAAkB,KAAK,CAAC,GAAG,IAAI;YAC7F,2BAA2B,SAAS,kDAAkD;YACtF,qBAAqB,SAAS,yEAAyE,CACxG,CAAC;QACF,EAAE,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;IAEpE,sEAAsE;IACtE,qEAAqE;IACrE,oEAAoE;IACpE,wEAAwE;IACxE,IAAI,UAA8B,CAAC;IACnC,IAAI,OAAO,KAAK,UAAU,EAAE,CAAC;QAC3B,UAAU,GAAG,IAAI,CAAC,gBAAgB,EAAE,EAAE,aAAa,CAAC,CAAC;QACrD,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAClC,CAAC;IAED,EAAE,CAAC,KAAK,EAAE,CAAC;IAEX,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAC/C,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChB,OAAO,CAAC,GAAG,CAAC,sCAAsC,CAAC,CAAC;QACpD,OAAO,CAAC,GAAG,CAAC,kCAAkC,CAAC,CAAC;QAChD,OAAO,CAAC,GAAG,CAAC,yBAAyB,SAAS,EAAE,CAAC,CAAC;QAClD,OAAO,CAAC,GAAG,CAAC,yBAAyB,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,kBAAkB,EAAE,CAAC,CAAC;QACxG,OAAO,CAAC,GAAG,CAAC,yBAAyB,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;QAC3D,OAAO,CAAC,GAAG,CAAC,yBAAyB,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;QAC1D,OAAO,CAAC,GAAG,CAAC,yBAAyB,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QAC7D,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC7B,OAAO,CAAC,GAAG,CAAC,6DAA6D,CAAC,CAAC;QAC7E,CAAC;QACD,IAAI,UAAU,EAAE,CAAC;YACf,OAAO,CAAC,GAAG,CAAC,wCAAwC,SAAS,OAAO,UAAU,EAAE,CAAC,CAAC;YAClF,OAAO,CAAC,GAAG,CAAC,yFAAyF,CAAC,CAAC;QACzG,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAClB,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAChD,CAAC"}

package/dist/cli/reinstall.d.ts

@@ -0,0 +1 @@
+export declare function reinstallCommand(args: string[]): Promise<void>;

package/dist/cli/reinstall.js

@@ -0,0 +1,205 @@
+/**
+ * reinstall.ts — `astramem-local reinstall` (D4).
+ *
+ * The one command that always works: fully non-interactive, idempotent, every
+ * failure surfaced verbatim. Run it after every upgrade (git pull + build) or
+ * whenever the service is in a weird state.
+ *
+ * Sequence:
+ *   1. resolve current build (refuse if dist/ missing)
+ *   2. resolve runtime config + print provenance of each value
+ *   3. stop any running daemon (via daemon.lock PID)
+ *   4. write shim + register scheduler task (single shared install path)
+ *   5. start the service
+ *   6. wait for /health, assert served version === this build's version
+ *      (catches a stale global install shadowing the repo build)
+ *   7. config sanity warnings (legacy dirs, plaintext backups, dataDir drift)
+ *
+ * Exit codes: 0 = healthy end-state; 1 = any step failed.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { resolveRuntimeConfig } from '../config/resolve-runtime.js';
+import { legacyDataDir, legacyConfigDir } from '../config/datadir.js';
+import { installServiceFlow } from '../service/install-flow.js';
+import { readLockInfo } from '../service/instance-lock.js';
+import { waitForHealth } from './wait-health.js';
+import { PKG_VERSION } from '../server/lib/wire-meta.js';
+function hasFlag(args, flag) {
+    return args.includes(flag);
+}
+async function stopRunningDaemon(dataDir, port) {
+    const holder = readLockInfo(dataDir);
+    if (!holder)
+        return { step: 'stop-daemon', ok: true, detail: 'no daemon.lock — nothing to stop' };
+    let alive = true;
+    try {
+        process.kill(holder.pid, 0);
+    }
+    catch {
+        alive = false;
+    }
+    if (!alive)
+        return { step: 'stop-daemon', ok: true, detail: `stale lock (pid ${holder.pid} dead)` };
+    try {
+        // SIGTERM runs the daemon's graceful shutdown; on Windows Node this
+        // terminates the process (no handler runs), which is still acceptable —
+        // boot job-recovery handles interrupted work.
+        process.kill(holder.pid, 'SIGTERM');
+    }
+    catch (err) {
+        return { step: 'stop-daemon', ok: false, detail: `kill pid ${holder.pid} failed: ${err.message}` };
+    }
+    // Wait up to 5s for the port to go quiet.
+    const deadline = Date.now() + 5000;
+    while (Date.now() < deadline) {
+        try {
+            await fetch(`http://127.0.0.1:${holder.port ?? port}/health`, { signal: AbortSignal.timeout(500) });
+            await new Promise(r => setTimeout(r, 250));
+        }
+        catch {
+            return { step: 'stop-daemon', ok: true, detail: `stopped pid ${holder.pid}` };
+        }
+    }
+    return { step: 'stop-daemon', ok: false, detail: `pid ${holder.pid} still serving after 5s` };
+}
+export async function reinstallCommand(args) {
+    const jsonMode = hasFlag(args, '--json');
+    const steps = [];
+    const log = (s) => { if (!jsonMode)
+        console.log(s); };
+    log(`\nAstraMemory reinstall — v${PKG_VERSION}\n`);
+    // 1+2. Resolve config with provenance.
+    const { port, dataDir, configDir, sources } = resolveRuntimeConfig();
+    log(`  config dir : ${configDir}`);
+    log(`  data dir   : ${dataDir}  (from ${sources.dataDir})`);
+    log(`  port       : ${port}  (from ${sources.port})`);
+    steps.push({ step: 'resolve-config', ok: true, detail: `dataDir=${dataDir} port=${port}` });
+    // 3. Stop any running daemon.
+    const stopResult = await stopRunningDaemon(dataDir, port);
+    steps.push(stopResult);
+    log(`  · stop daemon: ${stopResult.detail}`);
+    if (!stopResult.ok) {
+        finish(steps, jsonMode);
+        return;
+    }
+    // 4. Install (shared flow: shim + scheduler registration).
+    let startFn = null;
+    try {
+        const { result, adapter, build } = await installServiceFlow(port);
+        if (result.kind === 'task') {
+            steps.push({ step: 'install-service', ok: true, detail: 'registered (task)' });
+            log('  · service registered (task)');
+            startFn = () => adapter.start();
+            // W2.4: nightly verified backup by default — a memory daemon without
+            // backups is one disk hiccup away from losing everything.
+            if (!hasFlag(args, '--no-backup-timer')) {
+                try {
+                    await adapter.installBackupTimer(build.rawExecPath, 7);
+                    steps.push({ step: 'install-backup-timer', ok: true, detail: 'nightly 03:00, keep 7, verified' });
+                    log('  · backup timer registered (nightly 03:00, keep 7)');
+                }
+                catch (err) {
+                    // Soft-fail: daemon service matters more than the timer.
+                    steps.push({ step: 'install-backup-timer', ok: false, detail: err.message });
+                    log(`  ⚠ backup timer failed: ${err.message}`);
+                }
+            }
+        }
+        else {
+            // Startup-shortcut fallback: works at next logon but no start/stop
+            // control. Count it as a soft failure so the exit code says "not fully
+            // healthy" — the verbatim tier errors were already printed by install.
+            steps.push({
+                step: 'install-service',
+                ok: false,
+                detail: `fell back to Startup shortcut (${result.path}) — 'service start/stop' unavailable; fix the schtasks errors above`,
+            });
+        }
+    }
+    catch (err) {
+        steps.push({ step: 'install-service', ok: false, detail: err.message });
+        log(`  ✗ install failed: ${err.message}`);
+        finish(steps, jsonMode);
+        return;
+    }
+    // 5. Start.
+    if (startFn) {
+        try {
+            await startFn();
+            steps.push({ step: 'start-service', ok: true });
+            log('  · service started');
+        }
+        catch (err) {
+            steps.push({ step: 'start-service', ok: false, detail: err.message });
+            log(`  ✗ start failed: ${err.message}`);
+        }
+    }
+    // 6. Health + version assertion.
+    const healthy = await waitForHealth(port, 30_000);
+    if (!healthy) {
+        steps.push({ step: 'verify-health', ok: false, detail: `/health not responding on port ${port} within 30s` });
+    }
+    else {
+        try {
+            const res = await fetch(`http://127.0.0.1:${port}/version`, { signal: AbortSignal.timeout(3000) });
+            const body = (await res.json());
+            if (body.version === PKG_VERSION) {
+                steps.push({ step: 'verify-version', ok: true, detail: `daemon serving v${body.version}` });
+                log(`  ✓ daemon healthy, serving v${body.version}`);
+            }
+            else {
+                steps.push({
+                    step: 'verify-version',
+                    ok: false,
+                    detail: `daemon reports v${body.version} but this build is v${PKG_VERSION} — a DIFFERENT install is serving. ` +
+                        `Most common cause: a stale global install (e.g. 'bun install -g' shadowing the repo build). ` +
+                        `Stop the other daemon and re-run reinstall from the build you want.`,
+                });
+            }
+        }
+        catch (err) {
+            steps.push({ step: 'verify-version', ok: false, detail: err.message });
+        }
+    }
+    // 7. Sanity warnings (never fail the run — informational).
+    const warnings = [];
+    const legacyData = legacyDataDir();
+    if (legacyData !== dataDir && existsSync(join(legacyData, 'memory.sqlite'))) {
+        warnings.push(`legacy data dir still holds a database: ${legacyData} — verify it is not the one with your real data`);
+    }
+    const legacyCfg = legacyConfigDir();
+    if (legacyCfg !== configDir && existsSync(legacyCfg)) {
+        warnings.push(`legacy config dir still present: ${legacyCfg}`);
+    }
+    if (existsSync(join(dataDir, 'memory.sqlite.pre-encryption.bak'))) {
+        warnings.push(`plaintext pre-encryption backup present: ${join(dataDir, 'memory.sqlite.pre-encryption.bak')} — delete once the encrypted DB is verified`);
+    }
+    if (sources.dataDir === 'config.yaml') {
+        warnings.push(`dataDir comes from config.yaml and differs from the platform default — intentional? (${dataDir})`);
+    }
+    for (const w of warnings)
+        log(`  ⚠ ${w}`);
+    finish(steps, jsonMode, warnings);
+}
+function finish(steps, jsonMode, warnings = []) {
+    const failed = steps.filter(s => !s.ok);
+    if (jsonMode) {
+        console.log(JSON.stringify({ ok: failed.length === 0, version: PKG_VERSION, steps, warnings }, null, 2));
+    }
+    else {
+        console.log('');
+        if (failed.length === 0) {
+            console.log('✓ reinstall complete — service registered, daemon healthy.');
+        }
+        else {
+            console.log(`✗ reinstall finished with ${failed.length} failed step(s):`);
+            for (const f of failed)
+                console.log(`    ${f.step}: ${f.detail ?? 'failed'}`);
+        }
+        console.log('');
+    }
+    if (failed.length > 0)
+        process.exit(1);
+}
+//# sourceMappingURL=reinstall.js.map

package/dist/cli/reinstall.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reinstall.js","sourceRoot":"","sources":["../../src/cli/reinstall.ts"],"names":[],"mappings":"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"}

package/dist/cli/restore.d.ts

@@ -0,0 +1 @@
+export declare function restoreCommand(args: string[]): Promise<void>;

package/dist/cli/restore.js

@@ -0,0 +1,167 @@
+/**
+ * restore.ts — `astramem-local restore <snapshot>` (W2.2).
+ *
+ * Until now restore was an undocumented manual file copy. This command makes
+ * it safe:
+ *   1. verify the snapshot BEFORE touching anything (integrity_check + key)
+ *   2. stop a running daemon (via daemon.lock, same as reinstall)
+ *   3. set the current DB aside as memory.sqlite.pre-restore.bak (never lost)
+ *   4. swap the snapshot in via copy-to-tmp + atomic rename
+ *   5. run schema migrations (an old snapshot may predate current schema)
+ *   6. restart the service if one is registered, verify /health
+ *
+ * Exit codes: 0 = restored + healthy (or restored, daemon left stopped);
+ * 1 = any failure — the original DB is never deleted.
+ */
+import { existsSync, copyFileSync, renameSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import Database from 'better-sqlite3-multiple-ciphers';
+import { resolveRuntimeConfig } from '../config/resolve-runtime.js';
+import { defaultConfigDir } from '../config/datadir.js';
+import { getOrCreateKey } from '../storage/keystore.js';
+import { readLockInfo } from '../service/instance-lock.js';
+import { getServiceAdapter } from '../service/index.js';
+import { openDb } from '../storage/db.js';
+import { migrate } from '../storage/migrate.js';
+import { waitForHealth } from './wait-health.js';
+function hasFlag(args, flag) {
+    return args.includes(flag);
+}
+async function stopDaemon(dataDir, port) {
+    const holder = readLockInfo(dataDir);
+    if (!holder)
+        return 'no daemon running';
+    let alive = true;
+    try {
+        process.kill(holder.pid, 0);
+    }
+    catch {
+        alive = false;
+    }
+    if (!alive)
+        return `stale lock (pid ${holder.pid} dead)`;
+    process.kill(holder.pid, 'SIGTERM');
+    const deadline = Date.now() + 5000;
+    while (Date.now() < deadline) {
+        try {
+            await fetch(`http://127.0.0.1:${holder.port ?? port}/health`, { signal: AbortSignal.timeout(500) });
+            await new Promise(r => setTimeout(r, 250));
+        }
+        catch {
+            return `stopped pid ${holder.pid}`;
+        }
+    }
+    throw new Error(`daemon pid ${holder.pid} still serving after 5s — stop it manually and retry`);
+}
+/** Standalone integrity probe of a snapshot file (key-aware). */
+function probeSnapshot(path, key) {
+    let db = null;
+    try {
+        db = new Database(path, { readonly: true });
+        if (key)
+            db.pragma(`key='${key.replace(/'/g, "''")}'`);
+        const rows = db.pragma('integrity_check');
+        const verdict = rows.map(r => r.integrity_check).join('; ');
+        return verdict === 'ok' ? { ok: true } : { ok: false, error: `integrity_check: ${verdict}` };
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+    finally {
+        try {
+            db?.close();
+        }
+        catch { /* ignore */ }
+    }
+}
+export async function restoreCommand(args) {
+    const snapshotPath = args.find(a => !a.startsWith('-'));
+    const noRestart = hasFlag(args, '--no-restart');
+    if (!snapshotPath) {
+        console.error('restore: snapshot path required\nUsage: astramem-local restore <snapshot.sqlite> [--no-restart]');
+        process.exit(1);
+    }
+    if (!existsSync(snapshotPath)) {
+        console.error(`restore: snapshot not found: ${snapshotPath}`);
+        process.exit(1);
+    }
+    const { cfg, port, dataDir } = resolveRuntimeConfig();
+    if (dataDir === ':memory:') {
+        console.error('restore: refusing to restore into :memory:');
+        process.exit(1);
+    }
+    const dbPath = join(dataDir, 'memory.sqlite');
+    const key = cfg.security.encryption.enabled ? getOrCreateKey(defaultConfigDir()).key : undefined;
+    console.log(`\nAstraMemory restore\n  snapshot: ${snapshotPath}\n  target  : ${dbPath}\n`);
+    // 1. Verify the snapshot before touching anything.
+    const probe = probeSnapshot(snapshotPath, key);
+    if (!probe.ok) {
+        console.error(`✗ snapshot failed verification: ${probe.error}`);
+        console.error('  Nothing was changed.');
+        process.exit(1);
+    }
+    console.log('  · snapshot integrity: ok');
+    // 2. Stop the daemon.
+    try {
+        console.log(`  · stop daemon: ${await stopDaemon(dataDir, port)}`);
+    }
+    catch (err) {
+        console.error(`✗ ${err.message}`);
+        process.exit(1);
+    }
+    // 3+4. Set current DB aside, swap snapshot in atomically.
+    const asidePath = `${dbPath}.pre-restore.bak`;
+    const tmpPath = `${dbPath}.restoring-tmp`;
+    try {
+        copyFileSync(snapshotPath, tmpPath);
+        if (existsSync(dbPath)) {
+            rmSync(asidePath, { force: true });
+            renameSync(dbPath, asidePath);
+            console.log(`  · current DB set aside: ${asidePath}`);
+            // Stale WAL/SHM belong to the old DB — remove so SQLite doesn't pair
+            // them with the restored file (mismatched WAL corrupts).
+            rmSync(`${dbPath}-wal`, { force: true });
+            rmSync(`${dbPath}-shm`, { force: true });
+        }
+        renameSync(tmpPath, dbPath);
+        console.log('  · snapshot swapped in');
+    }
+    catch (err) {
+        rmSync(tmpPath, { force: true });
+        console.error(`✗ swap failed: ${err.message}`);
+        console.error(`  Original DB ${existsSync(asidePath) ? `is at ${asidePath} — rename it back` : 'was not moved'}.`);
+        process.exit(1);
+    }
+    // 5. Migrations — an older snapshot may predate the current schema.
+    try {
+        const db = openDb(dbPath, key ? { key } : {});
+        migrate(db, cfg.embedding.dim);
+        db.close();
+        console.log('  · schema migrations applied');
+    }
+    catch (err) {
+        console.error(`✗ migration on restored DB failed: ${err.message}`);
+        console.error(`  Roll back: delete ${dbPath} and rename ${asidePath} back.`);
+        process.exit(1);
+    }
+    // 6. Restart service when one is registered.
+    if (!noRestart) {
+        try {
+            const adapter = getServiceAdapter();
+            const status = await adapter.status();
+            if (status.installed) {
+                await adapter.start();
+                const healthy = await waitForHealth(port, 30_000);
+                console.log(healthy ? `  ✓ daemon healthy on :${port}` : `  ⚠ daemon did not report healthy within 30s — check 'astramem-local doctor'`);
+            }
+            else {
+                console.log('  · no service registered — start manually (serve / service start)');
+            }
+        }
+        catch (err) {
+            console.log(`  ⚠ restart failed: ${err.message} — start manually`);
+        }
+    }
+    console.log(`\n✓ restore complete. Previous DB kept at ${asidePath} — delete it once verified.\n`);
+}
+//# sourceMappingURL=restore.js.map

package/dist/cli/restore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"restore.js","sourceRoot":"","sources":["../../src/cli/restore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACvE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,QAAQ,MAAM,iCAAiC,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGjD,SAAS,OAAO,CAAC,IAAc,EAAE,IAAY;IAC3C,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,KAAK,UAAU,UAAU,CAAC,OAAe,EAAE,IAAY;IACrD,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IACrC,IAAI,CAAC,MAAM;QAAE,OAAO,mBAAmB,CAAC;IACxC,IAAI,KAAK,GAAG,IAAI,CAAC;IACjB,IAAI,CAAC;QAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC;QAAC,KAAK,GAAG,KAAK,CAAC;IAAC,CAAC;IAC7D,IAAI,CAAC,KAAK;QAAE,OAAO,mBAAmB,MAAM,CAAC,GAAG,QAAQ,CAAC;IACzD,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IACpC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;IACnC,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;QAC7B,IAAI,CAAC;YACH,MAAM,KAAK,CAAC,oBAAoB,MAAM,CAAC,IAAI,IAAI,IAAI,SAAS,EAAE,EAAE,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACpG,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;QAC7C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,eAAe,MAAM,CAAC,GAAG,EAAE,CAAC;QACrC,CAAC;IACH,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,cAAc,MAAM,CAAC,GAAG,sDAAsD,CAAC,CAAC;AAClG,CAAC;AAED,iEAAiE;AACjE,SAAS,aAAa,CAAC,IAAY,EAAE,GAAY;IAC/C,IAAI,EAAE,GAAc,IAAI,CAAC;IACzB,IAAI,CAAC;QACH,EAAE,GAAG,IAAI,QAAQ,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAO,CAAC;QAClD,IAAI,GAAG;YAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;QACvD,MAAM,IAAI,GAAG,EAAE,CAAC,MAAM,CAAC,iBAAiB,CAAuC,CAAC;QAChF,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5D,OAAO,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,oBAAoB,OAAO,EAAE,EAAE,CAAC;IAC/F,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IAChF,CAAC;YAAS,CAAC;QACT,IAAI,CAAC;YAAC,EAAE,EAAE,KAAK,EAAE,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC;IAC7C,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAc;IACjD,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;IACxD,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;IAChD,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,OAAO,CAAC,KAAK,CAAC,iGAAiG,CAAC,CAAC;QACjH,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QAC9B,OAAO,CAAC,KAAK,CAAC,gCAAgC,YAAY,EAAE,CAAC,CAAC;QAC9D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,oBAAoB,EAAE,CAAC;IACtD,IAAI,OAAO,KAAK,UAAU,EAAE,CAAC;QAC3B,OAAO,CAAC,KAAK,CAAC,4CAA4C,CAAC,CAAC;QAC5D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;IAC9C,MAAM,GAAG,GAAG,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,cAAc,CAAC,gBAAgB,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;IAEjG,OAAO,CAAC,GAAG,CAAC,sCAAsC,YAAY,iBAAiB,MAAM,IAAI,CAAC,CAAC;IAE3F,mDAAmD;IACnD,MAAM,KAAK,GAAG,aAAa,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC;IAC/C,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC;QACd,OAAO,CAAC,KAAK,CAAC,mCAAmC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;QAChE,OAAO,CAAC,KAAK,CAAC,wBAAwB,CAAC,CAAC;QACxC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC;IAE1C,sBAAsB;IACtB,IAAI,CAAC;QACH,OAAO,CAAC,GAAG,CAAC,oBAAoB,MAAM,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;IACrE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,KAAK,CAAC,KAAM,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QAC7C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,0DAA0D;IAC1D,MAAM,SAAS,GAAG,GAAG,MAAM,kBAAkB,CAAC;IAC9C,MAAM,OAAO,GAAG,GAAG,MAAM,gBAAgB,CAAC;IAC1C,IAAI,CAAC;QACH,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QACpC,IAAI,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YACvB,MAAM,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YACnC,UAAU,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;YAC9B,OAAO,CAAC,GAAG,CAAC,6BAA6B,SAAS,EAAE,CAAC,CAAC;YACtD,qEAAqE;YACrE,yDAAyD;YACzD,MAAM,CAAC,GAAG,MAAM,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YACzC,MAAM,CAAC,GAAG,MAAM,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3C,CAAC;QACD,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC5B,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;IACzC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACjC,OAAO,CAAC,KAAK,CAAC,kBAAmB,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QAC1D,OAAO,CAAC,KAAK,CAAC,iBAAiB,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,SAAS,mBAAmB,CAAC,CAAC,CAAC,eAAe,GAAG,CAAC,CAAC;QACnH,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,oEAAoE;IACpE,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC9C,OAAO,CAAC,EAAE,EAAE,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QAC/B,EAAE,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,CAAC,GAAG,CAAC,+BAA+B,CAAC,CAAC;IAC/C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,KAAK,CAAC,sCAAuC,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QAC9E,OAAO,CAAC,KAAK,CAAC,uBAAuB,MAAM,eAAe,SAAS,QAAQ,CAAC,CAAC;QAC7E,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,6CAA6C;IAC7C,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,iBAAiB,EAAE,CAAC;YACpC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC;YACtC,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;gBACrB,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;gBACtB,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;gBAClD,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,0BAA0B,IAAI,EAAE,CAAC,CAAC,CAAC,8EAA8E,CAAC,CAAC;YAC3I,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,GAAG,CAAC,oEAAoE,CAAC,CAAC;YACpF,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,GAAG,CAAC,uBAAwB,GAAa,CAAC,OAAO,mBAAmB,CAAC,CAAC;QAChF,CAAC;IACH,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,6CAA6C,SAAS,+BAA+B,CAAC,CAAC;AACrG,CAAC"}

package/dist/cli/retag.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `astramem-local retag [--dry-run] [--limit N] [--tier2] [--no-tier2]
+ *                        [--confidence N] [--json]`
+ *
+ * FEAT-403 (W4.3) — one-shot repo/project tag-hygiene backfill. Scans
+ * memories with null/empty repo or project, derives tags tier-1 (session
+ * cwd/project_id) then optionally tier-2 (LLM-assisted, confidence-gated).
+ * See src/tag-hygiene/backfill.ts for the core (DB-only, testable) logic.
+ *
+ * tier-2 defaults to OFF (config.tagHygiene.tier2Enabled=false) — a
+ * data-mutating heuristic pass over legacy rows carries real mis-tag risk,
+ * so it is opt-in via --tier2 or config, never silently on.
+ */
+export declare function retagCommand(args: string[]): Promise<void>;