akm-cli 0.9.0 → 0.9.1-beta.2

package/dist/core/json-schema.js

@@ -14,22 +14,288 @@
  *   Supported: `type` (string | string[] — string, number, integer, boolean,
  *   object, array, null), `properties`, `required`, `items`,
  *   `additionalProperties: false`, `enum` (primitives), `minItems`,
- *   `maxItems`, `minLength`, `maxLength`, `minimum`, `maximum`.
+ *   `maxItems`, `minLength`, `maxLength`, `minimum`, `maximum`, and the
+ *   combinators `allOf`, `anyOf`, `oneOf`, `not`.
  *
- *   Ignored (permissive): `$ref`, `allOf`/`anyOf`/`oneOf`/`not`, `pattern`,
- *   `format`, and every other keyword. Unknown keywords never throw — a
- *   schema using them simply constrains less. Callers needing full JSON
- *   Schema semantics should validate downstream.
+ *   Ignored (permissive): `$ref`, `pattern`, `format`, `patternProperties`,
+ *   tuple-form `items`, schema-form `additionalProperties`, and every other
+ *   keyword. Unknown keywords never throw — a schema using them simply
+ *   constrains less. Callers needing full JSON Schema semantics should
+ *   validate downstream.
+ *
+ *   `pattern` is deliberately NOT evaluated. Matching an author-supplied regex
+ *   with the platform `RegExp` inside a synchronous gate decision would need a
+ *   static safety analysis to stay bounded, and any such analysis rejects
+ *   legitimate patterns — machinery that makes authoring fail for no benefit
+ *   the workflows here ask for. `pattern` is a recognized-but-unsupported
+ *   keyword instead: {@link checkJsonSchemaDefinition} reports it loudly at
+ *   authoring time, so nobody writes one believing it is enforced.
+ *
+ * ## Totality and bounds
+ *
+ * Evaluation is TOTAL and BOUNDED. Recursion is capped at
+ * {@link MAX_DEFINITION_DEPTH} and the whole evaluation shares a single
+ * node-visit budget ({@link MAX_VALIDATION_NODES}); exhausting either emits an
+ * explicit error rather than silently accepting the value — the subset never
+ * fails open. The schema tree is finite and acyclic (no `$ref`), so combinator
+ * branching multiplies work by schema size, never exponentially.
  *
  * Returns a flat list of human-readable error strings (empty = valid), each
  * prefixed with a JSON-pointer-ish path — the shape `runStructured`'s
  * corrective-feedback builder wants.
+ *
+ * {@link checkJsonSchemaDefinition} is the companion DEFINITION checker: it
+ * walks an author-declared schema OBJECT (not a value) and reports typo'd
+ * `type` names / structurally malformed keywords as `"malformed"` issues, and
+ * recognized JSON Schema keywords this subset silently ignores as
+ * `"unsupported"` issues — so a schema that would constrain nothing at
+ * runtime can be rejected loudly at authoring time (the workflow parser does
+ * exactly that for `output:` and `params` schemas). It deliberately does NOT
+ * change {@link validateJsonSchemaSubset}'s permissive evaluation semantics.
+ */
+/**
+ * Deepest schema nesting either walk descends into — {@link
+ * validateJsonSchemaSubset} evaluating a value, and {@link
+ * checkJsonSchemaDefinition} checking the schema object itself. Both walk the
+ * same schema tree, so they share one bound.
  */
+const MAX_DEFINITION_DEPTH = 64;
+/** Total (schema node × value node) visits one {@link validateJsonSchemaSubset} call may make. */
+const MAX_VALIDATION_NODES = 100_000;
 export function validateJsonSchemaSubset(value, schema) {
     const errors = [];
-    validateNode(value, schema, "$", errors);
+    const budget = { nodes: MAX_VALIDATION_NODES };
+    validateNode(value, schema, "$", { errors, budget, depth: 0 });
+    if (budget.nodes < 0) {
+        errors.push(`$: schema evaluation exceeded the limit of ${MAX_VALIDATION_NODES} checks and was stopped`);
+    }
     return errors;
 }
+/** Human-readable list of the keywords {@link validateJsonSchemaSubset} enforces (for error messages). */
+export const JSON_SCHEMA_SUBSET_SUPPORTED_KEYWORDS = "type, enum, properties, required, items, additionalProperties: false, minItems, maxItems, " +
+    "minLength, maxLength, minimum, maximum, allOf, anyOf, oneOf, not";
+const KNOWN_TYPE_NAMES = new Set(["string", "number", "integer", "boolean", "object", "array", "null"]);
+// Annotation keywords (`title`, `description`, `default`, `examples`,
+// `$schema`, `$id`, `$comment`, `deprecated`, `readOnly`, `writeOnly`) are
+// deliberately NOT in the unsupported set below: they constrain nothing in
+// full JSON Schema either, so the subset ignoring them loses no semantics.
+// Like any other unrecognized keyword (e.g. `x-…` extensions), they fall
+// through the checker unreported — JSON Schema's own open-keyword behavior.
+/**
+ * Recognized JSON Schema keywords {@link validateJsonSchemaSubset} silently
+ * ignores — a schema relying on one of these constrains LESS at runtime than
+ * its author intended, so definition checking reports each as `"unsupported"`.
+ */
+const UNSUPPORTED_KEYWORDS = new Set([
+    "$ref",
+    "$defs",
+    "definitions",
+    "$anchor",
+    "$dynamicRef",
+    "$dynamicAnchor",
+    "if",
+    "then",
+    "else",
+    "const",
+    "pattern",
+    "format",
+    "patternProperties",
+    "propertyNames",
+    "additionalItems",
+    "prefixItems",
+    "contains",
+    "minContains",
+    "maxContains",
+    "uniqueItems",
+    "multipleOf",
+    "exclusiveMinimum",
+    "exclusiveMaximum",
+    "minProperties",
+    "maxProperties",
+    "dependencies",
+    "dependentRequired",
+    "dependentSchemas",
+    "unevaluatedItems",
+    "unevaluatedProperties",
+    "contentEncoding",
+    "contentMediaType",
+    "contentSchema",
+]);
+/**
+ * Per-keyword follow-up for the `"unsupported"` message. Where the subset can
+ * express the same intent, name the keyword that does it; where it cannot, say
+ * so plainly rather than sending the author to another unsupported keyword.
+ */
+const UNSUPPORTED_KEYWORD_HINTS = new Map([
+    ["$ref", `inline the referenced schema (the subset resolves no references, so it cannot follow "$ref")`],
+    ["$defs", `inline the definitions at their use sites — "$ref" is not resolved, so "$defs" can never be reached`],
+    [
+        "definitions",
+        `inline the definitions at their use sites — "$ref" is not resolved, so "definitions" can never be reached`,
+    ],
+    ["const", `use a single-value "enum" (e.g. enum: [pass])`],
+    [
+        "pattern",
+        `use "enum" when the allowed strings can be listed, or "minLength"/"maxLength" for a size bound — ` +
+            `a regular-expression constraint is not expressible in the subset; check the shape in the step's gate rubric instead`,
+    ],
+    [
+        "format",
+        `"format" is annotation-only in JSON Schema 2020-12 and the subset enforces no string-shape keyword — ` +
+            `use "enum" when the allowed values can be listed, otherwise check the shape in the step's gate rubric`,
+    ],
+    ["patternProperties", `declare the properties explicitly under "properties", or drop the constraint`],
+    ["if", `use "anyOf"/"oneOf" to express the alternatives directly`],
+    ["then", `use "anyOf"/"oneOf" to express the alternatives directly`],
+    ["else", `use "anyOf"/"oneOf" to express the alternatives directly`],
+    ["uniqueItems", `drop the constraint, or validate uniqueness in the step's gate rubric`],
+]);
+/**
+ * Check a JSON Schema DEFINITION (the schema object itself, not a value)
+ * against the subset {@link validateJsonSchemaSubset} enforces. Returns
+ * accumulated issues (empty = the schema is a well-formed subset schema).
+ * Keywords that are neither subset-enforced, unsupported-but-recognized, nor
+ * annotations are ignored, matching JSON Schema's own open-keyword behavior.
+ */
+export function checkJsonSchemaDefinition(schema) {
+    const issues = [];
+    checkDefinitionNode(schema, [], issues, 0);
+    return issues;
+}
+function pointerFor(path) {
+    return path.length === 0 ? "$" : `$.${path.map(String).join(".")}`;
+}
+function pushIssue(issues, path, keyword, kind, message) {
+    issues.push({ path: [...path], pointer: pointerFor(path), keyword, kind, message });
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Values the runtime's reference-equality `enum` check can enforce correctly. */
+function isSupportedEnumValue(value) {
+    return (value === null ||
+        typeof value === "string" ||
+        typeof value === "boolean" ||
+        (typeof value === "number" && Number.isFinite(value)));
+}
+function checkDefinitionNode(schema, path, issues, depth) {
+    if (depth > MAX_DEFINITION_DEPTH) {
+        pushIssue(issues, path, "(depth)", "malformed", `schema nesting exceeds the depth limit of ${MAX_DEFINITION_DEPTH}`);
+        return;
+    }
+    for (const keyword of Object.keys(schema)) {
+        if (UNSUPPORTED_KEYWORDS.has(keyword)) {
+            const hint = UNSUPPORTED_KEYWORD_HINTS.get(keyword);
+            pushIssue(issues, [...path, keyword], keyword, "unsupported", `keyword "${keyword}" is not enforced by the workflow schema subset — the schema would silently not ` +
+                `constrain what it looks like it constrains${hint ? `; ${hint}` : ""}`);
+        }
+    }
+    const declared = schema.type;
+    if (declared !== undefined) {
+        const names = Array.isArray(declared) ? declared : [declared];
+        if (names.length === 0) {
+            pushIssue(issues, [...path, "type"], "type", "malformed", `"type" must name at least one type`);
+        }
+        for (const [index, name] of names.entries()) {
+            const namePath = Array.isArray(declared) ? [...path, "type", index] : [...path, "type"];
+            if (typeof name !== "string") {
+                pushIssue(issues, namePath, "type", "malformed", `"type" must be a string or an array of strings`);
+            }
+            else if (!KNOWN_TYPE_NAMES.has(name)) {
+                pushIssue(issues, namePath, "type", "malformed", `unknown type ${JSON.stringify(name)} (valid types: ${[...KNOWN_TYPE_NAMES].join(", ")})`);
+            }
+        }
+    }
+    if (schema.enum !== undefined) {
+        if (!Array.isArray(schema.enum) || schema.enum.length === 0) {
+            pushIssue(issues, [...path, "enum"], "enum", "malformed", `"enum" must be a non-empty array of allowed values`);
+        }
+        else {
+            schema.enum.forEach((value, index) => {
+                if (isSupportedEnumValue(value))
+                    return;
+                pushIssue(issues, [...path, "enum", index], "enum", "unsupported", `"enum" values must be JSON primitives (string, finite number, boolean, or null) in the workflow ` +
+                    `schema subset — object and array enum members cannot be matched by the runtime subset`);
+            });
+        }
+    }
+    for (const keyword of ["allOf", "anyOf", "oneOf"]) {
+        const branches = schema[keyword];
+        if (branches === undefined)
+            continue;
+        if (!Array.isArray(branches) || branches.length === 0) {
+            pushIssue(issues, [...path, keyword], keyword, "malformed", `"${keyword}" must be a non-empty array of schema objects`);
+            continue;
+        }
+        branches.forEach((branch, index) => {
+            if (isPlainObject(branch)) {
+                checkDefinitionNode(branch, [...path, keyword, index], issues, depth + 1);
+            }
+            else {
+                pushIssue(issues, [...path, keyword, index], keyword, "malformed", `"${keyword}[${index}]" must be a schema object`);
+            }
+        });
+    }
+    if (schema.not !== undefined) {
+        if (isPlainObject(schema.not)) {
+            checkDefinitionNode(schema.not, [...path, "not"], issues, depth + 1);
+        }
+        else {
+            pushIssue(issues, [...path, "not"], "not", "malformed", `"not" must be a schema object`);
+        }
+    }
+    if (schema.required !== undefined) {
+        if (!Array.isArray(schema.required) || !schema.required.every((key) => typeof key === "string")) {
+            pushIssue(issues, [...path, "required"], "required", "malformed", `"required" must be an array of property-name strings`);
+        }
+    }
+    if (schema.properties !== undefined) {
+        if (!isPlainObject(schema.properties)) {
+            pushIssue(issues, [...path, "properties"], "properties", "malformed", `"properties" must be an object mapping property names to schemas`);
+        }
+        else {
+            for (const [key, propSchema] of Object.entries(schema.properties)) {
+                if (isPlainObject(propSchema)) {
+                    checkDefinitionNode(propSchema, [...path, "properties", key], issues, depth + 1);
+                }
+                else {
+                    pushIssue(issues, [...path, "properties", key], "properties", "malformed", `property ${JSON.stringify(key)} must be a schema object`);
+                }
+            }
+        }
+    }
+    if (schema.items !== undefined) {
+        if (isPlainObject(schema.items)) {
+            checkDefinitionNode(schema.items, [...path, "items"], issues, depth + 1);
+        }
+        else if (Array.isArray(schema.items)) {
+            pushIssue(issues, [...path, "items"], "items", "unsupported", `tuple-form "items" (an array of schemas) is not enforced by the workflow schema subset — use a single schema object`);
+        }
+        else {
+            pushIssue(issues, [...path, "items"], "items", "malformed", `"items" must be a schema object`);
+        }
+    }
+    if (schema.additionalProperties !== undefined && typeof schema.additionalProperties !== "boolean") {
+        if (isPlainObject(schema.additionalProperties)) {
+            pushIssue(issues, [...path, "additionalProperties"], "additionalProperties", "unsupported", `schema-form "additionalProperties" is not enforced by the workflow schema subset — only "additionalProperties: false" is`);
+        }
+        else {
+            pushIssue(issues, [...path, "additionalProperties"], "additionalProperties", "malformed", `"additionalProperties" must be a boolean (only "false" is enforced)`);
+        }
+    }
+    for (const keyword of ["minItems", "maxItems", "minLength", "maxLength"]) {
+        const value = schema[keyword];
+        if (value !== undefined && (typeof value !== "number" || !Number.isInteger(value) || value < 0)) {
+            pushIssue(issues, [...path, keyword], keyword, "malformed", `"${keyword}" must be a non-negative integer`);
+        }
+    }
+    for (const keyword of ["minimum", "maximum"]) {
+        const value = schema[keyword];
+        if (value !== undefined && (typeof value !== "number" || !Number.isFinite(value))) {
+            pushIssue(issues, [...path, keyword], keyword, "malformed", `"${keyword}" must be a finite number`);
+        }
+    }
+}
 function typeOf(value) {
     if (value === null)
         return "null";
@@ -52,7 +318,66 @@ function matchesType(actual, expected) {
     // JSON Schema: every integer is also a number.
     return expected === "number" && actual === "integer";
 }
-function validateNode(value, schema, path, errors) {
+/** Evaluate `schema` against `value` in a scratch error list, sharing the caller's budget. */
+function branchErrors(value, schema, path, ctx) {
+    const errors = [];
+    validateNode(value, schema, path, { ...ctx, errors, depth: ctx.depth + 1 });
+    return errors;
+}
+/** The schemas of a combinator keyword, or `[]` when the keyword is absent/malformed (permissive). */
+function combinatorBranches(schema, keyword) {
+    const raw = schema[keyword];
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter(isPlainObject);
+}
+/** First error of each failing branch, truncated — enough to act on without dumping every branch. */
+function summarizeBranchFailures(failures) {
+    const shown = failures.slice(0, 3).map((f) => `${f.index + 1}: ${f.errors[0] ?? "no match"}`);
+    if (failures.length > shown.length)
+        shown.push(`…${failures.length - shown.length} more`);
+    return shown.join("; ");
+}
+function validateCombinators(value, schema, path, ctx) {
+    for (const branch of combinatorBranches(schema, "allOf")) {
+        // `allOf` failures ARE the value's failures — surface them verbatim.
+        ctx.errors.push(...branchErrors(value, branch, path, ctx));
+    }
+    for (const keyword of ["anyOf", "oneOf"]) {
+        const branches = combinatorBranches(schema, keyword);
+        if (branches.length === 0)
+            continue;
+        const failures = [];
+        const matched = [];
+        branches.forEach((branch, index) => {
+            const errors = branchErrors(value, branch, path, ctx);
+            if (errors.length === 0)
+                matched.push(index + 1);
+            else
+                failures.push({ index, errors });
+        });
+        if (matched.length === 0) {
+            ctx.errors.push(`${path}: value matches none of the ${branches.length} "${keyword}" schemas (${summarizeBranchFailures(failures)})`);
+        }
+        else if (keyword === "oneOf" && matched.length > 1) {
+            ctx.errors.push(`${path}: value matches ${matched.length} "oneOf" schemas (branches ${matched.join(", ")}); exactly one must match`);
+        }
+    }
+    const not = schema.not;
+    if (isPlainObject(not) && branchErrors(value, not, path, ctx).length === 0) {
+        ctx.errors.push(`${path}: value must not match the "not" schema`);
+    }
+}
+function validateNode(value, schema, path, ctx) {
+    const errors = ctx.errors;
+    if (ctx.depth > MAX_DEFINITION_DEPTH) {
+        errors.push(`${path}: schema nesting exceeds the depth limit of ${MAX_DEFINITION_DEPTH}`);
+        return;
+    }
+    // Fail CLOSED: a truncated evaluation never returns "valid" — the counter
+    // going negative is what the wrapper turns into a top-level error.
+    if (--ctx.budget.nodes < 0)
+        return;
     const actual = typeOf(value);
     const declared = schema.type;
     if (typeof declared === "string" || Array.isArray(declared)) {
@@ -69,6 +394,10 @@ function validateNode(value, schema, path, errors) {
             return;
         }
     }
+    // Combinators are type-agnostic, so they run BEFORE the per-type branches
+    // below (each of which returns). A schema with no combinator keyword is
+    // untouched by this call.
+    validateCombinators(value, schema, path, ctx);
     if (actual === "string" && typeof value === "string") {
         if (typeof schema.minLength === "number" && value.length < schema.minLength) {
             errors.push(`${path}: string shorter than minLength ${schema.minLength}`);
@@ -97,7 +426,10 @@ function validateNode(value, schema, path, errors) {
         const items = schema.items;
         if (items && typeof items === "object" && !Array.isArray(items)) {
             value.forEach((element, index) => {
-                validateNode(element, items, `${path}[${index}]`, errors);
+                validateNode(element, items, `${path}[${index}]`, {
+                    ...ctx,
+                    depth: ctx.depth + 1,
+                });
             });
         }
         return;
@@ -122,7 +454,10 @@ function validateNode(value, schema, path, errors) {
                 if (!Object.hasOwn(record, key))
                     continue;
                 if (propSchema && typeof propSchema === "object" && !Array.isArray(propSchema)) {
-                    validateNode(record[key], propSchema, `${path}.${key}`, errors);
+                    validateNode(record[key], propSchema, `${path}.${key}`, {
+                        ...ctx,
+                        depth: ctx.depth + 1,
+                    });
                 }
             }
         }

package/dist/core/loopback.js

@@ -0,0 +1,89 @@
+// 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/.
+/**
+ * Loopback classification for LLM endpoints: does this endpoint name a model
+ * server running on THIS machine? A host is loopback when it is `localhost` or
+ * a `*.localhost` name (RFC 6761 §6.3), anywhere in `127.0.0.0/8`, an
+ * unspecified address (`0.0.0.0` / `::` — a client connecting there reaches
+ * local loopback), IPv6 `::1`, or the dotted IPv4-mapped spelling of a
+ * `127.0.0.0/8` address (`::ffff:127.0.0.1`). Address shapes are validated by
+ * `node:net`'s `isIP`, so a near-miss NAME like `127.0.0.1.evil.com` is remote.
+ *
+ * The check is purely syntactic — no DNS, no interface list — so the same
+ * config classifies the same on a laptop, on CI, and on a machine with no
+ * network. Ambiguity resolves toward LOOPBACK: misclassifying a local server
+ * as remote widens a concurrency pool onto a single-threaded local model
+ * (one loaded model, reload thrash, HTTP 500 — a hard failure); the reverse
+ * only costs throughput. The remedy in either direction is one line of config:
+ * `engines.<name>.concurrency`.
+ *
+ * The ONE local-vs-remote answer for concurrency defaults — the workflow
+ * engine's frozen engine concurrency (`workflows/concurrency-policy.ts`) and
+ * the indexer's LLM pool (`indexer/indexer.ts` `getDefaultLlmConcurrency`)
+ * both classify through here. NOT shared with the website snapshot fetcher's
+ * SSRF policy (`sources/snapshot-fetchers/host-guard.ts`), which deliberately
+ * draws different lines for a different threat model.
+ *
+ * @module core/loopback
+ */
+import { isIP } from "node:net";
+/**
+ * The IPv4-mapped IPv6 spellings of `127.0.0.0/8`: the dotted form, whose
+ * capture is validated by `isIP`, and the hex form `::ffff:7fxx:xxxx`. Both are
+ * needed because WHATWG `URL` re-serializes `[::ffff:127.0.0.1]` to the hex
+ * form, so an endpoint written the dotted way arrives here as hex.
+ */
+const IPV4_MAPPED_IPV6 = /^::ffff:(?:([\d.]+)|7f[\da-f]{2}:[\da-f]{1,4})$/;
+/** IPv6 groups before the last one, all of which must be zero (or elided). */
+const ZERO_GROUP = /^0+$/;
+/** The last IPv6 group of `::` / `::1`, in any zero-padding. */
+const LOOPBACK_LAST_GROUP = /^0*[01]?$/;
+/**
+ * True when `host` — a URL host component, with or without IPv6 brackets —
+ * names this machine WITHOUT resolving anything.
+ *
+ * Not recognized: the IPv4-compatible form (`::127.0.0.1`), and any NAME that
+ * merely resolves to loopback.
+ *
+ * Exported for the boundary-case table in
+ * `tests/workflows/concurrency-defaults.test.ts`, which has to reach the host
+ * predicate directly: several of its cases (a bare `""`, a malformed literal
+ * like `1::2::3`) cannot round-trip through a URL without changing meaning.
+ */
+export function isLoopbackHost(host) {
+    // Strip IPv6 brackets (`URL.hostname` keeps them) and the DNS root label. An
+    // empty host (`new URL("localhost:1234")` parses as scheme `localhost:` with
+    // no host) has nothing to judge, so it fails safe like an unparseable one.
+    const name = host.trim().toLowerCase().replace(/^\[/, "").replace(/\]$/, "").replace(/\.$/, "");
+    if (name === "" || name === "localhost" || name.endsWith(".localhost"))
+        return true;
+    const mapped = IPV4_MAPPED_IPV6.exec(name);
+    if (mapped) {
+        const quad = mapped[1];
+        // The hex branch already matched 127.x in the pattern; the dotted one still
+        // needs `isIP` so `::ffff:127.0.0.256` stays remote.
+        return quad === undefined || (isIP(quad) === 4 && quad.startsWith("127."));
+    }
+    const version = isIP(name);
+    if (version === 4)
+        return name.startsWith("127.") || name === "0.0.0.0";
+    if (version !== 6)
+        return false;
+    const groups = name.split(":");
+    const last = groups.pop() ?? "";
+    return groups.every((group) => group === "" || ZERO_GROUP.test(group)) && LOOPBACK_LAST_GROUP.test(last);
+}
+/** True when `endpoint` points at this machine (see {@link isLoopbackHost}). */
+export function isLoopbackEndpoint(endpoint) {
+    if (!endpoint)
+        return true;
+    try {
+        return isLoopbackHost(new URL(endpoint).hostname);
+    }
+    catch {
+        // An unparseable endpoint is treated as local: guessing "remote" here would
+        // widen the pool on exactly the configs we understand least.
+        return true;
+    }
+}

package/dist/core/migration-operation.js

@@ -2,9 +2,9 @@
 // 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 crypto from "node:crypto";
-import fs from "node:fs";
 import path from "node:path";
 import { ConfigError } from "./errors.js";
+import { classifyPathAccess, describeInaccessiblePath } from "./path-access.js";
 import { getConfigPath, getDataDir } from "./paths.js";
 let afterPendingCheckHook;
 /** TEST-ONLY: run once after a clear pending-operation check. */
@@ -45,12 +45,27 @@ export function getMigrationApplyJournalPath() {
 export function getMigrationGeneratedConfigPath() {
     return path.join(getMigrationOperationRoot(), "generated-config.json");
 }
+/**
+ * Refuse canonical config/database access while a migration or restore is
+ * mid-flight.
+ *
+ * This is a SAFETY gate, so "I could not tell" must fail the same way "yes"
+ * does. `fs.existsSync` answered `false` for an unreadable journal exactly as
+ * for an absent one (#791), which meant a permission fault on the journal
+ * silently CLEARED the gate and let akm open the canonical databases on top of
+ * a half-applied migration. Absence is the only answer that may open the door.
+ */
 export function assertNoPendingMigrationOperation() {
     for (const [kind, journalPath] of [
         ["restore", getMigrationRestoreJournalPath()],
         ["migration apply", getMigrationApplyJournalPath()],
     ]) {
-        if (fs.existsSync(journalPath)) {
+        const { access, code } = classifyPathAccess(journalPath);
+        if (access === "inaccessible") {
+            throw new ConfigError(`Cannot determine whether an AKM ${kind} recovery is pending: ${describeInaccessiblePath(journalPath, code)}. ` +
+                "Refusing canonical config/database access — proceeding could write on top of a half-applied migration.", "DATA_DIR_UNREADABLE");
+        }
+        if (access === "present") {
             throw new ConfigError(`AKM ${kind} recovery is pending at ${journalPath}; refusing canonical config/database access until recovery completes.`, "INVALID_CONFIG_FILE");
         }
     }

package/dist/core/path-access.js

@@ -0,0 +1,107 @@
+// 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/.
+/**
+ * Tell "this path is not there" apart from "I am not allowed to look at it"
+ * (issue #791).
+ *
+ * # Why this exists
+ *
+ * `fs.existsSync()` answers `false` for BOTH cases: it swallows every error,
+ * so `ENOENT` (genuinely absent) and `EACCES` (present, unreadable) are
+ * indistinguishable. akm used `existsSync` as its "is there an index?" gate on
+ * the read path, so an index the caller could not read was reported as an index
+ * that did not exist — `akm search` and `akm curate` returned
+ * `hits: []` with the tip *"No search index available. Run 'akm index' to build
+ * one."* at exit 0, for a populated index sitting right there on disk.
+ *
+ * That is the worst possible shape for a failure. A non-zero exit is a problem
+ * the operator can see; an empty-but-successful result is a lie that a
+ * consuming agent will confidently relay to its user. In the report that
+ * prompted this module, exactly that happened: an agent told its user akm's
+ * "vector service is unavailable and its maintenance lock is read-only" — a
+ * story it invented to explain results that claimed to be fine.
+ *
+ * # Contract
+ *
+ * `absent` means the path (or a parent component) genuinely is not there, which
+ * is a legitimate first-run state every caller already handles. `inaccessible`
+ * means the path may well exist and this process cannot determine that or read
+ * it — a caller must NEVER degrade that to an empty-but-successful result.
+ */
+import fs from "node:fs";
+function errnoOf(error) {
+    const code = error?.code;
+    return typeof code === "string" ? code : undefined;
+}
+/**
+ * Classify `target` as {@link PathAccess}.
+ *
+ * `ENOENT`/`ENOTDIR` are `absent` — the path cannot exist as named. Everything
+ * else that fails is `inaccessible`, carrying its errno: a permission error is
+ * the common case, but a symlink loop or an I/O error are equally "present as
+ * far as anyone knows, and unusable", and silently treating them as "no index"
+ * is the bug this module exists to prevent.
+ *
+ * Statting is not enough — a file can be `stat`-able through a searchable
+ * parent while being unreadable itself — so a successful stat is confirmed with
+ * an `R_OK` access check.
+ */
+export function classifyPathAccess(target) {
+    try {
+        fs.statSync(target);
+    }
+    catch (error) {
+        const code = errnoOf(error);
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return { access: "absent" };
+        return { access: "inaccessible", ...(code ? { code } : {}) };
+    }
+    try {
+        fs.accessSync(target, fs.constants.R_OK);
+    }
+    catch (error) {
+        const code = errnoOf(error);
+        return { access: "inaccessible", ...(code ? { code } : {}) };
+    }
+    return { access: "present" };
+}
+/** True when the path is genuinely absent — the ordinary "not built yet" state. */
+export function isPathAbsent(target) {
+    return classifyPathAccess(target).access === "absent";
+}
+/**
+ * A diagnostic line naming everything an operator needs to fix a permission
+ * problem without a second round trip: the path, the errno, the mode and owner
+ * of whatever akm *could* stat along the way, and the uid actually running.
+ *
+ * Deliberately best-effort — this runs on an error path, so a failure to gather
+ * detail must never mask the error being described.
+ */
+export function describeInaccessiblePath(target, code) {
+    const parts = [target];
+    if (code)
+        parts.push(`(${code})`);
+    try {
+        const stat = fs.statSync(target);
+        parts.push(`mode ${(stat.mode & 0o777).toString(8).padStart(3, "0")}, owner uid ${stat.uid}`);
+    }
+    catch {
+        // Cannot stat the file itself — describe the closest parent we CAN see,
+        // which is usually where the missing permission actually is.
+        const parent = target.slice(0, Math.max(0, target.lastIndexOf("/")));
+        if (parent) {
+            try {
+                const stat = fs.statSync(parent);
+                parts.push(`parent ${parent} is mode ${(stat.mode & 0o777).toString(8).padStart(3, "0")}, owner uid ${stat.uid}`);
+            }
+            catch {
+                // Nothing further to say.
+            }
+        }
+    }
+    const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+    if (uid !== undefined)
+        parts.push(`running as uid ${uid}`);
+    return parts.join("; ");
+}

package/dist/core/paths.js

@@ -160,9 +160,23 @@ export function getCacheDir(env = process.env) {
     }
     const home = env.HOME?.trim();
     if (!home)
-        return path.join("/tmp", "akm-cache");
+        return homelessFallbackDir("akm-cache");
     return path.join(home, ".cache", "akm");
 }
+/**
+ * Last-resort directory when neither the XDG variable nor HOME is set.
+ *
+ * Scoped by uid. A fixed `/tmp/akm-<kind>` path is world-shared and entirely
+ * predictable: on a multi-user host the first uid to run akm owns the
+ * directory and every other user then reads and writes the same databases, and
+ * any local user can pre-create the path (or a symlink at it) and wait. Adding
+ * the uid gives each account its own path; the caller still creates it with
+ * restrictive permissions.
+ */
+function homelessFallbackDir(kind) {
+    const uid = typeof process.getuid === "function" ? process.getuid() : undefined;
+    return path.join(os.tmpdir(), uid === undefined ? kind : `${kind}-${uid}`);
+}
 // ── Data directory ───────────────────────────────────────────────────────────
 /**
  * Returns the XDG data directory for akm (`~/.local/share/akm` on Linux/macOS,
@@ -209,7 +223,7 @@ export function getDataDir(env = process.env, platform = process.platform) {
         return path.join(xdgDataHome, "akm");
     const home = env.HOME?.trim();
     if (!home)
-        return path.join("/tmp", "akm-data");
+        return homelessFallbackDir("akm-data");
     return path.join(home, ".local", "share", "akm");
 }
 export function getDbPath(env = process.env) {