akm-cli 0.9.0 → 0.9.1-beta.1

package/dist/core/events.js

@@ -4,6 +4,7 @@
 import { insertEvent, readStateEvents } from "../storage/repositories/events-repository.js";
 import { rethrowIfTestIsolationError } from "./errors.js";
 import { getStateDbPath, openStateDatabase, withStateDb } from "./state-db.js";
+import { borrowScopedStateDb } from "./state-db-scope.js";
 import { error } from "./warn.js";
 /**
  * Resolve the state.db path from context:
@@ -28,36 +29,41 @@ function resolveNow(ctx) {
  * function writes directly to that handle without opening or closing the DB.
  * This eliminates per-event open/migrate/close overhead for high-frequency
  * callers such as `akmImprove`.
+ *
+ * The same fast path is taken IMPLICITLY inside a `withStateDbScope` /
+ * `withWorkflowRunsConnection` scope (`core/state-db-scope.ts`): the ambient
+ * scoped handle for this event's resolved `dbPath` is borrowed, so a workflow
+ * step's `workflow_unit_started` / `workflow_unit_finished` pair rides the same
+ * connection its journal rows do instead of opening state.db twice per unit.
+ * The scope owns that handle's lifetime; `appendEvent` never closes a borrowed
+ * connection.
  */
 export function appendEvent(input, ctx) {
     const now = resolveNow(ctx);
     const ts = new Date(now()).toISOString();
-    // Fast path: caller provided a long-lived connection — use it directly.
-    if (ctx?.db) {
-        try {
-            insertEvent(ctx.db, {
-                eventType: input.eventType,
-                ts,
-                ref: input.ref,
-                metadata: input.metadata,
-            });
+    const row = { eventType: input.eventType, ts, ref: input.ref, metadata: input.metadata };
+    // One try covers EVERY path — including resolving the state.db path, which
+    // reads the environment and throws where no data dir can be derived — so the
+    // best-effort contract ("a write failure never propagates") holds no matter
+    // which handle this event lands on.
+    try {
+        // Fast path: an explicitly supplied long-lived connection. Resolution is
+        // skipped outright, which is what "`dbPath` is ignored when `db` is
+        // provided" has to mean for a caller that already holds an open handle.
+        if (ctx?.db) {
+            insertEvent(ctx.db, row);
+            return;
         }
-        catch (err) {
-            error(`akm: appendEvent failed: ${String(err)}`);
+        const dbPath = resolveDbPath(ctx);
+        // The ambient scoped handle for this path, when a scope is open — borrowed
+        // exactly like the explicit one, and never closed here.
+        const borrowed = borrowScopedStateDb(dbPath);
+        if (borrowed) {
+            insertEvent(borrowed, row);
+            return;
         }
-        return;
-    }
-    // Default path: open, insert, close.
-    const dbPath = resolveDbPath(ctx);
-    try {
-        withStateDb((db) => {
-            insertEvent(db, {
-                eventType: input.eventType,
-                ts,
-                ref: input.ref,
-                metadata: input.metadata,
-            });
-        }, { path: dbPath });
+        // Default path: open, insert, close.
+        withStateDb((db) => insertEvent(db, row), { path: dbPath });
     }
     catch (err) {
         // Never mask the bun-test isolation guard as a silent "events failed".

package/dist/core/file-lock.js

@@ -139,7 +139,13 @@ export function probeLock(lockPath, opts) {
     try {
         snapshot = readLockSnapshot(lockPath);
     }
-    catch {
+    catch (error) {
+        // A permission error means the lock may be genuinely HELD by someone we
+        // cannot see. Reporting it as stale would invite a caller to steal a live
+        // lease (#791) — `unreadable` stays for the corrupt/undecodable case.
+        const code = error?.code;
+        if (code === "EACCES" || code === "EPERM")
+            return { state: "inaccessible", code };
         return { state: "stale", reason: "unreadable" };
     }
     if (!snapshot)

package/dist/core/improve-result.js

@@ -40,6 +40,7 @@ const COMMON_FIELDS = [
     "cycleMetrics",
     "runId",
     "sync",
+    "writtenPaths",
     "terminated",
 ];
 const V2_FIELDS = new Set([...COMMON_FIELDS, "strategy", "strategyFilteredRefs"]);
@@ -83,10 +84,14 @@ function validateCommon(value) {
         "extract",
         "coverageGaps",
         "deadUrls",
+        "writtenPaths",
     ]) {
         if (value[field] !== undefined && !Array.isArray(value[field]))
             fail(`${field} must be an array`);
     }
+    if (Array.isArray(value.writtenPaths) && value.writtenPaths.some((entry) => typeof entry !== "string")) {
+        fail("writtenPaths must be an array of strings");
+    }
     for (const field of [
         "cyclesRun",
         "evalCasesWritten",

package/dist/core/json-schema.js

@@ -14,22 +14,271 @@
  *   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);
+}
+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 && (!Array.isArray(schema.enum) || schema.enum.length === 0)) {
+        pushIssue(issues, [...path, "enum"], "enum", "malformed", `"enum" must be a non-empty array of allowed values`);
+    }
+    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 +301,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 +377,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 +409,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 +437,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");
         }
     }