akm-cli 0.9.0-beta.57 → 0.9.0-beta.58

package/dist/commands/improve/reflect.js

@@ -30,7 +30,7 @@ import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { stripMarkdownFences } from "../../core/asset/markdown.js";
 import { DESCRIPTION_MAX_CHARS, requiresDescription } from "../../core/authoring-rules.js";
 import { resolveStashDir } from "../../core/common.js";
-import { loadConfig } from "../../core/config/config.js";
+import { getImproveProcessConfig, loadConfig } from "../../core/config/config.js";
 import { ConfigError, UsageError } from "../../core/errors.js";
 import { appendEvent, readEvents } from "../../core/events.js";
 import { lintLessonContent } from "../../core/lesson-lint.js";
@@ -798,7 +798,7 @@ export async function akmReflect(options = {}) {
         }
         else {
             const cfg = options.config ?? loadConfig();
-            const reflectProcess = cfg.profiles?.improve?.default?.processes?.reflect;
+            const reflectProcess = getImproveProcessConfig(cfg, "reflect", options.improveProfile);
             // Resolve the runner from the improve profile's reflect entry when present.
             runnerSpec = resolveImproveProcessRunnerFromProfile(reflectProcess, cfg) ?? undefined;
             if (runnerSpec) {
@@ -1171,7 +1171,8 @@ export async function akmReflect(options = {}) {
     // `profiles.improve.default.processes.reflect.qualityGate.enabled` or
     // `profiles.improve.default.processes.distill.qualityGate.enabled` (the
     // `lesson_quality_gate` flag name is the legacy alias still accepted by
-    // `isLlmFeatureEnabled`). Fail-open: any judge error passes through.
+    // `isLlmFeatureEnabled`). Fail-CLOSED (07 P0-2): a judge error / no-LLM /
+    // parse failure rejects the proposal rather than passing it through.
     // G-Eval (arXiv:2303.16634) — quality judgment before admission.
     const runtimeConfig = options.config ??
         (() => {

package/dist/commands/improve/shared.js

@@ -1,7 +1,7 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { getDefaultLlmConfig } from "../../core/config/config.js";
+import { getDefaultLlmConfig, getImproveProcessConfig } from "../../core/config/config.js";
 import { warn } from "../../core/warn.js";
 import { resolveImproveProcessRunnerFromProfile, runnerIsLlm } from "../../integrations/agent/runner.js";
 import { chatCompletion } from "../../llm/client.js";
@@ -21,13 +21,16 @@ export function refSlug(ref) {
 }
 /**
  * Resolve the production LLM seam for an improve process (`recombine` /
- * `procedural`) from the active default improve profile. Returns a function
- * that issues one bounded chatCompletion per call, or `undefined` when no LLM
- * is configured (the pass then makes no calls). Previously copied verbatim in
- * recombine.ts and procedural.ts.
+ * `procedural`). Returns a function that issues one bounded chatCompletion per
+ * call, or `undefined` when no LLM is configured (the pass then makes no
+ * calls). Previously copied verbatim in recombine.ts and procedural.ts.
+ *
+ * When `opts.activeProfile` is supplied, its per-process runner override wins
+ * over the `default` profile so `akm improve --profile <name>` selects the
+ * profile's model; absent falls back to `default`.
  */
 export function resolveImproveLlmFn(config, opts) {
-    const processConfig = config.profiles?.improve?.default?.processes?.[opts.processKey];
+    const processConfig = getImproveProcessConfig(config, opts.processKey, opts.activeProfile);
     const runnerSpec = resolveImproveProcessRunnerFromProfile(processConfig, config);
     const llmConfig = runnerSpec && runnerIsLlm(runnerSpec) ? runnerSpec.connection : getDefaultLlmConfig(config);
     if (!llmConfig)

package/dist/commands/proposal/drain-policies.js

@@ -39,8 +39,10 @@ const GeneratorSchema = z.enum(PROPOSAL_SOURCES, {
 export const PERSONAL_STASH = {
     name: "personal-stash",
     accept: [
-        // Extract proposals carry freshly-pulled real content — accept when present.
-        { generator: "extract", minContentLines: 1 },
+        // Extract proposals carry freshly-pulled real content — accept when present,
+        // but cap the diff for parity with reflect(80)/consolidate(200): an
+        // arbitrarily large extract should not auto-promote with zero LLM calls.
+        { generator: "extract", minContentLines: 1, maxDiffLines: 200 },
         // Reflect refinements: accept small ones; larger refinements defer to review.
         { generator: "reflect", maxDiffLines: 80 },
         // Consolidate within the diff band; mid-band lands in `defer` below.

package/dist/commands/read/remember-cli.js

@@ -60,7 +60,7 @@ export const rememberCommand = defineJsonCommand({
         },
         expires: {
             type: "string",
-            description: "Expiry duration shorthand (e.g. 30d, 12h, 6m). Resolved to an ISO date.",
+            description: "Expiry duration shorthand — e.g. 30d, 12h, 5m (minutes), 3M (months). Resolved to an ISO date.",
         },
         source: {
             type: "string",

package/dist/commands/read/show.js

@@ -363,6 +363,21 @@ export async function showLocal(input) {
     }
     const renderCtx = buildRenderContext(fileCtx, match, allSourceDirs, source?.registryId);
     const response = renderer.buildShowResponse(renderCtx);
+    // 07 P1-D: provenance-aware toolPolicy CEILING. An agent's self-declared
+    // `tools` frontmatter is honoured ONLY for the operator's own PRIMARY stash —
+    // the assets they authored. Every other source is content pulled from
+    // elsewhere and must not name its own tool grant: registry-installed packs, a
+    // configured secondary source, and even a git source the operator marked
+    // `--writable` to contribute edits upstream (writability is "can I push", not
+    // "do I trust this content to grant itself tools"). Drop the policy so dispatch
+    // falls back to the parent/default grant. Keys off primary-stash identity —
+    // `allSources[0]` is always the primary (search-source.ts) — not a
+    // name-derived registryId or the orthogonal `writable` bit. `source` undefined
+    // (unresolved path) also fails closed.
+    const isPrimaryStash = source !== undefined && source.path === allSources[0]?.path;
+    if (response.toolPolicy !== undefined && !isPrimaryStash) {
+        delete response.toolPolicy;
+    }
     const editable = isEditable(assetPath, config);
     const fullResponse = {
         ...response,

package/dist/commands/remember.js

@@ -12,25 +12,24 @@ import { serializeFrontmatter } from "../core/asset/asset-serialize.js";
 import { toErrorMessage, tryReadStdinText } from "../core/common.js";
 import { getDefaultLlmConfig, loadConfig } from "../core/config/config.js";
 import { UsageError } from "../core/errors.js";
+import { DURATION_UNITS, parseDuration as parseDurationSpec } from "../core/time.js";
 import { warn } from "../core/warn.js";
 import { SCOPE_KEYS } from "../indexer/passes/metadata.js";
 import { parseFlagValue } from "../output/context.js";
 /**
  * Parse a shorthand duration string to a number of milliseconds.
- * Supports: `30d` (days), `12h` (hours), `6m` (months, approximated as 30d).
+ * Supports the CLI-wide canonical grammar: `30d` (days), `12h` (hours),
+ * `5m` (minutes), `3M` (months, approximated as 30d).
  */
 export function parseDuration(s) {
-    const match = s.trim().match(/^(\d+)([dhm])$/i);
-    if (!match)
-        throw new UsageError(`Invalid --expires format "${s}". Use shorthand like 30d, 12h, or 6m.`, "INVALID_FLAG_VALUE");
-    const n = Number(match[1]);
-    const unit = match[2].toLowerCase();
-    if (unit === "d")
-        return n * 24 * 60 * 60 * 1000;
-    if (unit === "h")
-        return n * 60 * 60 * 1000;
-    // 'm' = months, approximated as 30 days
-    return n * 30 * 24 * 60 * 60 * 1000;
+    // Canonical CLI unit grammar: `m` = minutes, `M` = months. Not lower-cased,
+    // so case distinguishes the two (`5m` = 5 minutes, `5M` = 5 months). See
+    // core/time.ts DURATION_UNITS.
+    const ms = parseDurationSpec(s.trim(), DURATION_UNITS);
+    if (ms === null) {
+        throw new UsageError(`Invalid --expires format "${s}". Use shorthand like 30d, 12h, 5m, or 3M.`, "INVALID_FLAG_VALUE");
+    }
+    return ms;
 }
 /**
  * Build a YAML frontmatter block from memory metadata.

package/dist/commands/sources/init.js

@@ -15,7 +15,7 @@ import { loadUserConfig, saveConfig } from "../../core/config/config.js";
 import { ConfigError } from "../../core/errors.js";
 import { assertSafeStashDir, getBinDir, getConfigPath, getDefaultStashDir } from "../../core/paths.js";
 import { ensureRg } from "../../core/ripgrep/install.js";
-import { copyStashSkeleton, scaffoldStashMeta } from "./stash-skeleton.js";
+import { copyStashSkeleton, ensureStashGitignore, scaffoldStashMeta } from "./stash-skeleton.js";
 /**
  * Refuse to persist a temporary-directory stashDir to the user's config when
  * running under a test runner AND `--dir <tempdir>` was passed explicitly.
@@ -92,6 +92,10 @@ async function akmInitReal(options) {
     }
     // Ensure the default stash is a local git repo (no remote required)
     ensureGitRepo(stashDir);
+    // 08-F1: scaffold a default `.gitignore` that keeps env/ + secrets/ out of git
+    // so a `git push` can never leak them. Idempotent + non-clobbering; the user
+    // opts into versioning by un-ignoring a path.
+    ensureStashGitignore(stashDir);
     // Run seeding UNCONDITIONALLY (not just when the stash was newly created) so
     // re-running `akm init` on an existing stash backfills any missing skeleton
     // files — the README, the per-type SOFT convention templates under

package/dist/commands/sources/stash-skeleton.js

@@ -71,6 +71,40 @@ export function scaffoldStashMeta(stashDir) {
         // Non-fatal — stash is usable without the .meta orientation doc
     }
 }
+/** Marks the akm-authored block in a stash `.gitignore` (idempotency anchor). */
+const STASH_GITIGNORE_MARKER = "# akm: keep secret material out of git by default";
+const STASH_GITIGNORE_BLOCK = [
+    STASH_GITIGNORE_MARKER,
+    "# env/ and secrets/ assets hold tokens and keys. They are ignored by default",
+    "# so `git push` can never leak them. To version a specific one (e.g. for a",
+    "# private-remote backup), un-ignore its path below once you accept the risk.",
+    "env/",
+    "secrets/",
+    "",
+].join("\n");
+/**
+ * Ensure the stash `.gitignore` keeps `env/` and `secrets/` out of git by
+ * default (08-F1: the v0.8.0 `vaults/` → `env/`+`secrets/` migration never
+ * carried the ignore rules forward, and init scaffolded none).
+ *
+ * Idempotent + non-clobbering: creates the file when absent, appends the akm
+ * block when the file exists but lacks it (preserving the user's own rules),
+ * and no-ops once the marker is present. The user opts INTO versioning by
+ * un-ignoring a path.
+ */
+export function ensureStashGitignore(stashDir) {
+    try {
+        const gitignorePath = path.join(stashDir, ".gitignore");
+        const existing = fs.existsSync(gitignorePath) ? fs.readFileSync(gitignorePath, "utf8") : "";
+        if (existing.includes(STASH_GITIGNORE_MARKER))
+            return;
+        const gap = existing.length === 0 ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+        fs.writeFileSync(gitignorePath, `${existing}${gap}${STASH_GITIGNORE_BLOCK}`);
+    }
+    catch {
+        // Non-fatal — the stash is usable without the ignore scaffold.
+    }
+}
 const STASH_META_INDEX_TEMPLATE = `---
 # Optional, human-authored orientation for this stash. Not indexed; surfaced
 # on demand via \`akm show meta\` (this file) or \`akm show <stash>//meta\`.

package/dist/core/asset/frontmatter.js

@@ -8,7 +8,9 @@
  * (block scalars, multi-line strings, nested objects, flow sequences, escape
  * sequences) is handled correctly without a brittle hand-rolled state machine.
  */
+import fs from "node:fs";
 import { parse as yamlParse, stringify as yamlStringify } from "yaml";
+import { assembleAsset } from "./asset-serialize.js";
 /**
  * Parse YAML frontmatter from a Markdown (or similar) string.
  *
@@ -107,6 +109,26 @@ function parseFrontmatterLenient(frontmatter) {
     }
     return data;
 }
+/**
+ * Read a file, parse its frontmatter, let `mutator` compute the next
+ * frontmatter object, and write the reassembled asset back to disk.
+ *
+ * This is the shared read→parse→mutate→write primitive. The `mutator` receives
+ * the parsed result and returns either the next frontmatter object (to write)
+ * or `null` to skip the write entirely (e.g. for idempotent no-ops). The body
+ * content is preserved from the parse.
+ *
+ * @returns `true` if a write occurred, `false` if the mutator returned `null`.
+ */
+export function mutateFrontmatter(filePath, mutator) {
+    const raw = fs.readFileSync(filePath, "utf8");
+    const parsed = parseFrontmatter(raw);
+    const nextFrontmatter = mutator(parsed);
+    if (nextFrontmatter === null)
+        return false;
+    fs.writeFileSync(filePath, assembleAsset(nextFrontmatter, parsed.content), "utf8");
+    return true;
+}
 export function parseFrontmatterBlock(raw) {
     // Handle both LF and CRLF line endings throughout.
     // The closing --- may be preceded by \r\n; capture and strip trailing \r

package/dist/core/common.js

@@ -84,14 +84,7 @@ export function writeFileAtomic(target, content, mode) {
     const tmp = `${target}.tmp.${process.pid}.${crypto.randomBytes(8).toString("hex")}`;
     const fd = fs.openSync(tmp, "w", mode ?? 0o600);
     try {
-        // fs.writeSync has two non-overlapping overloads (Buffer vs string); branch
-        // so each call resolves to a single overload. Both write byte-exact.
-        if (typeof content === "string") {
-            fs.writeSync(fd, content);
-        }
-        else {
-            fs.writeSync(fd, content);
-        }
+        fs.writeSync(fd, typeof content === "string" ? Buffer.from(content) : content);
         try {
             fs.fdatasyncSync(fd);
         }
@@ -462,13 +455,6 @@ export function asNonEmptyString(value) {
     return trimmed.length > 0 ? trimmed : undefined;
 }
 // ── Generic data utilities ───────────────────────────────────────────────────
-/**
- * Return the trimmed string if non-empty, otherwise `undefined`.
- * Equivalent to `firstString` previously defined in `memory-improve.ts`.
- */
-export function firstString(value) {
-    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
-}
 /**
  * Coerce an unknown value to a filtered, trimmed string array.
  * Non-strings and empty/whitespace-only entries are dropped.

package/dist/core/config/config-io.js

@@ -84,12 +84,21 @@ export function backupExistingConfig(configPath) {
     if (!fs.existsSync(configPath))
         return undefined;
     const backupDir = path.join(getCacheDir(), "config-backups");
-    fs.mkdirSync(backupDir, { recursive: true });
+    // 08-F4: lock the backup dir owner-only up front (0700) — matching the
+    // env.ts/secret.ts convention — so no other local user can traverse in during
+    // the copy→chmod window. chmod again to tighten a dir from an older version.
+    fs.mkdirSync(backupDir, { recursive: true, mode: 0o700 });
+    fs.chmodSync(backupDir, 0o700);
     const timestamp = new Date().toISOString().replace(/[.:]/g, "-");
     const timestamped = path.join(backupDir, `config-${timestamp}.json`);
     const latest = path.join(backupDir, "config.latest.json");
     fs.copyFileSync(configPath, timestamped);
     fs.copyFileSync(configPath, latest);
+    // 08-F4: a config backup carries the same sensitive fields as the live config
+    // (endpoints, tokens). `copyFileSync` inherits the source's (often 0644) mode,
+    // so tighten the backups to owner-only — mirrors the env-cli 0600 write floor.
+    fs.chmodSync(timestamped, 0o600);
+    fs.chmodSync(latest, 0o600);
     pruneOldBackups(backupDir);
     return { timestamped, latest };
 }

package/dist/core/config/config-migration.js

@@ -262,12 +262,6 @@ export function migrateConfigShape(raw, opts) {
                 if (typeof llmFeatures.metadata_enhance === "boolean")
                     me.enabled = llmFeatures.metadata_enhance;
             }
-            if ("curate_rerank" in llmFeatures) {
-                const search = getObj(result, "search");
-                const cr = getObj(search, "curateRerank");
-                if (typeof llmFeatures.curate_rerank === "boolean")
-                    cr.enabled = llmFeatures.curate_rerank;
-            }
             if ("lesson_quality_gate" in llmFeatures) {
                 const distill = getImproveProcess(result, "distill");
                 const qg = getObj(distill, "qualityGate");
@@ -417,17 +411,10 @@ export function migrateConfigShape(raw, opts) {
         }
         if (isObj(features.search)) {
             const fsearch = features.search;
-            if ("curate_rerank" in fsearch) {
-                const search = getObj(result, "search");
-                const cr = getObj(search, "curateRerank");
-                const val = fsearch.curate_rerank;
-                if (typeof val === "boolean")
-                    cr.enabled = val;
-                else if (isObj(val) && typeof val.enabled === "boolean")
-                    cr.enabled = val.enabled;
-            }
             // Catch-all: unknown features.search.<key> entries land at
             // search.<keyAsCamelCase> (preserving { enabled, options } when present).
+            // `curate_rerank` is a removed dead feature — listed here so the catch-all
+            // skips it and it is simply dropped (not resurrected under search.curateRerank).
             const knownSearchKeys = new Set(["curate_rerank"]);
             for (const [legacyKey, legacyVal] of Object.entries(fsearch)) {
                 if (knownSearchKeys.has(legacyKey))

package/dist/core/config/config-schema.js

@@ -49,8 +49,21 @@ const nonEmptyString = z
 const httpUrl = z.string().refine((v) => v.startsWith("http://") || v.startsWith("https://"), {
     message: "endpoint must start with http:// or https://",
 });
-// ── Feedback failure modes ──────────────────────────────────────────────────
-export const FEEDBACK_FAILURE_MODES = ["incorrect", "outdated", "dangerous", "incomplete", "redundant"];
+// ── Feedback failure modes (F-3 / #384) ─────────────────────────────────────
+/**
+ * Curated taxonomy of failure modes for negative feedback.
+ *
+ * Structured failure modes enable aggregation across feedback events so the
+ * distill pipeline can detect that "5 assets failed for the same reason" and
+ * act on it — free-text strings about the same issue are not aggregatable.
+ */
+export const FEEDBACK_FAILURE_MODES = [
+    "incorrect", // Factually wrong or logically flawed content
+    "outdated", // Correct at some point but now stale
+    "dangerous", // Could cause harm if followed (security, safety)
+    "incomplete", // Missing key steps, context, or caveats
+    "redundant", // Duplicates another asset without adding value
+];
 // ── Connection configs (LLM / embedding) ────────────────────────────────────
 const LlmCapabilitiesSchema = z
     .object({
@@ -552,7 +565,6 @@ export const SearchConfigSchema = z
     .object({
     minScore: nonNegativeNumber.optional(),
     defaultExcludeTypes: z.array(nonEmptyString).optional(),
-    curateRerank: z.object({ enabled: z.boolean().optional() }).passthrough().optional(),
     graphBoost: SearchGraphBoostSchema.optional(),
 })
     .passthrough();

package/dist/core/config/config.js

@@ -13,20 +13,9 @@ import { warn } from "../warn.js";
 // Canonical harness-id source of truth (#565) — runtime value re-export.
 export { VALID_HARNESS_IDS } from "./config-types.js";
 // ── Feedback failure-mode constants (F-3 / #384) ────────────────────────────
-/**
- * Curated taxonomy of failure modes for negative feedback.
- *
- * Structured failure modes enable aggregation across feedback events so the
- * distill pipeline can detect that "5 assets failed for the same reason" and
- * act on it — free-text strings about the same issue are not aggregatable.
- */
-export const FEEDBACK_FAILURE_MODES = [
-    "incorrect", // Factually wrong or logically flawed content
-    "outdated", // Correct at some point but now stale
-    "dangerous", // Could cause harm if followed (security, safety)
-    "incomplete", // Missing key steps, context, or caveats
-    "redundant", // Duplicates another asset without adding value
-];
+// Canonical taxonomy lives in the schema/validator layer; re-exported here so
+// existing `../core/config/config` import sites keep working.
+export { FEEDBACK_FAILURE_MODES } from "./config-schema.js";
 /**
  * Default value for {@link IndexPassConfig.graphExtractionBatchSize}. Chosen
  * empirically: 4 amortises the per-call HTTP overhead 4× while keeping the
@@ -205,6 +194,25 @@ export function getDefaultLlmConfig(config) {
         return undefined;
     return config.profiles?.llm?.[defaultName];
 }
+/**
+ * Resolve the per-process config section for an improve process,
+ * centralizing the deeply-nested lookup
+ * `profile?.processes?.<name>` that was previously copy-pasted across the
+ * improve command family (20+ call sites).
+ *
+ * When an `activeProfile` is supplied (the profile resolved for the current
+ * `akm improve --profile <name>` run), its per-process override wins; otherwise
+ * — and as a fallback when the active profile does not define the section — the
+ * lookup falls back to the `"default"` improve profile from the on-disk config.
+ * Callers that have not yet threaded the active profile pass only `config` and
+ * get the historical default-profile behavior unchanged.
+ */
+export function getImproveProcessConfig(config, processName, activeProfile) {
+    const fromActiveProfile = activeProfile?.processes?.[processName];
+    if (fromActiveProfile !== undefined)
+        return fromActiveProfile;
+    return config.profiles?.improve?.default?.processes?.[processName];
+}
 /**
  * Run `migrateConfigShape` on the raw text and — unless `AKM_NO_AUTO_MIGRATE=1`
  * is set — persist the migrated result. Returns the (possibly migrated) text

package/dist/core/paths.js

@@ -111,8 +111,8 @@ export function getConfigDir(env = process.env, platform = process.platform) {
     }
     return path.join(home, ".config", "akm");
 }
-export function getConfigPath() {
-    return path.join(getConfigDir(), "config.json");
+export function getConfigPath(env = process.env) {
+    return path.join(getConfigDir(env), "config.json");
 }
 // ── Cache directory ──────────────────────────────────────────────────────────
 export function getCacheDir(env = process.env) {
@@ -212,8 +212,8 @@ export function getDataDir(env = process.env, platform = process.platform) {
         return path.join("/tmp", "akm-data");
     return path.join(home, ".local", "share", "akm");
 }
-export function getDbPath() {
-    return path.join(getDataDir(), "index.db");
+export function getDbPath(env = process.env) {
+    return path.join(getDataDir(env), "index.db");
 }
 export function getIndexWriterLockPath() {
     return path.join(getDataDir(), "index.db.write.lock");

package/dist/core/time.js

@@ -9,6 +9,59 @@
  * consistently without private re-implementations drifting apart.
  */
 import { UsageError } from "./errors.js";
+// ── Duration-shorthand parsing ───────────────────────────────────────────────
+const MINUTE_MS = 60 * 1000;
+const HOUR_MS = 60 * 60 * 1000;
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** A month is approximated as 30 days — this shorthand is not calendar-exact. */
+const MONTH_MS = 30 * DAY_MS;
+/**
+ * Canonical duration-shorthand unit map shared by every `--since` / `--expires`
+ * / `--window-compare` consumer.
+ *
+ * The grammar is intentionally uniform across the whole CLI:
+ *   - `m` = MINUTES, `M` = MONTHS (30-day approximation)
+ *   - `h`/`H` = hours, `d`/`D` = days
+ *
+ * Matching is CASE-SENSITIVE (see {@link parseDuration}), which is what lets
+ * `m` and `M` mean different things. Historically `akm health --since` and
+ * `remember --expires` read a case-insensitive `m` as MONTHS while
+ * `consolidate` / `--window-compare` read it as MINUTES; that split is now
+ * resolved in favour of the conventional `m`=minutes, with `M` reserved for
+ * months. Upper-case `H`/`D` aliases are retained so specs that previously
+ * relied on the old case-insensitive parsers (e.g. `"7D"`) keep working.
+ */
+export const DURATION_UNITS = {
+    m: MINUTE_MS,
+    M: MONTH_MS,
+    h: HOUR_MS,
+    H: HOUR_MS,
+    d: DAY_MS,
+    D: DAY_MS,
+};
+/**
+ * Parse a compact duration shorthand (e.g. `"30d"`, `"12h"`, `"5m"`, `"3M"`)
+ * into a number of milliseconds using an explicit `units` map (default
+ * {@link DURATION_UNITS}), or return `null` when the input does not match
+ * `<digits><letter>` or the unit is not in the map.
+ *
+ * Matching is CASE-SENSITIVE against the map keys, so `m` (minutes) and `M`
+ * (months) are distinct — do NOT lower-case the spec before calling, or the
+ * two collapse. Amount is parsed with base-10 `parseInt`; `null` is returned
+ * rather than throwing so each caller keeps its own error/fallback policy.
+ */
+export function parseDuration(spec, units = DURATION_UNITS) {
+    const match = spec.trim().match(/^(\d+)([a-zA-Z])$/);
+    if (!match)
+        return null;
+    const amount = Number.parseInt(match[1] ?? "", 10);
+    if (!Number.isFinite(amount))
+        return null;
+    const multiplier = units[match[2] ?? ""];
+    if (multiplier === undefined)
+        return null;
+    return amount * multiplier;
+}
 // ── Since-flag parsing ───────────────────────────────────────────────────────
 /**
  * Parse a user-supplied `--since` value and return an ISO-8601 timestamp

package/dist/indexer/db/db.js

@@ -257,6 +257,49 @@ export function getDerivedForParent(db, parentRef) {
         return null;
     }
 }
+/**
+ * 03-R3: for the given derived-twin row ids, fetch each twin's BASE memory
+ * `beliefState`, keyed by twin id.
+ *
+ * Used by the derived-twin belief inheritance in search ranking: a `.derived`
+ * twin has no belief state of its own, so it inherits its base memory's
+ * demoting state (contradicted/superseded/…) at search time. A twin's
+ * `entry_key` is exactly its base's `entry_key` plus the `.derived` suffix
+ * (same stash + type prefix, `<name>` vs `<name>.derived`), so the base is
+ * found by stripping that suffix — no ref/prefix reconstruction. Returns a map
+ * of twin id → base beliefState for bases that carry a non-empty state.
+ * Best-effort: any query error (e.g. legacy DB) yields no inheritance rather
+ * than failing the search.
+ */
+export function getBaseBeliefStatesForDerivedTwins(db, twinIds) {
+    const out = new Map();
+    if (twinIds.length === 0)
+        return out;
+    // Chunk at SQLITE_CHUNK_SIZE like the sibling bulk-by-id helpers, so a large
+    // `--limit` candidate set never trips SQLITE_MAX_VARIABLE_NUMBER (which would
+    // otherwise fall into the best-effort catch and silently disable the feature).
+    for (let i = 0; i < twinIds.length; i += SQLITE_CHUNK_SIZE) {
+        const chunk = twinIds.slice(i, i + SQLITE_CHUNK_SIZE);
+        const placeholders = chunk.map(() => "?").join(",");
+        bestEffort(() => {
+            const rows = db
+                .prepare(`SELECT twin.id AS twin_id, json_extract(base.entry_json, '$.beliefState') AS belief
+           FROM entries twin
+           JOIN entries base
+             ON base.entry_type = 'memory'
+            AND base.entry_key = substr(twin.entry_key, 1, length(twin.entry_key) - length('.derived'))
+           WHERE twin.id IN (${placeholders})
+             AND twin.entry_key LIKE '%.derived'
+             AND json_extract(base.entry_json, '$.beliefState') IS NOT NULL`)
+                .all(...chunk);
+            for (const r of rows) {
+                if (typeof r.belief === "string" && r.belief.trim().length > 0)
+                    out.set(r.twin_id, r.belief.trim());
+            }
+        }, "legacy DB / entry_json without beliefState — treat as no twin inheritance");
+    }
+    return out;
+}
 /**
  * Phase 2A / Rec 5: bulk-load positive feedback event counts for the given
  * entry ids. Used by the utility-decay forgetting curve to stabilize
@@ -648,7 +691,8 @@ function runFtsQuery(db, ftsQuery, limit, entryType, excludeTypes) {
         }
         return results;
     }
-    catch {
+    catch (err) {
+        warn("[db] runFtsQuery failed:", err instanceof Error ? err.message : String(err));
         return [];
     }
 }
@@ -747,8 +791,7 @@ export function getEntryCount(db) {
     return row.cnt;
 }
 export function getEmbeddableEntryCount(db) {
-    const row = db.prepare("SELECT COUNT(*) AS cnt FROM entries").get();
-    return row.cnt;
+    return getEntryCount(db);
 }
 export function getEmbeddingCount(db) {
     const row = db.prepare("SELECT COUNT(*) AS cnt FROM embeddings").get();
@@ -1327,49 +1370,11 @@ export function relinkUsageEvents(db) {
     }, "usage_events table may not exist yet during entry_id re-resolution");
 }
 // ── registry_index_cache helpers ─────────────────────────────────────────────
-/**
- * Upsert a registry index cache entry in index.db.
- *
- * @param db          - Open index.db connection (from openDatabase / openExistingDatabase).
- * @param registryUrl - Canonical URL of the registry (used as primary key).
- * @param indexJson   - Serialised registry index document (JSON string).
- * @param opts.etag        - HTTP ETag from the response (optional).
- * @param opts.lastModified - HTTP Last-Modified from the response (optional).
- */
-export function upsertRegistryIndexCache(db, registryUrl, indexJson, opts) {
-    db.prepare(`
-    INSERT INTO registry_index_cache (registry_url, fetched_at, etag, last_modified, index_json)
-    VALUES (?, ?, ?, ?, ?)
-    ON CONFLICT(registry_url) DO UPDATE SET
-      fetched_at    = excluded.fetched_at,
-      etag          = excluded.etag,
-      last_modified = excluded.last_modified,
-      index_json    = excluded.index_json
-  `).run(registryUrl, new Date().toISOString(), opts?.etag ?? null, opts?.lastModified ?? null, indexJson);
-}
-/**
- * Look up a cached registry index entry from index.db.
- * Returns undefined when not found or when the entry is older than `maxAgeMs`.
- *
- * TTL check: if `Date.now() - new Date(fetched_at).getTime() > maxAgeMs` the
- * entry is considered a cache miss and undefined is returned.
- *
- * @param db          - Open index.db connection.
- * @param registryUrl - Canonical URL of the registry (primary key).
- * @param maxAgeMs    - Maximum age in milliseconds before the entry is stale (default: 1 hour).
- */
-export function getRegistryIndexCache(db, registryUrl, maxAgeMs = 3_600_000 /* 1 hour */) {
-    const row = db
-        .prepare(`SELECT fetched_at, etag, last_modified, index_json
-       FROM registry_index_cache WHERE registry_url = ?`)
-        .get(registryUrl);
-    if (!row)
-        return undefined;
-    const fetchedAt = Date.parse(row.fetched_at);
-    if (Number.isNaN(fetchedAt) || Date.now() - fetchedAt > maxAgeMs)
-        return undefined;
-    return { indexJson: row.index_json, etag: row.etag, lastModified: row.last_modified };
-}
+// The raw SQL for the `registry_index_cache` table now lives in the storage
+// layer (`src/storage/repositories/registry-index-cache-repository.ts`) so the
+// dependency arrow points indexer → storage. These thin re-exports preserve the
+// previously-public symbols for any importer of this module.
+export { getRegistryIndexCache, upsertRegistryIndexCache, } from "../../storage/repositories/registry-index-cache-repository.js";
 /**
  * Walk indexed entries and collect a deduplicated set of tags. When
  * `entryType` is provided, only entries of that type contribute tags.