codictator 0.0.0 → 0.1.3

package/dist/features/arch/index.js

@@ -0,0 +1,16 @@
+import { ARCH_PROFILES, isArchProfile, } from "./arch-profiles.js";
+import { checkArch as checkArchImpl, checkArchProfile, checkModuleSize, } from "./checks.js";
+import { CODICTATOR_MODULES, CODICTATOR_PROFILE, } from "./codictator-modules.js";
+import { buildGraph as buildGraphImpl, EMPTY_GRAPH_CACHE, hashGraphContent, normalizeSeparators, parseGraphCache, resolveImportTarget, serializeGraphCache, updateGraphCache, } from "./graph.js";
+import { layerMayImport, resolveLayer } from "./layer-rules.js";
+import { validateModuleMap } from "./module-map-validation.js";
+import { deriveModules, isPublicEntryTarget } from "./module-mapping.js";
+export { ARCH_PROFILES, CODICTATOR_MODULES, CODICTATOR_PROFILE, checkArchProfile, checkModuleSize, deriveModules, EMPTY_GRAPH_CACHE, hashGraphContent, isArchProfile, isPublicEntryTarget, layerMayImport, normalizeSeparators, parseGraphCache, resolveImportTarget, resolveLayer, serializeGraphCache, updateGraphCache, validateModuleMap, };
+// SPEC §4.11.3: import graph construction over the module map.
+export function buildGraph(modules, refs) {
+    return buildGraphImpl(modules, refs);
+}
+// SPEC §4.11.4: boundary and layer checks for the evaluation path.
+export function checkArch(ctx, refs, options = {}) {
+    return checkArchImpl(ctx, refs, options);
+}

package/dist/features/arch/layer-rules.d.ts

@@ -0,0 +1,3 @@
+import type { ArchProfile } from "./arch-profiles.ts";
+export declare function layerMayImport(layer: string, target: string, profile: ArchProfile): boolean;
+export declare function resolveLayer(file: string, moduleBase: string, layerDirs: ReadonlyArray<string>): string | undefined;

package/dist/features/arch/layer-rules.js

@@ -0,0 +1,38 @@
+const APP_LAYER_ORDER = {
+    domain: ["domain"],
+    application: ["domain", "application"],
+    infrastructure: ["domain", "application", "infrastructure"],
+    ui: ["domain", "application", "ui"],
+    api: ["domain", "application", "api"],
+};
+export function layerMayImport(layer, target, profile) {
+    if (target === "kernel") {
+        return true;
+    }
+    if (profile !== "app" && profile !== "service") {
+        return true;
+    }
+    const allowed = APP_LAYER_ORDER[layer];
+    if (allowed === undefined) {
+        return true;
+    }
+    return allowed.includes(target);
+}
+// SPEC §4.11.1: the first matching folder segment under the module dir names
+// the layer; a file outside every configured layer dir is unlayered.
+export function resolveLayer(file, moduleBase, layerDirs) {
+    const prefix = `${moduleBase}/`;
+    if (!file.startsWith(prefix)) {
+        return undefined;
+    }
+    const rest = file.slice(prefix.length);
+    const slash = rest.indexOf("/");
+    if (slash < 0) {
+        return undefined;
+    }
+    const top = rest.slice(0, slash);
+    if (!layerDirs.includes(top)) {
+        return undefined;
+    }
+    return top;
+}

package/dist/features/arch/module-map-validation.d.ts

@@ -0,0 +1,3 @@
+import { type Result } from "../../kernel/index.ts";
+import type { ModuleNode } from "./index.ts";
+export declare function validateModuleMap(modules: ReadonlyArray<ModuleNode>): Result<ReadonlyArray<ModuleNode>>;

package/dist/features/arch/module-map-validation.js

@@ -0,0 +1,30 @@
+// SPEC §4.11.2: adding a dependsOn edge is a design change, allowed only
+// when the graph stays acyclic. Config validation owns the same check; this
+// pure form lets the arch guard refuse a cyclic map with CDX-E105.
+import { err, makeError, ok, } from "../../kernel/index.js";
+import { findModuleCycle } from "./cycle-walk.js";
+function cycleError(trail) {
+    return makeError("CDX-E105", `architecture change closes a cycle: ${trail.join(" -> ")}`, "Remove a dependsOn edge so the module graph stays acyclic (SPEC §4.11.2).");
+}
+export function validateModuleMap(modules) {
+    const deps = new Map();
+    for (const mod of modules) {
+        if (deps.has(mod.name)) {
+            return err(makeError("CDX-E105", `duplicate module name "${mod.name}"`, "Give every architecture module a unique name, then retry."));
+        }
+        deps.set(mod.name, mod.dependsOn);
+    }
+    for (const mod of modules) {
+        for (const dep of mod.dependsOn) {
+            if (dep !== "*" && !deps.has(dep)) {
+                return err(makeError("CDX-E105", `module "${mod.name}" depends on unknown module "${dep}"`, "Point dependsOn at a module the architecture map declares, then retry."));
+            }
+        }
+    }
+    const names = modules.map((mod) => mod.name);
+    const cycle = findModuleCycle(names, deps, (dep) => dep === "*");
+    if (cycle !== undefined) {
+        return err(cycleError(cycle));
+    }
+    return ok(modules);
+}

package/dist/features/arch/module-mapping.d.ts

@@ -0,0 +1,15 @@
+import type { Finding } from "../engine/index.ts";
+import type { ModuleNode } from "./index.ts";
+export interface ArchDenyRule {
+    readonly from: string;
+    readonly to: string;
+}
+export declare function moduleEntry(mod: ModuleNode): string;
+export declare function isPublicEntryTarget(mod: ModuleNode, resolved: string): boolean;
+export declare function deriveModules(refs: ReadonlyArray<{
+    readonly from: string;
+    readonly to: string;
+}>): Array<ModuleNode>;
+export declare function dependsAllowed(fromMod: ModuleNode, toMod: ModuleNode, deny: ReadonlyArray<ArchDenyRule>): boolean;
+export declare function profileAllowsEdge(profile: string, fromMod: ModuleNode, toMod: ModuleNode): boolean;
+export declare function mappedFinding(from: string, line: number, detail: string): Finding;

package/dist/features/arch/module-mapping.js

@@ -0,0 +1,184 @@
+import { isArchProfile } from "./arch-profiles.js";
+import { moduleBase, normalizeSeparators, resolveRelativeSpecifier, } from "./graph.js";
+const TYPESCRIPT_EXTENSIONS = [
+    ".d.ts",
+    ".ts",
+    ".tsx",
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".cjs",
+    ".mts",
+    ".cts",
+];
+function stripExtension(path) {
+    for (const extension of TYPESCRIPT_EXTENSIONS) {
+        if (path.endsWith(extension)) {
+            return path.slice(0, -extension.length);
+        }
+    }
+    return path;
+}
+export function moduleEntry(mod) {
+    if (mod.entry !== undefined) {
+        return normalizeSeparators(mod.entry);
+    }
+    return `${moduleBase(mod)}/index.ts`;
+}
+// A cross-module import targets the public entry when it names the entry
+// file, the entry without its extension, or the module dir itself.
+export function isPublicEntryTarget(mod, resolved) {
+    const target = normalizeSeparators(resolved);
+    const entry = moduleEntry(mod);
+    const base = moduleBase(mod);
+    return (target === entry ||
+        stripExtension(target) === stripExtension(entry) ||
+        target === base ||
+        stripExtension(target) === `${base}/index`);
+}
+function hasGeneratedSegment(path) {
+    return normalizeSeparators(path).split("/").includes("generated");
+}
+function isRepoPath(value) {
+    return value.startsWith("src/");
+}
+function submoduleForTail(top, tail, kind) {
+    const next = tail.indexOf("/");
+    if (next < 0) {
+        return undefined;
+    }
+    const name = tail.slice(0, next);
+    if (kind === "pack") {
+        return {
+            name: `${top}/${name}`,
+            path: `src/${top}/${name}/**`,
+            kind: "pack",
+            dependsOn: [],
+        };
+    }
+    return {
+        name,
+        path: `src/${top}/${name}/**`,
+        kind: "feature",
+        dependsOn: [],
+    };
+}
+function moduleForTop(top, tail) {
+    if (top === "kernel") {
+        return {
+            name: "kernel",
+            path: "src/kernel/**",
+            kind: "kernel",
+            dependsOn: [],
+        };
+    }
+    if (top === "cli") {
+        return {
+            name: "cli",
+            path: "src/cli/**",
+            kind: "composition",
+            dependsOn: ["*"],
+        };
+    }
+    if (top === "features") {
+        return submoduleForTail(top, tail, "feature");
+    }
+    if (top === "builtin-packs") {
+        return submoduleForTail(top, tail, "pack");
+    }
+    return {
+        name: top,
+        path: `src/${top}/**`,
+        kind: "feature",
+        dependsOn: [],
+    };
+}
+function moduleForPath(path) {
+    const candidate = normalizeSeparators(path);
+    if (hasGeneratedSegment(candidate) || !isRepoPath(candidate)) {
+        return undefined;
+    }
+    const rest = candidate.slice("src/".length);
+    const slash = rest.indexOf("/");
+    if (slash < 0) {
+        return undefined;
+    }
+    return moduleForTop(rest.slice(0, slash), rest.slice(slash + 1));
+}
+// SPEC §4.11.3 Assign for the evaluation path: without a configured map the
+// modules derive from the files under src/, each with no declared edges, so
+// every cross-module edge fails closed until the config map declares it.
+export function deriveModules(refs) {
+    const found = new Map();
+    const consider = (file) => {
+        const mod = moduleForPath(file);
+        if (mod !== undefined && !found.has(mod.name)) {
+            found.set(mod.name, mod);
+        }
+    };
+    for (const ref of refs) {
+        consider(ref.from);
+        const target = normalizeSeparators(ref.to);
+        if (target.startsWith("./") || target.startsWith("../")) {
+            consider(resolveRelativeSpecifier(ref.from, target));
+        }
+        else if (isRepoPath(target)) {
+            consider(target);
+        }
+    }
+    return [...found.values()].sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+}
+export function dependsAllowed(fromMod, toMod, deny) {
+    for (const rule of deny) {
+        const fromHit = rule.from === "*" || rule.from === fromMod.name;
+        const toHit = rule.to === "*" || rule.to === toMod.name;
+        if (fromHit && toHit) {
+            return false;
+        }
+    }
+    if (fromMod.kind === "composition" || fromMod.dependsOn.includes("*")) {
+        return true;
+    }
+    if (toMod.kind === "composition") {
+        return false;
+    }
+    return fromMod.dependsOn.includes(toMod.name);
+}
+// SPEC §4.11.1 profile overlays beyond dependsOn: the kernel and layer
+// directions the table cannot express, and the composition root nothing may
+// import. Unknown kinds stay neutral so unconfigured maps fail on edges only.
+export function profileAllowsEdge(profile, fromMod, toMod) {
+    if (!isArchProfile(profile) ||
+        fromMod.kind === undefined ||
+        toMod.kind === undefined) {
+        return true;
+    }
+    if (fromMod.kind === "kernel" && toMod.name !== fromMod.name) {
+        return false;
+    }
+    if (profile === "app" || profile === "service") {
+        if (fromMod.kind === "shared" && toMod.kind === "feature") {
+            return false;
+        }
+    }
+    if (profile === "cli") {
+        if (fromMod.kind === "feature" && toMod.kind === "command") {
+            return false;
+        }
+    }
+    if (profile === "service") {
+        if (fromMod.kind === "feature" && toMod.kind === "transport") {
+            return false;
+        }
+    }
+    return true;
+}
+export function mappedFinding(from, line, detail) {
+    return {
+        ruleId: "core/arch-module-mapped",
+        path: from,
+        line,
+        message: detail,
+        remediation: "Move the file under a config.architecture modules[] path, or add its folder to the map.",
+    };
+}

package/dist/features/arch/profiles.d.ts

@@ -0,0 +1,4 @@
+export { ARCH_PROFILES, type ArchProfile, isArchProfile, } from "./arch-profiles.ts";
+export { CODICTATOR_MODULES, CODICTATOR_PROFILE, } from "./codictator-modules.ts";
+export { layerMayImport, resolveLayer } from "./layer-rules.ts";
+export { validateModuleMap } from "./module-map-validation.ts";

package/dist/features/arch/profiles.js

@@ -0,0 +1,8 @@
+// SPEC §4.11.1–§4.11.2: architecture profiles surface. Behaviour lives in
+// arch-profiles, layer-rules, codictator-modules and module-map-validation;
+// this file re-exports the surface so existing `./profiles.ts` imports keep
+// working.
+export { ARCH_PROFILES, isArchProfile, } from "./arch-profiles.js";
+export { CODICTATOR_MODULES, CODICTATOR_PROFILE, } from "./codictator-modules.js";
+export { layerMayImport, resolveLayer } from "./layer-rules.js";
+export { validateModuleMap } from "./module-map-validation.js";

package/dist/features/audit/append.d.ts

@@ -0,0 +1,26 @@
+import type { Decision, Finding, Ports, Trigger } from "../../kernel/index.ts";
+import { type Result } from "../../kernel/index.ts";
+import type { EventKind } from "./index.ts";
+export declare const LOG_REL = ".codictator/state/events.jsonl";
+export declare const MAX_LINE_BYTES: number;
+export declare const MAX_LOG_BYTES: number;
+export declare const KEEP_ROTATED = 5;
+export interface NewEvent {
+    readonly kind: EventKind;
+    readonly layer: string;
+    readonly trigger: Trigger;
+    readonly harness?: string;
+    readonly sessionId?: string;
+    readonly taskId?: string;
+    readonly ruleIds: ReadonlyArray<string>;
+    readonly decision?: Decision;
+    readonly findings?: ReadonlyArray<Finding>;
+    readonly waivers?: ReadonlyArray<string>;
+    readonly clockSkew?: boolean;
+    readonly durationMs: number;
+    readonly configHash: string;
+    readonly packs: Readonly<Record<string, string>>;
+    readonly message?: string;
+    readonly ts?: string;
+}
+export declare function appendEvent(ports: Ports, repoRoot: string, event: NewEvent, seq?: number): Promise<Result<void>>;

package/dist/features/audit/append.js

@@ -0,0 +1,210 @@
+// SPEC §4.18.1: event log append. One fs.append call per event, so
+// concurrent hook processes never interleave lines; lines stay under 64 KB
+// (the message is truncated with a marker first); past 5 MiB the log
+// rotates to events.<n>.jsonl keeping the newest five.
+import { err, makeError, ok, redactSecrets, sha256Text, stableLineStringify, stableStringify, } from "../../kernel/index.js";
+export const LOG_REL = ".codictator/state/events.jsonl";
+export const MAX_LINE_BYTES = 64 * 1024;
+export const MAX_LOG_BYTES = 5 * 1024 * 1024;
+export const KEEP_ROTATED = 5;
+function byteLength(text) {
+    return new TextEncoder().encode(text).length;
+}
+function e801(action, detail) {
+    return makeError("CDX-E801", `event log not writable: cannot ${action}`, "Free disk space and fix permissions on .codictator/state/, then retry.", detail);
+}
+// SPEC §7.10: sortable id from now plus a content digest. The per-process
+// counter arrives with the engine sequence; without it the digest keeps E1
+// ids unique without module-level mutable state.
+function makeEventId(now, canonical, seq) {
+    const stamp = now.replace(/[-:.]/g, "");
+    const digest = sha256Text(canonical).slice(0, 12);
+    if (seq === undefined) {
+        return `${stamp}-${digest}`;
+    }
+    return `${stamp}-${seq.toString().padStart(6, "0")}-${digest}`;
+}
+// SPEC §7.10: findings on the line carry rule, path, line and code only.
+function projectFinding(finding) {
+    return {
+        ruleId: finding.ruleId,
+        ...(finding.path === undefined ? {} : { path: finding.path }),
+        ...(finding.line === undefined ? {} : { line: finding.line }),
+        ...(finding.code === undefined ? {} : { code: finding.code }),
+    };
+}
+function truncateUtf8(text, maxBytes) {
+    const bytes = new TextEncoder().encode(text);
+    if (bytes.length <= maxBytes) {
+        return text;
+    }
+    let cut = maxBytes;
+    while (cut > 0) {
+        const byte = bytes[cut];
+        if (byte === undefined || (byte & 0xc0) !== 0x80) {
+            break;
+        }
+        cut -= 1;
+    }
+    return new TextDecoder().decode(bytes.subarray(0, cut));
+}
+function withOptionals(base, event, message) {
+    return {
+        ...base,
+        ...(event.harness === undefined ? {} : { harness: event.harness }),
+        ...(event.sessionId === undefined ? {} : { sessionId: event.sessionId }),
+        ...(event.taskId === undefined ? {} : { taskId: event.taskId }),
+        ...(event.decision === undefined ? {} : { decision: event.decision }),
+        ...(event.waivers === undefined ? {} : { waivers: event.waivers }),
+        ...(event.clockSkew === undefined ? {} : { clockSkew: event.clockSkew }),
+        ...(event.findings === undefined
+            ? {}
+            : { findings: event.findings.map(projectFinding) }),
+        ...(message === undefined ? {} : { message }),
+    };
+}
+// SPEC §4.18.6 EC-2: the message is truncated with a marker before append.
+function fitLine(event, now, id) {
+    const base = {
+        v: 1,
+        id,
+        ts: event.ts ?? now,
+        now,
+        kind: event.kind,
+        layer: event.layer,
+        trigger: event.trigger,
+        ruleIds: event.ruleIds,
+        durationMs: event.durationMs,
+        configHash: event.configHash,
+        packs: event.packs,
+    };
+    const message = event.message === undefined ? undefined : redactSecrets(event.message);
+    const full = stableLineStringify(withOptionals(base, event, message));
+    if (byteLength(full) <= MAX_LINE_BYTES) {
+        return ok(full);
+    }
+    if (message === undefined) {
+        return err(e801("append event", "a single event without a message exceeds 64 KB"));
+    }
+    const empty = stableLineStringify(withOptionals(base, event, ""));
+    const allowance = MAX_LINE_BYTES - byteLength(empty) - 2;
+    return truncateToFit(base, event, message, allowance);
+}
+// Halve the budget until the marked message fits, else fail closed.
+function truncateToFit(base, event, message, allowance) {
+    let budget = allowance;
+    for (let round = 0; round < 32; round += 1) {
+        if (budget < 0) {
+            return err(e801("append event", "the message cannot be truncated to fit 64 KB"));
+        }
+        const kept = truncateUtf8(message, budget);
+        const omitted = byteLength(message) - byteLength(kept);
+        const candidate = stableLineStringify(withOptionals(base, event, `${kept}[truncated ${omitted} bytes]`));
+        if (byteLength(candidate) <= MAX_LINE_BYTES) {
+            return ok(candidate);
+        }
+        budget = Math.floor(budget / 2);
+    }
+    return err(e801("append event", "the message cannot be truncated to fit 64 KB"));
+}
+function rotatedNumber(name) {
+    const match = /^events\.(\d+)\.jsonl$/.exec(name);
+    if (match === null) {
+        return undefined;
+    }
+    const raw = match[1];
+    if (raw === undefined) {
+        return undefined;
+    }
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isSafeInteger(parsed) ? parsed : undefined;
+}
+async function rotateLog(ports, root, logRel) {
+    const stateRel = `${root}/.codictator/state`;
+    const listed = await ports.fs.list(stateRel);
+    if (!listed.ok) {
+        return e801("rotate the event log", listed.error.message);
+    }
+    let next = 1;
+    const numbered = [];
+    for (const name of listed.value) {
+        const at = rotatedNumber(name);
+        if (at !== undefined) {
+            numbered.push(at);
+            next = Math.max(next, at + 1);
+        }
+    }
+    const current = await ports.fs.read(logRel);
+    if (!current.ok) {
+        return e801("rotate the event log", current.error.message);
+    }
+    const written = await ports.fs.write(`${stateRel}/events.${next}.jsonl`, current.value);
+    if (!written.ok) {
+        return e801("rotate the event log", written.error.message);
+    }
+    const removed = await ports.fs.remove(logRel);
+    if (!removed.ok) {
+        return e801("rotate the event log", removed.error.message);
+    }
+    numbered.push(next);
+    numbered.sort((a, b) => a - b);
+    while (numbered.length > KEEP_ROTATED) {
+        const oldest = numbered.shift();
+        if (oldest === undefined) {
+            break;
+        }
+        const deleted = await ports.fs.remove(`${stateRel}/events.${oldest}.jsonl`);
+        if (!deleted.ok) {
+            return e801("rotate the event log", deleted.error.message);
+        }
+    }
+    return undefined;
+}
+// SPEC §4.18.1: append one line-atomic event; writes recreate the log when it
+// was deleted mid-session; the log rotates past the size cap. The optional
+// sequence carries the engine's per-process counter into the event id so a
+// verdict's eventId matches its log line (SPEC §7.10).
+export async function appendEvent(ports, repoRoot, event, seq) {
+    const stripped = repoRoot.replace(/\/+$/, "");
+    const root = stripped === "" ? "." : stripped;
+    const logRel = `${root}/${LOG_REL}`;
+    const now = ports.clock.now();
+    const canonical = stableStringify({
+        kind: event.kind,
+        layer: event.layer,
+        trigger: event.trigger,
+        ruleIds: [...event.ruleIds].sort(),
+        durationMs: event.durationMs,
+        configHash: event.configHash,
+        packs: event.packs,
+        message: event.message,
+    });
+    const fitted = fitLine(event, now, makeEventId(now, canonical, seq));
+    if (!fitted.ok) {
+        return err(fitted.error);
+    }
+    const lineBytes = new TextEncoder().encode(fitted.value);
+    // exists() is the portable absence check: stat on a missing path
+    // rejects on some ports, so it runs only when the log is there.
+    const seen = await ports.fs.exists(logRel);
+    if (!seen.ok) {
+        return err(e801("append event", seen.error.message));
+    }
+    if (seen.value) {
+        const stat = await ports.fs.stat(logRel);
+        if (!stat.ok) {
+            return err(e801("append event", stat.error.message));
+        }
+        if (stat.value.size + lineBytes.length > MAX_LOG_BYTES) {
+            const rotated = await rotateLog(ports, root, logRel);
+            if (rotated !== undefined) {
+                return err(rotated);
+            }
+        }
+    }
+    const appended = await ports.fs.append(logRel, lineBytes);
+    if (!appended.ok) {
+        return err(e801("append event", appended.error.message));
+    }
+    return ok(undefined);
+}

package/dist/features/audit/explain-table-tail.d.ts

@@ -0,0 +1,2 @@
+import { type ErrorRow } from "./explain-table.ts";
+export declare const ERROR_ROWS_TAIL: ReadonlyArray<ErrorRow>;

package/dist/features/audit/explain-table-tail.js

@@ -0,0 +1,29 @@
+// SPEC §8.1: the error-code table, second half (CDX-E401 through CDX-E903:
+// registry, CI, workflow, filesystem, events, LLM and runtime). Combined
+// with explain-table.ts by explain.ts; the append-only rule lives there.
+import { row } from "./explain-table.js";
+// SPEC §8.1: rows CDX-E401 through CDX-E903.
+export const ERROR_ROWS_TAIL = [
+    row("CDX-E401", 5, "Registry or advisory data unavailable and no usable snapshot", "Retry with network access, or record a usable registry snapshot first."),
+    row("CDX-E501", 1, "Managed block markers malformed or duplicated", "Restore the file with codictator regen; never hand-edit generated artifacts."),
+    row("CDX-E503", 5, "CI base commit unreachable (shallow clone)", "Fetch with fetch-depth 0 so the base is reachable, then rerun."),
+    row("CDX-E601", 1, "Red proof attempted after implementation began", "Write the failing red proof before implementing, then retry."),
+    row("CDX-E602", 1, "Declared test did not execute and fail", "Declare a test that executes and fails red, then retry."),
+    row("CDX-E604", 1, "Phase gate evidence missing", "Attach the phase gate evidence the step requires, then retry."),
+    row("CDX-E605", 1, "Reviewer session not fresh", "Have a fresh session that wrote no file of the task run the review, then retry."),
+    row("CDX-E606", 3, "More than one open task on a branch", "Close the extra open tasks so one branch holds one task, then retry."),
+    row("CDX-E607", 3, "Review findings file invalid", "Fix the review findings file to match its schema, then retry."),
+    row("CDX-E608", 1, "Remediation needs a clean work tree", "Commit or stash the work tree, then retry the remediation step."),
+    row("CDX-E609", 4, "Rollback refused outside Codictator's step branches", "Run the rollback on a Codictator step branch, with a human driving."),
+    row("CDX-E701", 1, "Write outside the repo root or temp dir", "Keep the path inside the repo root or the OS temp dir, then retry."),
+    row("CDX-E702", 5, "Network host not on the allowlist", "Use an allowlisted registry or advisory host, then retry."),
+    row("CDX-E703", 6, "git missing or not a git repository", "Run inside a git repository so paths resolve against its root."),
+    row("CDX-E801", 7, "Event log not writable (verdict blocked)", "Free disk space and fix permissions on .codictator/state/, then retry."),
+    row("CDX-E851", 3, "No LLM configured for --llm", "Configure config.llm or drop the --llm flag, then retry."),
+    row("CDX-E852", 5, "LLM key missing or rejected", "Set a valid LLM API key in the environment, then retry."),
+    row("CDX-E853", 1, "LLM draft invalid after repair", "Simplify the generation request and retry."),
+    row("CDX-E854", 5, "LLM unavailable (timeout, 429, 5xx after retries)", "Wait and retry; the provider is unreachable right now."),
+    row("CDX-E901", 7, "Enforcer or runtime threw", "Fix the throwing enforcer or runtime path; the failure stays fail-closed until then."),
+    row("CDX-E902", 1, "Budget or time limit exceeded", "Shrink the scope or raise the budget, then retry."),
+    row("CDX-E903", 5, "Required data or tool for an enforcer unavailable", "Provide the required data or tool, then retry."),
+];

package/dist/features/audit/explain-table.d.ts

@@ -0,0 +1,8 @@
+export interface ErrorRow {
+    readonly code: string;
+    readonly exit: number;
+    readonly meaning: string;
+    readonly remediation: string;
+}
+export declare function row(code: string, exit: number, meaning: string, remediation: string): ErrorRow;
+export declare const ERROR_ROWS_HEAD: ReadonlyArray<ErrorRow>;

package/dist/features/audit/explain-table.js

@@ -0,0 +1,48 @@
+// SPEC §8.1: the error-code table behind `codictator explain CDX-Ennn`,
+// first half (CDX-E001 through CDX-E306: bootstrap, config, packs and
+// adapters). ErrorRow and the row helper live here so
+// explain-table-tail.ts reuses them; explain.ts combines both halves in
+// SPEC §8.1 order. Codes are append-only (SPEC §1.4): a new code is added
+// in order, never by editing an existing row.
+export function row(code, exit, meaning, remediation) {
+    return { code, exit, meaning, remediation };
+}
+// SPEC §8.1: rows CDX-E001 through CDX-E306.
+export const ERROR_ROWS_HEAD = [
+    row("CDX-E001", 6, "Node.js is not on PATH", "Install Node.js LTS and retry with node on PATH."),
+    row("CDX-E002", 6, "Node.js is older than the engine's engines.node", "Upgrade Node.js to the required version, then retry."),
+    row("CDX-E003", 6, "Engine not installed at the root or tool dir", "Run npm ci at the root or npm ci --prefix .codictator/tool, then retry."),
+    row("CDX-E010", 2, "Unknown rule, event or error id for explain", "Check the spelling; the nearest known ids are listed above."),
+    row("CDX-E011", 6, "Replay needs a pack version that is not installed", "Install the pack version the event records, then rerun codictator replay <eventId>."),
+    row("CDX-E101", 3, "Config missing, unparseable or schema-invalid", "Fix .codictator/config.json to match schema/config.schema.json, then retry."),
+    row("CDX-E102", 3, "config.codictator does not match the installed engine", "Set codictator to the installed engine version, or upgrade the engine."),
+    row("CDX-E103", 3, "Override or waiver of a floor rule", "Remove the override or waiver; floor rules cannot be loosened."),
+    row("CDX-E104", 3, "Tunable looser than its default outside a waiver", "Tighten the tunable, or move the loosening into .codictator/waivers.json."),
+    row("CDX-E105", 3, "Mandatory workflow gate removed or reordered, or an architecture change that loosens a profile rule or creates a cycle", "Restore the mandatory order and the profile rule, then retry."),
+    row("CDX-E106", 3, "Literal secret in config, or key over plaintext HTTP", "Remove the literal secret and use HTTPS, then retry."),
+    row("CDX-E107", 4, "Human-only command without a TTY or with agent markers", "Run this command yourself in an interactive terminal, not through an agent or hook."),
+    row("CDX-E108", 3, "Not a Codictator repo", "Run codictator init inside a repository, or change into a Codictator repo."),
+    row("CDX-E109", 3, "Waiver value beyond the pack bound", "Bring the waiver value inside the pack bound, then retry."),
+    row("CDX-E110", 3, "Waiver expiry beyond maxWaiverDays or renewal chain too long", "Shorten the expiry within maxWaiverDays and keep the chain short, then retry."),
+    row("CDX-E201", 7, "Schema uses an unsupported keyword", "Rewrite the schema with the supported 2020-12 subset, then retry."),
+    row("CDX-E202", 3, "Duplicate rule id", "Rename one of the rules so every rule id is unique, then retry."),
+    row("CDX-E203", 3, "Configured pack missing or failing self-test", "Install the pack at its pinned version and make codictator pack test pass, then retry."),
+    row("CDX-E204", 3, "Custom pack id or rule id collides with or impersonates a built-in", "Rename the custom pack and rules with a custom prefix, then retry."),
+    row("CDX-E205", 3, "Rule names an unknown enforcer", "Name a known enforcer for the rule's family, then retry."),
+    row("CDX-E206", 3, "Tool without an exact version pin", "Pin the tool to an exact version in config, then retry."),
+    row("CDX-E207", 1, "External tool error, unknown exit code, unparseable or oversized output, or path outside the repo", "Fix the tool invocation per the reported detail; the finding blocks until the run is clean."),
+    row("CDX-E208", 1, "External tool version does not match its pin", "Install the pinned tool version, then retry."),
+    row("CDX-E209", 1, "External tool not found", "Install the tool the pack needs, then retry."),
+    row("CDX-E210", 3, "External tool mapped to a rule outside its pack", "Map the tool to a rule inside its own pack, then retry."),
+    row("CDX-E211", 3, "Pack self-test failure (SPEC §4.4.4): rule fixtures", "Run codictator pack test <id> and fix the failing case, then retry."),
+    row("CDX-E212", 3, "Pack self-test failure (SPEC §4.4.4): enforcer binding", "Run codictator pack test <id> and fix the failing case, then retry."),
+    row("CDX-E213", 3, "Pack self-test failure (SPEC §4.4.4): parameter bounds", "Run codictator pack test <id> and fix the failing case, then retry."),
+    row("CDX-E214", 3, "Pack self-test failure (SPEC §4.4.4): default direction", "Run codictator pack test <id> and fix the failing case, then retry."),
+    row("CDX-E215", 3, "Pack self-test failure (SPEC §4.4.4): external tool declaration", "Run codictator pack test <id> and fix the failing case, then retry."),
+    row("CDX-E216", 3, "Pack self-test failure (SPEC §4.4.4): capability coverage", "Run codictator pack test <id> and fix the failing case, then retry."),
+    row("CDX-E301", 3, "Unknown or uninstalled harness id", "Use an installed adapter id, or add the custom adapter under .codictator/adapters/."),
+    row("CDX-E302", 3, "Custom adapter without passing contract tests", "Make the adapter pass its contract tests, then retry."),
+    row("CDX-E303", 1, "Hook payload unparseable or missing required fields", "Resend a well-formed hook payload; the finding blocks until it parses."),
+    row("CDX-E305", 1, "Hook payload over 8 MiB", "Write the file in smaller edits, then retry the tool call."),
+    row("CDX-E306", 1, "Shell command unparseable", "Simplify the shell command so it parses, then retry."),
+];

package/dist/features/audit/explain.d.ts

@@ -0,0 +1,7 @@
+import { type ErrorRow } from "./explain-table.ts";
+export declare const ERROR_ROWS: ReadonlyArray<ErrorRow>;
+export declare function errorRowFor(code: string): ErrorRow | undefined;
+export declare function isKnownExplainId(id: string): boolean;
+export declare function explainCodeText(rowValue: ErrorRow): string;
+export declare function nearestExplainIds(id: string, limit?: number): Array<string>;
+export declare function explainUnknownText(id: string): string;