akm-cli 0.9.1 → 0.9.2-alpha.2

package/dist/sources/snapshot-fetchers/host-guard.js

@@ -1,9 +1,8 @@
 // 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 { lookup as dnsLookup } from "node:dns/promises";
-import { isIP } from "node:net";
 import { fetchWithRetry, readBodyWithByteCap } from "../../core/common.js";
+import { bareHostname, classifyNetworkAddress, classifyNetworkHostname, resolveHostnameAddresses, } from "../../core/network-policy.js";
 /** Redirect budget for a single guarded request chain. */
 const MAX_GUARDED_REDIRECTS = 8;
 export function assertWebsiteRequestUrl(rawUrl, ErrorType = Error, options) {
@@ -22,10 +21,6 @@ export function assertWebsiteRequestUrl(rawUrl, ErrorType = Error, options) {
         throw new ErrorType(`Refusing to fetch non-public website host: ${parsedUrl.hostname}`);
     }
 }
-async function defaultResolveHostname(hostname) {
-    const records = await dnsLookup(hostname, { all: true });
-    return records.map((record) => record.address);
-}
 /**
  * Resolve-then-validate SSRF guard against DNS rebinding / private-range
  * bypasses. {@link assertWebsiteRequestUrl} only rejects IP-literal and
@@ -46,18 +41,16 @@ async function defaultResolveHostname(hostname) {
 export async function assertResolvedHostAllowed(hostname, options) {
     if (options?.allowPrivateHosts === true)
         return;
-    const bare = stripIpv6Brackets(hostname.toLowerCase());
-    const literalVersion = isIP(bare);
-    if (literalVersion !== 0) {
-        const forbidden = literalVersion === 4 ? isForbiddenIpv4(bare) : isForbiddenIpv6(bare);
-        if (forbidden)
+    const bare = bareHostname(hostname.toLowerCase());
+    const literalClass = classifyNetworkAddress(bare);
+    if (literalClass !== "invalid") {
+        if (literalClass !== "public")
             throw new Error(`Refusing to fetch non-public website host: ${hostname}`);
         return;
     }
-    const resolve = options?.resolveHostname ?? defaultResolveHostname;
     let addresses;
     try {
-        addresses = await resolve(bare);
+        addresses = await resolveHostnameAddresses(bare, options?.resolveHostname);
     }
     catch {
         throw new Error(`Refusing to fetch ${hostname}: DNS resolution failed`);
@@ -66,138 +59,18 @@ export async function assertResolvedHostAllowed(hostname, options) {
         throw new Error(`Refusing to fetch ${hostname}: hostname resolved to no addresses`);
     }
     for (const address of addresses) {
-        const version = isIP(address);
-        const forbidden = version === 4 ? isForbiddenIpv4(address) : version === 6 ? isForbiddenIpv6(stripIpv6Brackets(address)) : true;
-        if (forbidden) {
+        if (classifyNetworkAddress(address) !== "public") {
             throw new Error(`Refusing to fetch ${hostname}: resolves to non-public or unparseable address ${address}`);
         }
     }
 }
-// WHATWG URL.hostname wraps IPv6 literals in brackets (e.g. "[::1]"), but
-// node:net's isIP() only recognizes the bare address form and returns 0 for
-// anything bracketed — silently skipping all IPv6 forbidden-host checks
-// below for every hostname parsed off a URL. Strip the brackets before any
-// isIP()/isForbiddenIpv6() call so those checks actually run.
-function stripIpv6Brackets(hostname) {
-    return hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
-}
 function isForbiddenWebsiteHostname(hostname, options) {
     if (options?.allowPrivateHosts === true)
         return false;
-    if (hostname === "localhost" || hostname.endsWith(".localhost") || hostname === "metadata.google.internal") {
-        return true;
-    }
-    const bareHostname = stripIpv6Brackets(hostname);
-    const ipVersion = isIP(bareHostname);
-    if (ipVersion === 4)
-        return isForbiddenIpv4(bareHostname);
-    if (ipVersion === 6)
-        return isForbiddenIpv6(bareHostname);
-    return false;
+    return classifyNetworkHostname(hostname) !== "public";
 }
 export function isLoopbackWebsiteHostname(hostname) {
-    if (hostname === "localhost" || hostname.endsWith(".localhost"))
-        return true;
-    const bareHostname = stripIpv6Brackets(hostname);
-    const ipVersion = isIP(bareHostname);
-    if (ipVersion === 4)
-        return bareHostname.startsWith("127.");
-    if (ipVersion === 6)
-        return bareHostname === "::1";
-    return false;
-}
-function isForbiddenIpv4(hostname) {
-    const parts = hostname.split(".").map((part) => Number.parseInt(part, 10));
-    const [a = -1, b = -1, c = -1, d = -1] = parts;
-    if (parts.length !== 4 || [a, b, c, d].some((part) => !Number.isInteger(part) || part < 0 || part > 255)) {
-        return true;
-    }
-    return (a === 0 ||
-        a === 10 ||
-        (a === 100 && b >= 64 && b <= 127) ||
-        a === 127 ||
-        (a === 169 && b === 254) ||
-        (a === 172 && b >= 16 && b <= 31) ||
-        (a === 192 && b === 0 && c === 0 && d !== 9 && d !== 10) ||
-        (a === 192 && b === 0 && c === 2) ||
-        (a === 192 && b === 168) ||
-        (a === 192 && b === 88 && c === 99) ||
-        (a === 198 && (b === 18 || b === 19)) ||
-        (a === 198 && b === 51 && c === 100) ||
-        (a === 203 && b === 0 && c === 113) ||
-        a >= 224);
-}
-function parseIpv6Words(hostname) {
-    let normalized;
-    try {
-        normalized = stripIpv6Brackets(new URL(`http://[${stripIpv6Brackets(hostname)}]/`).hostname).toLowerCase();
-    }
-    catch {
-        return null;
-    }
-    const halves = normalized.split("::");
-    if (halves.length > 2)
-        return null;
-    const left = halves[0] ? halves[0].split(":") : [];
-    const right = halves[1] ? halves[1].split(":") : [];
-    const missing = 8 - left.length - right.length;
-    if ((halves.length === 1 && missing !== 0) || (halves.length === 2 && missing < 1))
-        return null;
-    const parts = halves.length === 2 ? [...left, ...Array(missing).fill("0"), ...right] : left;
-    if (parts.length !== 8 || parts.some((part) => !/^[0-9a-f]{1,4}$/.test(part)))
-        return null;
-    return parts.map((part) => Number.parseInt(part, 16));
-}
-function ipv6Value(hostname) {
-    const words = parseIpv6Words(hostname);
-    if (!words)
-        return null;
-    return words.reduce((value, word) => (value << 16n) | BigInt(word), 0n);
-}
-const FORBIDDEN_IPV6_RANGES = [
-    ["64:ff9b:1::", 48],
-    ["100::", 64],
-    ["2001::", 32],
-    ["2001:2::", 48],
-    ["2001:10::", 28],
-    ["2001:20::", 28],
-    ["2001:db8::", 32],
-    ["3fff::", 20],
-    ["5f00::", 16],
-    ["fc00::", 7],
-    ["fe80::", 10],
-    ["fec0::", 10],
-    ["ff00::", 8],
-];
-function embeddedIpv4Address(words) {
-    const firstSixZero = words.slice(0, 6).every((word) => word === 0);
-    const mapped = words.slice(0, 5).every((word) => word === 0) && words[5] === 0xffff;
-    const translated = words.slice(0, 4).every((word) => word === 0) && words[4] === 0xffff && words[5] === 0;
-    const wellKnownNat64 = words[0] === 0x64 && words[1] === 0xff9b && words.slice(2, 6).every((word) => word === 0);
-    if (words[0] === 0x2002)
-        return ipv4FromHextets(words[1] ?? 0, words[2] ?? 0);
-    if (!firstSixZero && !mapped && !translated && !wellKnownNat64)
-        return null;
-    return ipv4FromHextets(words[6] ?? 0, words[7] ?? 0);
-}
-function ipv4FromHextets(high, low) {
-    return `${(high >> 8) & 0xff}.${high & 0xff}.${(low >> 8) & 0xff}.${low & 0xff}`;
-}
-function isForbiddenIpv6(hostname) {
-    const words = parseIpv6Words(hostname);
-    const value = ipv6Value(hostname);
-    if (!words || value === null)
-        return true;
-    const embeddedIpv4 = embeddedIpv4Address(words);
-    if (embeddedIpv4)
-        return isForbiddenIpv4(embeddedIpv4);
-    return FORBIDDEN_IPV6_RANGES.some(([prefix, bits]) => {
-        const prefixValue = ipv6Value(prefix);
-        if (prefixValue === null)
-            return true;
-        const shift = BigInt(128 - bits);
-        return value >> shift === prefixValue >> shift;
-    });
+    return classifyNetworkHostname(hostname) === "loopback";
 }
 function redirectInit(init, currentUrl, nextUrl) {
     if (new URL(currentUrl).origin === new URL(nextUrl).origin)

package/dist/sources/snapshot-fetchers/website-ingest.js

@@ -1,18 +1,18 @@
 // 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 { createHash, randomBytes } from "node:crypto";
+import { randomBytes } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { fetchWithRetry, isWithin, ResponseTooLargeError, readBodyWithByteCap, resolveStashDir, todayIso, } from "../../core/common.js";
 import { ConfigError, UsageError } from "../../core/errors.js";
-import { getRegistryIndexCacheDir } from "../../core/paths.js";
 import { warn, warnVerbose } from "../../core/warn.js";
 import { withFreshnessCache } from "../freshness.js";
 import { sanitizeString } from "../providers/provider-utils.js";
+import { getWebsiteCachePaths, normalizeSiteUrl, validateWebsiteInputUrl, validateWebsiteUrl, } from "../website-url.js";
 import { htmlToMarkdownAndLinks } from "./content-extract.js";
 import { escapeMarkdownStructure } from "./fetcher-util.js";
-import { assertResolvedHostAllowed, assertWebsiteRequestUrl, isLoopbackWebsiteHostname, } from "./host-guard.js";
+import { assertResolvedHostAllowed, assertWebsiteRequestUrl } from "./host-guard.js";
 import { loadWikiSnapshotFetchers } from "./registry.js";
 import { createAllowAllRobotsPolicy, createRobotsPolicy, isPathAllowedByRobots, ROBOTS_BODY_TIMEOUT_MS, ROBOTS_BYTE_CAP, } from "./robots.js";
 /** Refresh website snapshots every 12 hours to balance freshness with scraping load. */
@@ -37,25 +37,15 @@ const WEBSITE_PAGE_BYTE_CAP = 5 * 1024 * 1024;
  */
 const WEBSITE_CRAWL_WALL_CLOCK_MS = 10 * 60 * 1000;
 const WEBSITE_MAX_REDIRECTS = 8;
-/**
- * Coerces the user-facing `crawlTimeoutMs` option.
- *
- * Returns `null` for an explicit opt-out (`false`, or `0`), the configured
- * number of milliseconds when positive, and `undefined` to mean "unset, use
- * the default". Anything else is ignored rather than failing a crawl over a
- * malformed knob.
- */
-function coerceCrawlTimeoutMs(value) {
-    if (value === false || value === 0)
-        return null;
-    if (value === true || value === undefined || value === null)
-        return undefined;
-    const parsed = typeof value === "number" ? value : typeof value === "string" ? Number.parseInt(value, 10) : Number.NaN;
-    if (!Number.isFinite(parsed))
+/** Resolve the exact persisted crawl timeout; zero explicitly disables it. */
+export function resolveCrawlTimeoutMs(value) {
+    if (value === undefined)
         return undefined;
-    if (parsed <= 0)
+    if (value === 0)
         return null;
-    return parsed;
+    if (typeof value === "number" && Number.isInteger(value) && value > 0)
+        return value;
+    throw new ConfigError(`Invalid value for crawlTimeoutMs: expected a non-negative integer, got ${JSON.stringify(value)}.`);
 }
 /**
  * How many times a URL may be pushed back for not fitting its origin's
@@ -70,19 +60,6 @@ const MAX_CRAWL_DEFERRALS = 3;
  * wall-clock cap elapses.
  */
 const WEBSITE_PAGE_BODY_TIMEOUT_MS = 30_000;
-export function shouldAllowPrivateWebsiteHostsForTests() {
-    return process.env.BUN_TEST === "1" || process.env.NODE_ENV === "test";
-}
-export function shouldAllowPrivateWebsiteUrlForTests(rawUrl) {
-    if (!shouldAllowPrivateWebsiteHostsForTests())
-        return false;
-    try {
-        return isLoopbackWebsiteHostname(new URL(rawUrl).hostname.toLowerCase());
-    }
-    catch {
-        return false;
-    }
-}
 function resolveFetcherStashDir(explicitStashDir) {
     if (explicitStashDir)
         return explicitStashDir;
@@ -93,19 +70,10 @@ function resolveFetcherStashDir(explicitStashDir) {
         return null;
     }
 }
-export function getWebsiteCachePaths(siteUrl) {
-    const key = createHash("sha256").update(normalizeSiteUrl(siteUrl)).digest("hex").slice(0, 16);
-    const rootDir = path.join(getRegistryIndexCacheDir(), `website-${key}`);
-    return {
-        rootDir,
-        stashDir: path.join(rootDir, "stash"),
-        manifestPath: path.join(rootDir, "manifest.json"),
-    };
-}
 export async function ensureWebsiteMirror(config, options) {
     const rawUrl = config.url ?? "";
     const normalizedUrl = validateWebsiteUrl(rawUrl, { allowPrivateHosts: options?.allowPrivateHosts });
-    const cachePaths = getWebsiteCachePaths(normalizedUrl);
+    const cachePaths = getWebsiteCachePaths(normalizedUrl, options?.cacheRootDir);
     const requireStashDir = options?.requireStashDir === true;
     await withFreshnessCache({
         markerPath: cachePaths.manifestPath,
@@ -117,12 +85,12 @@ export async function ensureWebsiteMirror(config, options) {
             fs.mkdirSync(cachePaths.rootDir, { recursive: true });
             await scrapeWebsiteToStash(normalizedUrl, cachePaths.stashDir, {
                 fetcherStashDir: resolveFetcherStashDir(),
-                maxPages: coercePositiveInt(config.options?.maxPages, MAX_PAGES_DEFAULT),
-                maxDepth: coercePositiveInt(config.options?.maxDepth, MAX_DEPTH_DEFAULT),
-                respectRobots: coerceRespectRobots(config.options?.respectRobots),
+                maxPages: resolvePositiveInt(config.options?.maxPages, MAX_PAGES_DEFAULT, "maxPages"),
+                maxDepth: resolvePositiveInt(config.options?.maxDepth, MAX_DEPTH_DEFAULT, "maxDepth"),
+                respectRobots: resolveRespectRobots(config.options?.respectRobots),
                 allowPrivateHosts: options?.allowPrivateHosts,
                 wallClockCapMs: options?.wallClockCapMs,
-                crawlTimeoutMs: coerceCrawlTimeoutMs(config.options?.crawlTimeoutMs),
+                crawlTimeoutMs: resolveCrawlTimeoutMs(config.options?.crawlTimeoutMs),
                 resolveSecret: options?.resolveSecret,
                 // As-supplied, pre-normalization start URL (see crawlWebsite's
                 // `rawStartUrl` doc comment): threaded through purely for the C-02
@@ -544,7 +512,7 @@ async function crawlWebsite(startUrl, options) {
     const visited = new Set();
     const pages = [];
     // Precedence: the test-only seam, then the user's `crawlTimeoutMs`, then the
-    // default. `crawlTimeoutMs: 0` / `false` disables the cap outright, for a
+    // default. `crawlTimeoutMs: 0` disables the cap outright, for a
     // deliberately long-running crawl the user is willing to babysit.
     const configuredCapMs = options.crawlTimeoutMs === null ? null : (options.crawlTimeoutMs ?? WEBSITE_CRAWL_WALL_CLOCK_MS);
     const wallClockCapMs = options.wallClockCapMs ?? configuredCapMs;
@@ -866,28 +834,13 @@ export async function loadRobotsTxt(robotsUrl, options) {
         return { kind: "unavailable" };
     }
 }
-/**
- * Coerces `SourceConfigEntry.options.respectRobots` to a boolean. The bundle
- * descriptor is boolean-validated at config load (schema), but the legacy
- * `sources[].options` bag is `z.record(z.unknown())` and accepts anything, so
- * the runtime read still validates. A misspelled non-boolean opt-out fails
- * loudly (`ConfigError`) rather than silently defaulting either way — the
- * user would otherwise think robots.txt handling is something other than
- * what akm is actually doing (spec §4.7).
- */
-export function coerceRespectRobots(value) {
-    if (value === undefined || value === null)
+/** Resolve the exact persisted robots policy. */
+export function resolveRespectRobots(value) {
+    if (value === undefined)
         return true;
     if (typeof value === "boolean")
         return value;
-    if (typeof value === "string") {
-        const normalized = value.trim().toLowerCase();
-        if (normalized === "true")
-            return true;
-        if (normalized === "false")
-            return false;
-    }
-    throw new ConfigError(`Invalid value for respectRobots: expected a boolean (or "true"/"false"), got ${JSON.stringify(value)}.`);
+    throw new ConfigError(`Invalid value for respectRobots: expected a boolean, got ${JSON.stringify(value)}.`);
 }
 function buildMarkdownSnapshot(page, slug, tags) {
     const title = sanitizeString(page.title, 200) || slug;
@@ -917,41 +870,6 @@ function buildMarkdownSnapshot(page, slug, tags) {
         "",
     ].join("\n");
 }
-export function validateWebsiteUrl(rawUrl, options) {
-    return validateWebsiteUrlWithError(rawUrl, ConfigError, options);
-}
-export function validateWebsiteInputUrl(rawUrl, options) {
-    return validateWebsiteUrlWithError(rawUrl, UsageError, options);
-}
-function validateWebsiteUrlWithError(rawUrl, ErrorType, options) {
-    if (!rawUrl) {
-        throw new ErrorType("Website provider requires a URL");
-    }
-    let parsed;
-    try {
-        parsed = new URL(rawUrl);
-    }
-    catch {
-        throw new ErrorType(`Website URL is not valid: "${rawUrl}"`);
-    }
-    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-        throw new ErrorType(`Website URL must use http:// or https://, got "${parsed.protocol}" in "${rawUrl}"`);
-    }
-    if (parsed.username || parsed.password) {
-        throw new ErrorType("Website URL must not contain embedded credentials");
-    }
-    assertWebsiteRequestUrl(parsed.toString(), ErrorType, options);
-    parsed.hash = "";
-    return normalizeSiteUrl(parsed.toString());
-}
-function normalizeSiteUrl(rawUrl) {
-    const parsed = new URL(rawUrl);
-    parsed.hash = "";
-    if (parsed.pathname !== "/" && parsed.pathname.endsWith("/")) {
-        parsed.pathname = parsed.pathname.replace(/\/+$/, "");
-    }
-    return parsed.toString();
-}
 function normalizeCrawlUrl(rawUrl) {
     try {
         const parsed = new URL(rawUrl);
@@ -1024,15 +942,12 @@ function uniqueSlug(base, used) {
     used.add(candidate);
     return candidate;
 }
-function coercePositiveInt(value, fallback) {
+export function resolvePositiveInt(value, fallback, optionName) {
+    if (value === undefined)
+        return fallback;
     if (typeof value === "number" && Number.isInteger(value) && value > 0)
         return value;
-    if (typeof value === "string") {
-        const parsed = Number.parseInt(value, 10);
-        if (Number.isInteger(parsed) && parsed > 0)
-            return parsed;
-    }
-    return fallback;
+    throw new ConfigError(`Invalid value for ${optionName}: expected a positive integer, got ${JSON.stringify(value)}.`);
 }
 function looksLikeMarkup(body) {
     return /<html[\s>]|<body[\s>]|<\/[a-z][\w:-]*>/i.test(body);
@@ -1101,5 +1016,6 @@ function safeCodePointToString(value) {
         return undefined;
     }
 }
+export { getWebsiteCachePaths, normalizeSiteUrl, shouldAllowPrivateWebsiteHostsForTests, shouldAllowPrivateWebsiteUrlForTests, validateWebsiteInputUrl, validateWebsiteUrl, } from "../website-url.js";
 // Re-exported for existing importers (the SSRF suite pins these entry points).
 export { assertResolvedHostAllowed } from "./host-guard.js";

package/dist/sources/website-url.js

@@ -0,0 +1,73 @@
+// 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/.
+/**
+ * Leaf URL and cache-path derivations shared by website source providers and
+ * the website ingest pipeline.
+ *
+ * Keep this module independent of website-ingest and the snapshot-fetcher
+ * registry. Provider registration must be safe to import from low-level source
+ * resolution code without pulling the fetcher subgraph into that leaf.
+ */
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { ConfigError, UsageError } from "../core/errors.js";
+import { getRegistryIndexCacheDir } from "../core/paths.js";
+import { assertWebsiteRequestUrl, isLoopbackWebsiteHostname, } from "./snapshot-fetchers/host-guard.js";
+export function shouldAllowPrivateWebsiteHostsForTests() {
+    return process.env.BUN_TEST === "1" || process.env.NODE_ENV === "test";
+}
+export function shouldAllowPrivateWebsiteUrlForTests(rawUrl) {
+    if (!shouldAllowPrivateWebsiteHostsForTests())
+        return false;
+    try {
+        return isLoopbackWebsiteHostname(new URL(rawUrl).hostname.toLowerCase());
+    }
+    catch {
+        return false;
+    }
+}
+export function getWebsiteCachePaths(siteUrl, cacheRootOverride) {
+    const key = createHash("sha256").update(normalizeSiteUrl(siteUrl)).digest("hex").slice(0, 16);
+    const rootDir = path.join(cacheRootOverride ?? getRegistryIndexCacheDir(), `website-${key}`);
+    return {
+        rootDir,
+        stashDir: path.join(rootDir, "stash"),
+        manifestPath: path.join(rootDir, "manifest.json"),
+    };
+}
+export function validateWebsiteUrl(rawUrl, options) {
+    return validateWebsiteUrlWithError(rawUrl, ConfigError, options);
+}
+export function validateWebsiteInputUrl(rawUrl, options) {
+    return validateWebsiteUrlWithError(rawUrl, UsageError, options);
+}
+function validateWebsiteUrlWithError(rawUrl, ErrorType, options) {
+    if (!rawUrl) {
+        throw new ErrorType("Website provider requires a URL");
+    }
+    let parsed;
+    try {
+        parsed = new URL(rawUrl);
+    }
+    catch {
+        throw new ErrorType(`Website URL is not valid: "${rawUrl}"`);
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new ErrorType(`Website URL must use http:// or https://, got "${parsed.protocol}" in "${rawUrl}"`);
+    }
+    if (parsed.username || parsed.password) {
+        throw new ErrorType("Website URL must not contain embedded credentials");
+    }
+    assertWebsiteRequestUrl(parsed.toString(), ErrorType, options);
+    parsed.hash = "";
+    return normalizeSiteUrl(parsed.toString());
+}
+export function normalizeSiteUrl(rawUrl) {
+    const parsed = new URL(rawUrl);
+    parsed.hash = "";
+    if (parsed.pathname !== "/" && parsed.pathname.endsWith("/")) {
+        parsed.pathname = parsed.pathname.replace(/\/+$/, "");
+    }
+    return parsed.toString();
+}

package/dist/storage/engines/sqlite-migrations.js

@@ -9,12 +9,12 @@ export function assertMigrationRegistry(migrations) {
         seen.add(migration.id);
     }
 }
-function migrationsTableExists(db) {
+export function migrationLedgerExists(db) {
     return !!db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'schema_migrations'").get();
 }
 /** Inspect the database's applied IDs against the exact ordered registry prefix. */
 function inspectLedgerAgainst(db, registryIds) {
-    if (!migrationsTableExists(db))
+    if (!migrationLedgerExists(db))
         return { status: registryIds.length === 0 ? "current" : "old", migrationIds: [] };
     const rows = db.prepare("SELECT id FROM schema_migrations ORDER BY rowid").all();
     const migrationIds = rows.map((row) => row.id);
@@ -53,13 +53,6 @@ export function assertMigrationLedger(db, migrations) {
     }
     return state;
 }
-export function assertCurrentMigrationLedger(db, migrations) {
-    const state = assertMigrationLedger(db, migrations);
-    if (state.status !== "current") {
-        throw new Error(`Refusing to open an obsolete writable schema; run \`akm migrate apply\`: ${state.detail ?? "pending migrations"}.`);
-    }
-    return state;
-}
 /**
  * Create the migrations ledger table if it does not exist. Must be called
  * unconditionally on every open so a fresh database bootstraps correctly.
@@ -73,13 +66,14 @@ export function ensureMigrationsTable(db) {
   `);
 }
 /**
- * Apply every pending migration, one transaction per migration.
+ * Apply every pending migration, normally one transaction per migration.
  *
  * Each migration is applied in its own transaction so a failure in migration N
  * does not roll back already-applied migrations 1..N-1. The migration row is
- * inserted AFTER the DDL succeeds, so a crash mid-migration leaves no row and
- * the migration is retried on next open (all DDL in `up` uses IF NOT EXISTS so
- * the retry is safe).
+ * inserted after the DDL succeeds in the same transaction, so a crash rolls
+ * back both that migration's SQL and its ledger row. A caller may explicitly
+ * group the initial prefix when ledger initialization and dependent early
+ * migrations form one safety boundary.
  *
  * @param db          The open SQLite database.
  * @param migrations  The module's ordered, append-only migration list.
@@ -87,13 +81,44 @@ export function ensureMigrationsTable(db) {
  */
 export function runMigrations(db, migrations, opts) {
     assertMigrationRegistry(migrations);
-    if (opts?.applyPending === false) {
+    const lockedPrefixThrough = opts?.lockInitialMigrationPrefixThrough;
+    const lockedPrefixEnd = lockedPrefixThrough
+        ? migrations.findIndex((migration) => migration.id === lockedPrefixThrough)
+        : -1;
+    if (lockedPrefixThrough && lockedPrefixEnd < 0) {
+        throw new Error(`Initial locked migration prefix ends at unknown migration ID ${lockedPrefixThrough}.`);
+    }
+    if (lockedPrefixEnd >= 0) {
+        withImmediateWriteLock(db, () => {
+            if (!migrationLedgerExists(db)) {
+                opts?.beforeLedgerInitializationLocked?.(db);
+                ensureMigrationsTable(db);
+            }
+            assertMigrationLedger(db, migrations);
+            for (const migration of migrations.slice(0, lockedPrefixEnd + 1)) {
+                const already = db.prepare("SELECT 1 FROM schema_migrations WHERE id = ?").get(migration.id);
+                if (already)
+                    continue;
+                opts?.beforeMigration?.(migration);
+                opts?.beforeMigrationLocked?.(migration, db);
+                db.exec(migration.up);
+                db.prepare("INSERT INTO schema_migrations (id) VALUES (?)").run(migration.id);
+            }
+        });
         assertMigrationLedger(db, migrations);
-        return;
     }
-    if (migrationsTableExists(db))
+    else if (migrationLedgerExists(db)) {
+        assertMigrationLedger(db, migrations);
+    }
+    else {
+        withImmediateWriteLock(db, () => {
+            if (migrationLedgerExists(db))
+                return;
+            opts?.beforeLedgerInitializationLocked?.(db);
+            ensureMigrationsTable(db);
+        });
         assertMigrationLedger(db, migrations);
-    ensureMigrationsTable(db);
+    }
     const appliedRows = db.prepare("SELECT id FROM schema_migrations ORDER BY rowid").all();
     const applied = new Set(appliedRows.map((r) => r.id));
     for (const migration of migrations) {
@@ -103,12 +128,13 @@ export function runMigrations(db, migrations, opts) {
         withImmediateWriteLock(db, () => {
             // Re-check under the write lock. `applied` is a snapshot taken before the
             // loop, so two processes bootstrapping the same fresh DB concurrently
-            // (both see existed=false, both run with applyPending) could each decide
+            // (both see existed=false) could each decide
             // to apply migration N. The first commits; the second must not re-run the
             // DDL and must not hit a UNIQUE violation on the ledger insert.
             const already = db.prepare("SELECT 1 FROM schema_migrations WHERE id = ?").get(migration.id);
             if (already)
                 return;
+            opts?.beforeMigrationLocked?.(migration, db);
             db.exec(migration.up);
             db.prepare("INSERT INTO schema_migrations (id) VALUES (?)").run(migration.id);
         });
@@ -117,6 +143,17 @@ export function runMigrations(db, migrations, opts) {
 }
 /** Attempts to acquire the write lock before giving up to the caller. */
 const IMMEDIATE_LOCK_MAX_ATTEMPTS = 5;
+function isRetryableImmediateBeginError(error) {
+    const message = (error instanceof Error ? error.message : String(error)).toLowerCase();
+    return (message.includes("database is locked") ||
+        message.includes("database table is locked") ||
+        message.includes("did not open a transaction"));
+}
+function sleepImmediateRetry(ms) {
+    if (ms <= 0)
+        return;
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
 /**
  * Run `fn` inside a `BEGIN IMMEDIATE` transaction.
  *
@@ -139,24 +176,42 @@ function withImmediateWriteLock(db, fn) {
     for (let attempt = 1; attempt <= IMMEDIATE_LOCK_MAX_ATTEMPTS; attempt++) {
         try {
             db.exec("BEGIN IMMEDIATE");
+            if (!db.inTransaction) {
+                throw new Error("BEGIN IMMEDIATE did not open a transaction (phantom contention state)");
+            }
         }
         catch (err) {
-            // Busy despite busy_timeout (another writer holding it across the whole
-            // window). Retry a bounded number of times before surfacing.
             lastBeginErr = err;
-            continue;
+            if (isRetryableImmediateBeginError(err) && attempt < IMMEDIATE_LOCK_MAX_ATTEMPTS) {
+                if (db.inTransaction) {
+                    try {
+                        db.exec("ROLLBACK");
+                    }
+                    catch {
+                        // Transaction already gone; retrying is safe because fn has not run.
+                    }
+                }
+                sleepImmediateRetry(2 ** (attempt - 1));
+                continue;
+            }
+            throw err;
         }
         try {
             fn();
+            if (!db.inTransaction) {
+                throw new Error("Migration write lock invariant violated: transaction opened by BEGIN IMMEDIATE was no longer active after the migration body ran; refusing to COMMIT (writes may have escaped serialization)");
+            }
             db.exec("COMMIT");
             return;
         }
         catch (err) {
-            try {
-                db.exec("ROLLBACK");
-            }
-            catch {
-                // Already rolled back by SQLite (e.g. the statement aborted the txn).
+            if (db.inTransaction) {
+                try {
+                    db.exec("ROLLBACK");
+                }
+                catch {
+                    // Already rolled back by SQLite (e.g. the statement aborted the txn).
+                }
             }
             throw err;
         }