akm-cli 0.9.0-rc.0 → 0.9.0-rc.2

package/dist/core/extra-params.js

@@ -0,0 +1,61 @@
+// 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/.
+export const EXTRA_PARAMS_PROTECTED_TOP_LEVEL_KEYS = [
+    "model",
+    "messages",
+    "temperature",
+    "maxtokens",
+    "responseformat",
+    "stream",
+    "streamoptions",
+    "enablethinking",
+];
+export const EXTRA_PARAMS_CREDENTIAL_KEYS = [
+    "authorization",
+    "headers",
+    "apikey",
+    "token",
+    "password",
+    "secret",
+    "cookie",
+    "setcookie",
+];
+const PROTECTED_TOP_LEVEL_KEYS = new Set(EXTRA_PARAMS_PROTECTED_TOP_LEVEL_KEYS);
+const CREDENTIAL_KEYS = new Set(EXTRA_PARAMS_CREDENTIAL_KEYS);
+export function normalizeExtraParamKey(key) {
+    return key.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+/** Validate provider extras without allowing them to override AKM fields or carry credentials. */
+export function validateExtraParams(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return [{ path: [], message: "must be an object" }];
+    }
+    const issues = [];
+    const visit = (entry, path) => {
+        if (Array.isArray(entry)) {
+            entry.forEach((child, index) => {
+                visit(child, [...path, index]);
+            });
+            return;
+        }
+        if (!entry || typeof entry !== "object")
+            return;
+        for (const [key, child] of Object.entries(entry)) {
+            const normalized = normalizeExtraParamKey(key);
+            if (path.length === 0 && PROTECTED_TOP_LEVEL_KEYS.has(normalized)) {
+                issues.push({ path: [key], message: `${key} is protected by AKM` });
+            }
+            if (CREDENTIAL_KEYS.has(normalized)) {
+                issues.push({ path: [...path, key], message: `${key} cannot carry credentials` });
+            }
+            visit(child, [...path, key]);
+        }
+    };
+    visit(value, []);
+    return issues;
+}
+export function formatExtraParamsIssue(label, issue) {
+    const suffix = issue.path.map((part) => (typeof part === "number" ? `[${part}]` : `.${part}`)).join("");
+    return `${label}${suffix} ${issue.message}`;
+}

package/dist/core/file-lock.js

@@ -1,11 +1,114 @@
 // 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 { randomUUID } from "node:crypto";
 import fs from "node:fs";
+import path from "node:path";
+import { openDatabase } from "../storage/database.js";
 import { isProcessAlive } from "./common.js";
+function readLockSnapshot(lockPath) {
+    let fd;
+    try {
+        fd = fs.openSync(lockPath, "r");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return undefined;
+        throw err;
+    }
+    try {
+        const rawContent = fs.readFileSync(fd, "utf8");
+        const stat = fs.fstatSync(fd);
+        return {
+            rawContent,
+            identity: { dev: stat.dev, ino: stat.ino, size: stat.size, mtimeMs: stat.mtimeMs },
+        };
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function sameIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino && left.size === right.size && left.mtimeMs === right.mtimeMs;
+}
+function operationMutexPath(lockPath) {
+    // `.sensitive` is an established non-asset suffix across stash walkers. The
+    // mutex may sit beside a secret/env lock and must never surface as an asset.
+    return path.join(path.dirname(lockPath), `.${path.basename(lockPath)}.operations.sensitive`);
+}
+/**
+ * Serialize every mutation of one canonical lock path. SQLite's write lock is
+ * released by the OS when a process dies, so this mutex needs no stale-owner
+ * deletion protocol (which would reproduce the same check/rename race it is
+ * meant to prevent).
+ */
+function withLockOperationMutex(lockPath, run) {
+    const db = openDatabase(operationMutexPath(lockPath));
+    let began = false;
+    try {
+        db.exec("PRAGMA busy_timeout = 30000");
+        for (let attempt = 0; attempt < 5 && !began; attempt += 1) {
+            db.exec("BEGIN IMMEDIATE");
+            began = db.inTransaction;
+            if (!began)
+                Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 2 ** attempt);
+        }
+        if (!began)
+            throw new Error(`Could not acquire lock operation mutex for ${lockPath}.`);
+        const result = run();
+        db.exec("COMMIT");
+        began = false;
+        return result;
+    }
+    catch (error) {
+        if (began && db.inTransaction) {
+            try {
+                db.exec("ROLLBACK");
+            }
+            catch {
+                // Preserve the operation failure.
+            }
+        }
+        throw error;
+    }
+    finally {
+        db.close();
+    }
+}
+function tryAcquireLockRaw(lockPath, payload) {
+    try {
+        fs.writeFileSync(lockPath, payload, { flag: "wx" });
+    }
+    catch (err) {
+        if (err.code === "EEXIST")
+            return undefined;
+        throw err;
+    }
+    let snapshot;
+    try {
+        snapshot = readLockSnapshot(lockPath);
+    }
+    catch (error) {
+        releaseLockRaw(lockPath);
+        throw error;
+    }
+    if (!snapshot) {
+        releaseLockRaw(lockPath);
+        throw new Error(`Could not read newly acquired lock at ${lockPath}.`);
+    }
+    return { lockPath, ...snapshot };
+}
+function releaseLockRaw(lockPath) {
+    try {
+        fs.unlinkSync(lockPath);
+    }
+    catch {
+        // Sentinel already gone — fine.
+    }
+}
 /**
  * Atomically create a sentinel at `lockPath` with `payload` as the body.
- * Returns true if we now own the lock, false if a sentinel already
+ * Returns an exact ownership handle if we now own the lock, or undefined if a sentinel already
  * exists (EEXIST). Throws any other error (permissions, missing parent
  * dir, etc.) — callers must ensure the parent directory exists.
  *
@@ -14,15 +117,11 @@ import { isProcessAlive } from "./common.js";
  * (improve.ts records pid + startedAt so audit can correlate runs).
  */
 export function tryAcquireLockSync(lockPath, payload) {
-    try {
-        fs.writeFileSync(lockPath, payload, { flag: "wx" });
-        return true;
-    }
-    catch (err) {
-        if (err.code === "EEXIST")
-            return false;
-        throw err;
-    }
+    return withLockOperationMutex(lockPath, () => tryAcquireLockRaw(lockPath, payload));
+}
+/** Build a PID-bearing payload with a unique token for one acquisition attempt. */
+export function createLockPayload(metadata = {}) {
+    return JSON.stringify({ ...metadata, pid: process.pid, lockId: randomUUID() });
 }
 /**
  * Inspect an existing sentinel at `lockPath` without modifying it.
@@ -36,70 +135,116 @@ export function tryAcquireLockSync(lockPath, payload) {
  * Does NOT remove the file. Callers decide recovery policy.
  */
 export function probeLock(lockPath, opts) {
-    let rawContent;
-    let ageMs;
-    try {
-        rawContent = fs.readFileSync(lockPath, "utf8");
-    }
-    catch (err) {
-        if (err.code === "ENOENT")
-            return { state: "absent" };
-        return { state: "stale", reason: "unreadable" };
-    }
+    let snapshot;
     try {
-        const stat = fs.statSync(lockPath);
-        ageMs = Date.now() - stat.mtimeMs;
+        snapshot = readLockSnapshot(lockPath);
     }
     catch {
-        // Stat failed even though read succeeded — race-y removal in flight.
-        return { state: "stale", reason: "unreadable", rawContent };
+        return { state: "stale", reason: "unreadable" };
     }
+    if (!snapshot)
+        return { state: "absent" };
+    const { rawContent, identity } = snapshot;
+    const ageMs = Date.now() - identity.mtimeMs;
     const holderPid = extractHolderPid(rawContent);
     if (holderPid === undefined) {
-        return { state: "stale", reason: "invalid_pid", ageMs, rawContent };
+        return { state: "stale", reason: "invalid_pid", ageMs, rawContent, identity };
     }
     if (!isProcessAlive(holderPid)) {
-        return { state: "stale", reason: "pid_dead", holderPid, ageMs, rawContent };
+        return { state: "stale", reason: "pid_dead", holderPid, ageMs, rawContent, identity };
     }
     if (opts?.staleAfterMs !== undefined && ageMs > opts.staleAfterMs) {
-        return { state: "stale", reason: "age_exceeded", holderPid, ageMs, rawContent };
+        return { state: "stale", reason: "age_exceeded", holderPid, ageMs, rawContent, identity };
     }
-    return { state: "held", holderPid, ageMs, rawContent };
+    return { state: "held", holderPid, ageMs, rawContent, identity };
 }
 /**
- * Remove a lock file. Idempotent — silently ignores ENOENT. Used both to
- * reclaim stale locks (after probeLock returns `state: "stale"`) and to
- * release locks we own (after a successful tryAcquireLockSync).
+ * Revalidate and quarantine the probed sentinel while holding the same operation
+ * mutex used by acquisitions. A newer owner therefore cannot be renamed in the
+ * check/quarantine window, and a third contender cannot acquire until cleanup
+ * has completed.
  */
-export function releaseLock(lockPath) {
-    try {
-        fs.unlinkSync(lockPath);
-    }
-    catch {
-        // Sentinel already gone — fine.
-    }
+export function reclaimStaleLock(lockPath, probe, options) {
+    if (probe.rawContent === undefined || probe.identity === undefined)
+        return false;
+    const expectedContent = probe.rawContent;
+    const expectedIdentity = probe.identity;
+    return withLockOperationMutex(lockPath, () => {
+        let current;
+        try {
+            current = readLockSnapshot(lockPath);
+        }
+        catch {
+            return false;
+        }
+        if (!current || current.rawContent !== expectedContent || !sameIdentity(current.identity, expectedIdentity)) {
+            return false;
+        }
+        const quarantinePath = `${lockPath}.stale-${process.pid}-${randomUUID()}`;
+        try {
+            fs.renameSync(lockPath, quarantinePath);
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return false;
+            throw err;
+        }
+        let quarantined;
+        try {
+            quarantined = readLockSnapshot(quarantinePath);
+        }
+        catch {
+            quarantined = undefined;
+        }
+        if (!quarantined ||
+            quarantined.rawContent !== expectedContent ||
+            !sameIdentity(quarantined.identity, expectedIdentity)) {
+            try {
+                // Restore without replacing a non-cooperating lock installed after quarantine.
+                fs.linkSync(quarantinePath, lockPath);
+            }
+            catch (err) {
+                if (err.code !== "EEXIST")
+                    throw err;
+            }
+            releaseLockRaw(quarantinePath);
+            return false;
+        }
+        options?.afterQuarantineVerified?.();
+        try {
+            fs.unlinkSync(quarantinePath);
+            return true;
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return false;
+            throw err;
+        }
+    });
 }
 /**
- * Release a lock ONLY if it is still owned by `ownerPid`. Safe to call from a
- * `process.exit()` / `'exit'` handler as a backstop: `process.exit()` skips
- * `finally` blocks — so the normal lock-release never runs on signal death
- * (SIGTERM/SIGINT) — but it DOES fire `'exit'` listeners synchronously. Checking
- * ownership first means that if the lock was already released and re-acquired by
- * a different process, this leaves that process's lock intact (no cross-run
- * deletion / PID-reuse footgun). Synchronous so it is valid inside an exit handler.
+ * Release only the exact sentinel returned by `tryAcquireLockSync`. Content and
+ * file identity are revalidated while holding the acquisition operation mutex,
+ * so a stale holder cannot remove a successor. Synchronous and idempotent so it
+ * is safe in both `finally` blocks and process exit handlers.
  */
-export function releaseLockIfOwned(lockPath, ownerPid) {
-    let rawContent;
-    try {
-        rawContent = fs.readFileSync(lockPath, "utf8");
-    }
-    catch {
-        // Absent or unreadable — nothing of ours to release.
+export function releaseLock(ownership) {
+    const { lockPath } = ownership;
+    if (!fs.existsSync(lockPath) && !fs.existsSync(operationMutexPath(lockPath)))
         return;
-    }
-    if (extractHolderPid(rawContent) === ownerPid) {
-        releaseLock(lockPath);
-    }
+    withLockOperationMutex(lockPath, () => {
+        let current;
+        try {
+            current = readLockSnapshot(lockPath);
+        }
+        catch {
+            // Absent or unreadable — nothing of ours to release.
+            return;
+        }
+        if (current && current.rawContent === ownership.rawContent && sameIdentity(current.identity, ownership.identity)) {
+            releaseLockRaw(lockPath);
+        }
+    });
 }
 /**
  * Extract a PID from a sentinel body. Accepts the two shapes used across

package/dist/core/improve-result.js

@@ -0,0 +1,178 @@
+// 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/.
+const COMMON_FIELDS = [
+    "schemaVersion",
+    "ok",
+    "scope",
+    "dryRun",
+    "skipped",
+    "guidance",
+    "memorySummary",
+    "memoryCleanup",
+    "cyclesRun",
+    "plannedRefs",
+    "actions",
+    "distillSkipped",
+    "validationFailures",
+    "schemaRepairs",
+    "consolidation",
+    "extract",
+    "lintSummary",
+    "memoryIndexHealth",
+    "coverageGaps",
+    "evalCasesWritten",
+    "deadUrls",
+    "reflectsWithErrorContext",
+    "memoryInference",
+    "graphExtraction",
+    "memoryInferenceDurationMs",
+    "graphExtractionDurationMs",
+    "orphansPurged",
+    "proposalsExpired",
+    "reflectCooldownActions",
+    "reflectSkippedActions",
+    "reflectGuardRejectedActions",
+    "gateAutoAcceptedCount",
+    "gateAutoAcceptFailedCount",
+    "triage",
+    "proactiveMaintenance",
+    "recombination",
+    "proceduralCompilation",
+    "cycleMetrics",
+    "runId",
+    "sync",
+    "terminated",
+];
+const V1_FIELDS = new Set([...COMMON_FIELDS, "profile", "profileFilteredRefs"]);
+const V2_FIELDS = new Set([...COMMON_FIELDS, "strategy", "strategyFilteredRefs"]);
+function fail(message) {
+    throw new Error(`invalid improve-result envelope: ${message}`);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireExactFields(value, allowed) {
+    const unknown = Object.keys(value).filter((key) => !allowed.has(key));
+    if (unknown.length > 0)
+        fail(`unknown field${unknown.length === 1 ? "" : "s"}: ${unknown.sort().join(", ")}`);
+}
+function validateCommon(value) {
+    if (typeof value.ok !== "boolean")
+        fail("ok must be a boolean");
+    if (typeof value.dryRun !== "boolean")
+        fail("dryRun must be a boolean");
+    if (!Array.isArray(value.plannedRefs))
+        fail("plannedRefs must be an array");
+    if (!isRecord(value.scope))
+        fail("scope must be an object");
+    requireExactFields(value.scope, new Set(["mode", "value"]));
+    if (value.scope.mode !== "all" && value.scope.mode !== "type" && value.scope.mode !== "ref") {
+        fail('scope.mode must be "all", "type", or "ref"');
+    }
+    if (value.scope.value !== undefined && typeof value.scope.value !== "string") {
+        fail("scope.value must be a string when present");
+    }
+    if (!isRecord(value.memorySummary))
+        fail("memorySummary must be an object");
+    requireExactFields(value.memorySummary, new Set(["eligible", "derived"]));
+    if (typeof value.memorySummary.eligible !== "number" || typeof value.memorySummary.derived !== "number") {
+        fail("memorySummary.eligible and memorySummary.derived must be numbers");
+    }
+    for (const field of [
+        "actions",
+        "validationFailures",
+        "schemaRepairs",
+        "extract",
+        "coverageGaps",
+        "deadUrls",
+    ]) {
+        if (value[field] !== undefined && !Array.isArray(value[field]))
+            fail(`${field} must be an array`);
+    }
+    for (const field of [
+        "cyclesRun",
+        "evalCasesWritten",
+        "reflectsWithErrorContext",
+        "memoryInferenceDurationMs",
+        "graphExtractionDurationMs",
+        "orphansPurged",
+        "proposalsExpired",
+        "reflectCooldownActions",
+        "reflectSkippedActions",
+        "reflectGuardRejectedActions",
+        "gateAutoAcceptedCount",
+        "gateAutoAcceptFailedCount",
+    ]) {
+        if (value[field] !== undefined && typeof value[field] !== "number")
+            fail(`${field} must be a number`);
+    }
+    for (const field of ["guidance", "runId"]) {
+        if (value[field] !== undefined && typeof value[field] !== "string")
+            fail(`${field} must be a string`);
+    }
+    for (const field of [
+        "skipped",
+        "memoryCleanup",
+        "distillSkipped",
+        "consolidation",
+        "lintSummary",
+        "memoryIndexHealth",
+        "memoryInference",
+        "graphExtraction",
+        "triage",
+        "proactiveMaintenance",
+        "recombination",
+        "proceduralCompilation",
+        "cycleMetrics",
+        "sync",
+        "terminated",
+    ]) {
+        if (value[field] !== undefined && !isRecord(value[field]))
+            fail(`${field} must be an object`);
+    }
+}
+/** Decode the persisted public v1/v2 contract without guessing across versions. */
+export function decodeImproveResult(input) {
+    let parsed = input;
+    if (typeof input === "string") {
+        try {
+            parsed = JSON.parse(input);
+        }
+        catch {
+            fail("not valid JSON");
+        }
+    }
+    if (!isRecord(parsed))
+        fail("root must be an object");
+    if (parsed.schemaVersion === 1) {
+        requireExactFields(parsed, V1_FIELDS);
+        validateCommon(parsed);
+        if (parsed.profile !== undefined && typeof parsed.profile !== "string")
+            fail("profile must be a string");
+        if (parsed.profileFilteredRefs !== undefined && !Array.isArray(parsed.profileFilteredRefs)) {
+            fail("profileFilteredRefs must be an array");
+        }
+        return {
+            envelope: parsed,
+            strategy: null,
+            legacyProfile: typeof parsed.profile === "string" ? parsed.profile : null,
+        };
+    }
+    if (parsed.schemaVersion === 2) {
+        requireExactFields(parsed, V2_FIELDS);
+        validateCommon(parsed);
+        if (typeof parsed.strategy !== "string" || parsed.strategy.length === 0) {
+            fail("strategy must be a non-empty string");
+        }
+        if (parsed.strategyFilteredRefs !== undefined && !Array.isArray(parsed.strategyFilteredRefs)) {
+            fail("strategyFilteredRefs must be an array");
+        }
+        return {
+            envelope: parsed,
+            strategy: parsed.strategy,
+            legacyProfile: null,
+        };
+    }
+    fail(`unsupported schemaVersion: ${String(parsed.schemaVersion)}`);
+}

package/dist/core/json-schema.js

@@ -0,0 +1,142 @@
+// 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/.
+/**
+ * Structural JSON-Schema-subset validator (orchestration plan P1).
+ *
+ * The workflow engine's structured-output normalization needs to validate
+ * unit results against the author-declared unit `output` schema on any harness —
+ * including ones with no native schema support. Pulling in a full
+ * draft-2020-12 validator is deliberately avoided (dependency surface); this
+ * module implements the bounded subset that covers the schemas workflow
+ * authors actually write:
+ *
+ *   Supported: `type` (string | string[] — string, number, integer, boolean,
+ *   object, array, null), `properties`, `required`, `items`,
+ *   `additionalProperties: false`, `enum` (primitives), `minItems`,
+ *   `maxItems`, `minLength`, `maxLength`, `minimum`, `maximum`.
+ *
+ *   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.
+ *
+ * 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.
+ */
+export function validateJsonSchemaSubset(value, schema) {
+    const errors = [];
+    validateNode(value, schema, "$", errors);
+    return errors;
+}
+function typeOf(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    switch (typeof value) {
+        case "string":
+            return "string";
+        case "boolean":
+            return "boolean";
+        case "number":
+            return Number.isInteger(value) ? "integer" : "number";
+        default:
+            return "object";
+    }
+}
+function matchesType(actual, expected) {
+    if (expected === actual)
+        return true;
+    // JSON Schema: every integer is also a number.
+    return expected === "number" && actual === "integer";
+}
+function validateNode(value, schema, path, errors) {
+    const actual = typeOf(value);
+    const declared = schema.type;
+    if (typeof declared === "string" || Array.isArray(declared)) {
+        const expected = (Array.isArray(declared) ? declared : [declared]).filter((t) => typeof t === "string");
+        if (expected.length > 0 && !expected.some((t) => matchesType(actual, t))) {
+            errors.push(`${path}: expected type ${expected.join(" | ")}, got ${actual}`);
+            return; // type mismatch makes the remaining constraints meaningless
+        }
+    }
+    if (Array.isArray(schema.enum) && schema.enum.length > 0) {
+        const allowed = schema.enum;
+        if (!allowed.some((candidate) => candidate === value)) {
+            errors.push(`${path}: value ${JSON.stringify(value)} is not one of ${JSON.stringify(allowed)}`);
+            return;
+        }
+    }
+    if (actual === "string" && typeof value === "string") {
+        if (typeof schema.minLength === "number" && value.length < schema.minLength) {
+            errors.push(`${path}: string shorter than minLength ${schema.minLength}`);
+        }
+        if (typeof schema.maxLength === "number" && value.length > schema.maxLength) {
+            errors.push(`${path}: string longer than maxLength ${schema.maxLength}`);
+        }
+        return;
+    }
+    if ((actual === "number" || actual === "integer") && typeof value === "number") {
+        if (typeof schema.minimum === "number" && value < schema.minimum) {
+            errors.push(`${path}: ${value} is below minimum ${schema.minimum}`);
+        }
+        if (typeof schema.maximum === "number" && value > schema.maximum) {
+            errors.push(`${path}: ${value} is above maximum ${schema.maximum}`);
+        }
+        return;
+    }
+    if (actual === "array" && Array.isArray(value)) {
+        if (typeof schema.minItems === "number" && value.length < schema.minItems) {
+            errors.push(`${path}: array has fewer than minItems ${schema.minItems}`);
+        }
+        if (typeof schema.maxItems === "number" && value.length > schema.maxItems) {
+            errors.push(`${path}: array has more than maxItems ${schema.maxItems}`);
+        }
+        const items = schema.items;
+        if (items && typeof items === "object" && !Array.isArray(items)) {
+            value.forEach((element, index) => {
+                validateNode(element, items, `${path}[${index}]`, errors);
+            });
+        }
+        return;
+    }
+    if (actual === "object" && typeof value === "object" && value !== null) {
+        const record = value;
+        const properties = schema.properties && typeof schema.properties === "object" && !Array.isArray(schema.properties)
+            ? schema.properties
+            : undefined;
+        if (Array.isArray(schema.required)) {
+            for (const key of schema.required) {
+                // `Object.hasOwn`, not `key in record`: a required key satisfied only by
+                // an inherited prototype member (e.g. "toString", "constructor") is NOT
+                // present on the value itself, so `{}` must fail `required: ["toString"]`.
+                if (typeof key === "string" && !Object.hasOwn(record, key)) {
+                    errors.push(`${path}: missing required property "${key}"`);
+                }
+            }
+        }
+        if (properties) {
+            for (const [key, propSchema] of Object.entries(properties)) {
+                if (!Object.hasOwn(record, key))
+                    continue;
+                if (propSchema && typeof propSchema === "object" && !Array.isArray(propSchema)) {
+                    validateNode(record[key], propSchema, `${path}.${key}`, errors);
+                }
+            }
+        }
+        // `additionalProperties: false` closes the object to exactly its declared
+        // `properties`. This MUST run even when no `properties` object is present:
+        // `{ type: "object", additionalProperties: false }` admits only `{}`. Use
+        // `Object.hasOwn` so an inherited key name (e.g. "toString") on the empty
+        // property set is not mistaken for a declared property.
+        if (schema.additionalProperties === false) {
+            for (const key of Object.keys(record)) {
+                if (!properties || !Object.hasOwn(properties, key)) {
+                    errors.push(`${path}: unexpected property "${key}" (additionalProperties: false)`);
+                }
+            }
+        }
+    }
+}