@arnilo/prism-coding-agent 0.0.7 → 0.0.10

package/dist/coding-checkpoint.js

@@ -0,0 +1,576 @@
+/**
+ * Bounded durable coding-task checkpoint metadata.
+ *
+ * This is not a second runtime. Hosts persist plan/todo Markdown in the workspace
+ * and store only references/hashes/summaries in workflow checkpoint state. Resume
+ * revalidates fingerprints and artifact integrity before import/execution.
+ */
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
+import { DEFAULT_MAX_CHECK_SUMMARY_BYTES, DEFAULT_MAX_CODING_ARTIFACT_BYTES, DEFAULT_MAX_CODING_ARTIFACTS, DEFAULT_MAX_CODING_CHECKPOINT_BYTES, DEFAULT_MAX_PLAN_BYTES, DEFAULT_MAX_TODO_TEXT_BYTES, DEFAULT_MAX_TODOS, HARD_MAX_CHECK_SUMMARY_BYTES, HARD_MAX_CODING_ARTIFACT_BYTES, HARD_MAX_CODING_ARTIFACTS, HARD_MAX_CODING_CHECKPOINT_BYTES, HARD_MAX_PLAN_BYTES, HARD_MAX_TODO_TEXT_BYTES, HARD_MAX_TODOS, validateCodingLimit, } from "./limits.js";
+import { sha256Hex } from "./artifacts.js";
+export const CODING_CHECKPOINT_SCHEMA_VERSION = 1;
+/** Workflow shared-state key that holds coding checkpoint metadata. */
+export const CODING_STATE_KEY = "coding";
+const SHA256_HEX = /^[a-f0-9]{64}$/;
+const TASK_ID = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,127}$/;
+const BRANCH = /^[^\s]{1,255}$/;
+const TODO_LINE = /^\s*[-*]\s+\[([ xX])\]\s+(.+?)\s*$/;
+const FORBIDDEN_METADATA_KEYS = new Set([
+    "credentials",
+    "credential",
+    "secret",
+    "secrets",
+    "token",
+    "tokens",
+    "password",
+    "cookie",
+    "cookies",
+    "storageState",
+    "storage_state",
+    "authorization",
+    "env",
+    "processEnv",
+    "commandOutput",
+    "rawOutput",
+    "stdout",
+    "stderr",
+]);
+export class CodingCheckpointError extends Error {
+    code = "ERR_PRISM_CODING_CHECKPOINT";
+    constructor(message) {
+        super(message);
+        this.name = "CodingCheckpointError";
+    }
+}
+export function resolveCodingCheckpointLimits(options) {
+    return {
+        maxPlanBytes: validateCodingLimit("maxPlanBytes", options?.maxPlanBytes ?? DEFAULT_MAX_PLAN_BYTES, HARD_MAX_PLAN_BYTES),
+        maxTodos: validateCodingLimit("maxTodos", options?.maxTodos ?? DEFAULT_MAX_TODOS, HARD_MAX_TODOS),
+        maxTodoTextBytes: validateCodingLimit("maxTodoTextBytes", options?.maxTodoTextBytes ?? DEFAULT_MAX_TODO_TEXT_BYTES, HARD_MAX_TODO_TEXT_BYTES),
+        maxArtifacts: validateCodingLimit("maxArtifacts", options?.maxArtifacts ?? DEFAULT_MAX_CODING_ARTIFACTS, HARD_MAX_CODING_ARTIFACTS),
+        maxArtifactBytes: validateCodingLimit("maxArtifactBytes", options?.maxArtifactBytes ?? DEFAULT_MAX_CODING_ARTIFACT_BYTES, HARD_MAX_CODING_ARTIFACT_BYTES),
+        maxCheckSummaryBytes: validateCodingLimit("maxCheckSummaryBytes", options?.maxCheckSummaryBytes ?? DEFAULT_MAX_CHECK_SUMMARY_BYTES, HARD_MAX_CHECK_SUMMARY_BYTES),
+        maxCheckpointBytes: validateCodingLimit("maxCheckpointBytes", options?.maxCheckpointBytes ?? DEFAULT_MAX_CODING_CHECKPOINT_BYTES, HARD_MAX_CODING_CHECKPOINT_BYTES),
+    };
+}
+/** Deterministic SHA-256 fingerprint over a JSON-stable encoding. */
+export function fingerprintJson(value) {
+    return sha256Hex(Buffer.from(stableStringify(value), "utf8"));
+}
+export function createCodingArtifactRef(input) {
+    const maxBytes = input.maxBytes ?? DEFAULT_MAX_CODING_ARTIFACT_BYTES;
+    if (input.bytes.length > maxBytes) {
+        throw new CodingCheckpointError(`Artifact exceeds ${maxBytes} byte limit`);
+    }
+    if (!isNonEmptyString(input.uri) || input.uri.length > 2_048) {
+        throw new CodingCheckpointError("Artifact URI must be a non-empty string at most 2048 characters");
+    }
+    return {
+        kind: input.kind,
+        uri: input.uri,
+        sha256: sha256Hex(input.bytes),
+        bytes: input.bytes.length,
+    };
+}
+export function verifyCodingArtifactBytes(ref, bytes, limits) {
+    const resolved = resolveCodingCheckpointLimits(limits);
+    if (ref.bytes > resolved.maxArtifactBytes || bytes.length > resolved.maxArtifactBytes) {
+        throw new CodingCheckpointError(`Artifact exceeds ${resolved.maxArtifactBytes} byte limit`);
+    }
+    if (bytes.length !== ref.bytes) {
+        throw new CodingCheckpointError(`Artifact byte count mismatch: expected ${ref.bytes}, got ${bytes.length}`);
+    }
+    const digest = sha256Hex(bytes);
+    if (digest !== ref.sha256) {
+        throw new CodingCheckpointError("Artifact SHA-256 mismatch");
+    }
+}
+export function createCodingPlanMarkdown(input) {
+    const limits = resolveCodingCheckpointLimits(input.limits);
+    if (input.todos.length > limits.maxTodos) {
+        throw new CodingCheckpointError(`Plan exceeds ${limits.maxTodos} todo limit`);
+    }
+    const lines = [
+        `# ${input.title.trim() || "Coding task"}`,
+        "",
+        `- Task ID: \`${input.taskId}\``,
+        `- Status: \`${input.status ?? "planned"}\``,
+        "",
+        "## Todos",
+        "",
+    ];
+    for (const todo of input.todos) {
+        const text = todo.text.trim();
+        assertTodoText(text, limits.maxTodoTextBytes);
+        const mark = todo.done ? "x" : " ";
+        const idPrefix = todo.id ? `[${todo.id}] ` : "";
+        lines.push(`- [${mark}] ${idPrefix}${text}`);
+    }
+    if (input.notes?.trim()) {
+        lines.push("", "## Notes", "", input.notes.trim(), "");
+    }
+    else {
+        lines.push("");
+    }
+    const markdown = lines.join("\n");
+    assertByteLimit("plan", markdown, limits.maxPlanBytes);
+    return markdown;
+}
+export function parseCodingPlanTodos(markdown, limits) {
+    const resolved = resolveCodingCheckpointLimits(limits);
+    assertByteLimit("plan", markdown, resolved.maxPlanBytes);
+    const todos = [];
+    for (const line of markdown.split(/\r?\n/)) {
+        const match = TODO_LINE.exec(line);
+        if (!match)
+            continue;
+        const done = match[1].toLowerCase() === "x";
+        const raw = match[2].trim();
+        assertTodoText(raw, resolved.maxTodoTextBytes);
+        const idMatch = /^\[([A-Za-z0-9._-]{1,64})\]\s+(.+)$/.exec(raw);
+        const id = idMatch?.[1] ?? `todo-${todos.length + 1}`;
+        const text = idMatch?.[2] ?? raw;
+        assertTodoText(text, resolved.maxTodoTextBytes);
+        todos.push({ id, text, done });
+        if (todos.length > resolved.maxTodos) {
+            throw new CodingCheckpointError(`Plan exceeds ${resolved.maxTodos} todo limit`);
+        }
+    }
+    return todos;
+}
+export async function writeCodingPlanFile(input) {
+    const limits = resolveCodingCheckpointLimits(input.limits);
+    assertByteLimit("plan", input.markdown, limits.maxPlanBytes);
+    const absolute = resolveUnderWorkspace(input.workspaceRoot, input.planPath);
+    await mkdir(dirname(absolute), { recursive: true });
+    const bytes = Buffer.from(input.markdown, "utf8");
+    await writeFile(absolute, bytes, { mode: 0o600 });
+    return createCodingArtifactRef({
+        kind: "plan",
+        uri: `file://${absolute}`,
+        bytes,
+        maxBytes: limits.maxPlanBytes,
+    });
+}
+export async function readCodingPlanFile(input) {
+    const limits = resolveCodingCheckpointLimits(input.limits);
+    const absolute = resolveUnderWorkspace(input.workspaceRoot, input.planPath);
+    const bytes = await readFile(absolute);
+    if (bytes.length > limits.maxPlanBytes) {
+        throw new CodingCheckpointError(`Plan exceeds ${limits.maxPlanBytes} byte limit`);
+    }
+    const artifact = createCodingArtifactRef({
+        kind: "plan",
+        uri: `file://${absolute}`,
+        bytes,
+        maxBytes: limits.maxPlanBytes,
+    });
+    if (input.expected) {
+        verifyCodingArtifactBytes(input.expected, bytes, limits);
+    }
+    const markdown = bytes.toString("utf8");
+    return {
+        markdown,
+        artifact,
+        todos: parseCodingPlanTodos(markdown, limits),
+    };
+}
+export function buildCodingCheckpointMetadata(input) {
+    const metadata = {
+        schemaVersion: CODING_CHECKPOINT_SCHEMA_VERSION,
+        taskId: input.taskId,
+        workspaceRoot: input.workspaceRoot,
+        baseBranch: input.baseBranch,
+        branch: input.branch,
+        worktreePath: input.worktreePath,
+        planPath: input.planPath,
+        plan: input.plan,
+        workspaceExport: input.workspaceExport,
+        artifacts: input.artifacts ?? [],
+        checks: input.checks ?? [],
+        handoff: input.handoff,
+        status: input.status ?? "planned",
+        fingerprints: input.fingerprints,
+        todos: input.todos ?? [],
+        updatedAt: input.updatedAt ?? new Date().toISOString(),
+    };
+    return validateCodingCheckpointMetadata(metadata, input.limits);
+}
+export function validateCodingCheckpointMetadata(value, limits) {
+    const resolved = resolveCodingCheckpointLimits(limits);
+    if (!isPlainObject(value)) {
+        throw new CodingCheckpointError("Coding checkpoint metadata must be an object");
+    }
+    assertNoForbiddenKeys(value);
+    if (value.schemaVersion !== CODING_CHECKPOINT_SCHEMA_VERSION) {
+        throw new CodingCheckpointError(`Unsupported coding checkpoint schemaVersion: ${String(value.schemaVersion)}`);
+    }
+    const taskId = requireString(value.taskId, "taskId");
+    if (!TASK_ID.test(taskId)) {
+        throw new CodingCheckpointError("taskId has invalid format");
+    }
+    const workspaceRoot = requireAbsolutePath(value.workspaceRoot, "workspaceRoot");
+    const baseBranch = requireBranch(value.baseBranch, "baseBranch");
+    const branch = requireBranch(value.branch, "branch");
+    const planPath = requireRelativePath(value.planPath, "planPath");
+    const plan = validateArtifactRef(value.plan, resolved, { requireKind: "plan" });
+    const worktreePath = value.worktreePath === undefined ? undefined : requireAbsolutePath(value.worktreePath, "worktreePath");
+    const workspaceExport = value.workspaceExport === undefined
+        ? undefined
+        : validateArtifactRef(value.workspaceExport, resolved);
+    const artifacts = requireArray(value.artifacts, "artifacts").map((item, index) => validateArtifactRef(item, resolved, { label: `artifacts[${index}]` }));
+    if (artifacts.length > resolved.maxArtifacts) {
+        throw new CodingCheckpointError(`Coding checkpoint exceeds ${resolved.maxArtifacts} artifact references`);
+    }
+    const checks = requireArray(value.checks, "checks").map((item, index) => validateCheckSummary(item, resolved, `checks[${index}]`));
+    if (checks.length > HARD_MAX_CODING_ARTIFACTS) {
+        throw new CodingCheckpointError("Too many check summaries");
+    }
+    const todos = requireArray(value.todos, "todos").map((item, index) => validateTodo(item, resolved, `todos[${index}]`));
+    if (todos.length > resolved.maxTodos) {
+        throw new CodingCheckpointError(`Coding checkpoint exceeds ${resolved.maxTodos} todos`);
+    }
+    const fingerprints = validateFingerprints(value.fingerprints);
+    const status = requireStatus(value.status);
+    const updatedAt = requireString(value.updatedAt, "updatedAt");
+    if (Number.isNaN(Date.parse(updatedAt))) {
+        throw new CodingCheckpointError("updatedAt must be an ISO-8601 timestamp");
+    }
+    const handoff = value.handoff === undefined ? undefined : validateHandoffSummary(value.handoff, resolved);
+    const metadata = {
+        schemaVersion: CODING_CHECKPOINT_SCHEMA_VERSION,
+        taskId,
+        workspaceRoot,
+        baseBranch,
+        branch,
+        worktreePath,
+        planPath,
+        plan,
+        workspaceExport,
+        artifacts,
+        checks,
+        handoff,
+        status,
+        fingerprints,
+        todos,
+        updatedAt,
+    };
+    const encoded = Buffer.byteLength(JSON.stringify(metadata), "utf8");
+    if (encoded > resolved.maxCheckpointBytes) {
+        throw new CodingCheckpointError(`Coding checkpoint metadata exceeds ${resolved.maxCheckpointBytes} byte limit`);
+    }
+    return metadata;
+}
+/**
+ * Fail closed before resume/import when ownership-equivalent fingerprints diverge
+ * or artifact references cannot be verified.
+ */
+export function assertCodingResumeAllowed(input) {
+    const metadata = validateCodingCheckpointMetadata(input.metadata, input.limits);
+    assertFingerprintsMatch(metadata.fingerprints, input.expected);
+    if (input.expectedWorkspaceRoot !== undefined &&
+        resolve(input.expectedWorkspaceRoot) !== resolve(metadata.workspaceRoot)) {
+        throw new CodingCheckpointError("Workspace root mismatch on coding resume");
+    }
+    if (input.expectedBaseBranch !== undefined && input.expectedBaseBranch !== metadata.baseBranch) {
+        throw new CodingCheckpointError("Base branch mismatch on coding resume");
+    }
+    if (input.planBytes) {
+        verifyCodingArtifactBytes(metadata.plan, input.planBytes, input.limits);
+    }
+    if (input.workspaceExportBytes) {
+        if (!metadata.workspaceExport) {
+            throw new CodingCheckpointError("Workspace export bytes provided without metadata reference");
+        }
+        verifyCodingArtifactBytes(metadata.workspaceExport, input.workspaceExportBytes, input.limits);
+    }
+    return metadata;
+}
+/** Extract and validate `state.coding` when present. */
+export function readCodingCheckpointFromState(state, limits) {
+    if (!(CODING_STATE_KEY in state))
+        return undefined;
+    return validateCodingCheckpointMetadata(state[CODING_STATE_KEY], limits);
+}
+export function codingCheckpointStatePatch(metadata) {
+    return { [CODING_STATE_KEY]: validateCodingCheckpointMetadata(metadata) };
+}
+function assertFingerprintsMatch(actual, expected) {
+    if (actual.workflowRevision !== expected.workflowRevision) {
+        throw new CodingCheckpointError("Workflow revision fingerprint mismatch on coding resume");
+    }
+    if (actual.toolFingerprint !== expected.toolFingerprint) {
+        throw new CodingCheckpointError("Tool fingerprint mismatch on coding resume");
+    }
+    if (actual.policyFingerprint !== expected.policyFingerprint) {
+        throw new CodingCheckpointError("Policy fingerprint mismatch on coding resume");
+    }
+    if (expected.definitionHash !== undefined) {
+        if (actual.definitionHash !== expected.definitionHash) {
+            throw new CodingCheckpointError("Definition hash mismatch on coding resume");
+        }
+    }
+    if (expected.imageDigest !== undefined) {
+        if (actual.imageDigest !== expected.imageDigest) {
+            throw new CodingCheckpointError("Image digest mismatch on coding resume");
+        }
+    }
+}
+function validateFingerprints(value) {
+    if (!isPlainObject(value)) {
+        throw new CodingCheckpointError("fingerprints must be an object");
+    }
+    assertNoForbiddenKeys(value);
+    const workflowRevision = requireString(value.workflowRevision, "fingerprints.workflowRevision");
+    const toolFingerprint = requireFingerprint(value.toolFingerprint, "fingerprints.toolFingerprint");
+    const policyFingerprint = requireFingerprint(value.policyFingerprint, "fingerprints.policyFingerprint");
+    const definitionHash = value.definitionHash === undefined
+        ? undefined
+        : requireFingerprint(value.definitionHash, "fingerprints.definitionHash");
+    const imageDigest = value.imageDigest === undefined
+        ? undefined
+        : requireString(value.imageDigest, "fingerprints.imageDigest");
+    if (imageDigest !== undefined && !/sha256:[a-f0-9]{64}/.test(imageDigest) && !SHA256_HEX.test(imageDigest)) {
+        // Allow either raw hex or docker digest form.
+        if (!imageDigest.includes("@sha256:") && !imageDigest.startsWith("sha256:")) {
+            throw new CodingCheckpointError("fingerprints.imageDigest must be a digest string");
+        }
+    }
+    return {
+        workflowRevision,
+        definitionHash,
+        imageDigest,
+        toolFingerprint,
+        policyFingerprint,
+    };
+}
+function validateArtifactRef(value, limits, options) {
+    const label = options?.label ?? "artifact";
+    if (!isPlainObject(value)) {
+        throw new CodingCheckpointError(`${label} must be an object`);
+    }
+    assertNoForbiddenKeys(value);
+    const kind = requireString(value.kind, `${label}.kind`);
+    if (!["plan", "workspace", "patch", "bundle", "diff", "other"].includes(kind)) {
+        throw new CodingCheckpointError(`${label}.kind is unsupported`);
+    }
+    if (options?.requireKind && kind !== options.requireKind) {
+        throw new CodingCheckpointError(`${label}.kind must be ${options.requireKind}`);
+    }
+    const uri = requireString(value.uri, `${label}.uri`);
+    if (uri.length > 2_048) {
+        throw new CodingCheckpointError(`${label}.uri exceeds 2048 characters`);
+    }
+    const sha256 = requireString(value.sha256, `${label}.sha256`).toLowerCase();
+    if (!SHA256_HEX.test(sha256)) {
+        throw new CodingCheckpointError(`${label}.sha256 must be a 64-char hex digest`);
+    }
+    const bytes = requireSafeInt(value.bytes, `${label}.bytes`);
+    if (bytes < 0 || bytes > limits.maxArtifactBytes) {
+        throw new CodingCheckpointError(`${label}.bytes out of range`);
+    }
+    return { kind, uri, sha256, bytes };
+}
+function validateCheckSummary(value, limits, label) {
+    if (!isPlainObject(value)) {
+        throw new CodingCheckpointError(`${label} must be an object`);
+    }
+    assertNoForbiddenKeys(value);
+    const name = requireString(value.name, `${label}.name`);
+    if (!/^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(name)) {
+        throw new CodingCheckpointError(`${label}.name has invalid format`);
+    }
+    const exitCode = requireSafeInt(value.exitCode, `${label}.exitCode`);
+    if (exitCode < 0 || exitCode > 255) {
+        throw new CodingCheckpointError(`${label}.exitCode out of range`);
+    }
+    const summary = requireString(value.summary, `${label}.summary`);
+    assertByteLimit(`${label}.summary`, summary, limits.maxCheckSummaryBytes);
+    if (/[\u0000-\u0008\u000B\u000C\u000E-\u001F]/.test(summary)) {
+        throw new CodingCheckpointError(`${label}.summary contains control characters`);
+    }
+    return { name, exitCode, summary };
+}
+function validateTodo(value, limits, label) {
+    if (!isPlainObject(value)) {
+        throw new CodingCheckpointError(`${label} must be an object`);
+    }
+    assertNoForbiddenKeys(value);
+    const id = requireString(value.id, `${label}.id`);
+    if (!/^[A-Za-z0-9._-]{1,64}$/.test(id)) {
+        throw new CodingCheckpointError(`${label}.id has invalid format`);
+    }
+    const text = requireString(value.text, `${label}.text`);
+    assertTodoText(text, limits.maxTodoTextBytes);
+    if (typeof value.done !== "boolean") {
+        throw new CodingCheckpointError(`${label}.done must be a boolean`);
+    }
+    return { id, text, done: value.done };
+}
+function validateHandoffSummary(value, limits) {
+    if (!isPlainObject(value)) {
+        throw new CodingCheckpointError("handoff must be an object");
+    }
+    assertNoForbiddenKeys(value);
+    const base = requireString(value.base, "handoff.base");
+    const head = requireString(value.head, "handoff.head");
+    const changedPathCount = requireSafeInt(value.changedPathCount, "handoff.changedPathCount");
+    const checkCount = requireSafeInt(value.checkCount, "handoff.checkCount");
+    if (changedPathCount < 0 || checkCount < 0) {
+        throw new CodingCheckpointError("handoff counts must be non-negative");
+    }
+    const artifact = value.artifact === undefined
+        ? undefined
+        : validateArtifactRef(value.artifact, limits, { label: "handoff.artifact" });
+    return { base, head, changedPathCount, checkCount, artifact };
+}
+function requireStatus(value) {
+    const status = requireString(value, "status");
+    const allowed = [
+        "planned",
+        "editing",
+        "checking",
+        "awaiting_approval",
+        "ready_for_handoff",
+        "completed",
+        "failed",
+        "cancelled",
+    ];
+    if (!allowed.includes(status)) {
+        throw new CodingCheckpointError(`Unsupported coding task status: ${status}`);
+    }
+    return status;
+}
+function resolveUnderWorkspace(workspaceRoot, relativePath) {
+    const root = requireAbsolutePath(workspaceRoot, "workspaceRoot");
+    const rel = requireRelativePath(relativePath, "planPath");
+    const candidate = resolve(root, rel);
+    const relToRoot = relative(root, candidate);
+    if (relToRoot.startsWith("..") || isAbsolute(relToRoot)) {
+        throw new CodingCheckpointError("Plan path escapes workspace root");
+    }
+    return candidate;
+}
+function requireAbsolutePath(value, label) {
+    const path = requireString(value, label);
+    if (!isAbsolute(path)) {
+        throw new CodingCheckpointError(`${label} must be an absolute path`);
+    }
+    const normalized = normalize(path);
+    if (normalized.includes(`..${sep}`) || normalized.endsWith(`${sep}..`)) {
+        throw new CodingCheckpointError(`${label} must not contain parent segments`);
+    }
+    return normalized;
+}
+function requireRelativePath(value, label) {
+    const path = requireString(value, label);
+    if (isAbsolute(path) || path.split(/[\\/]/).includes("..")) {
+        throw new CodingCheckpointError(`${label} must be a relative path without parent segments`);
+    }
+    if (!path || path === ".") {
+        throw new CodingCheckpointError(`${label} must be a non-empty relative path`);
+    }
+    return path.replace(/\\/g, "/");
+}
+function requireBranch(value, label) {
+    const branch = requireString(value, label);
+    if (!BRANCH.test(branch) || branch.includes("..")) {
+        throw new CodingCheckpointError(`${label} has invalid format`);
+    }
+    return branch;
+}
+function requireFingerprint(value, label) {
+    const digest = requireString(value, label).toLowerCase();
+    if (!SHA256_HEX.test(digest)) {
+        throw new CodingCheckpointError(`${label} must be a 64-char hex digest`);
+    }
+    return digest;
+}
+function assertTodoText(text, maxBytes) {
+    if (!text) {
+        throw new CodingCheckpointError("Todo text must be non-empty");
+    }
+    assertByteLimit("todo text", text, maxBytes);
+    if (/[\u0000-\u0008\u000B\u000C\u000E-\u001F]/.test(text)) {
+        throw new CodingCheckpointError("Todo text contains control characters");
+    }
+}
+function assertByteLimit(label, text, maxBytes) {
+    const bytes = Buffer.byteLength(text, "utf8");
+    if (bytes > maxBytes) {
+        throw new CodingCheckpointError(`${label} exceeds ${maxBytes} byte limit`);
+    }
+}
+function assertNoForbiddenKeys(value, path = "") {
+    for (const [key, child] of Object.entries(value)) {
+        const lower = key.toLowerCase();
+        if (FORBIDDEN_METADATA_KEYS.has(key) || FORBIDDEN_METADATA_KEYS.has(lower)) {
+            throw new CodingCheckpointError(`Forbidden coding checkpoint field: ${path}${key}`);
+        }
+        if (isPlainObject(child)) {
+            assertNoForbiddenKeys(child, `${path}${key}.`);
+        }
+    }
+}
+function requireString(value, label) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new CodingCheckpointError(`${label} must be a non-empty string`);
+    }
+    return value;
+}
+function requireSafeInt(value, label) {
+    if (!Number.isSafeInteger(value)) {
+        throw new CodingCheckpointError(`${label} must be a safe integer`);
+    }
+    return value;
+}
+function requireArray(value, label) {
+    if (!Array.isArray(value)) {
+        throw new CodingCheckpointError(`${label} must be an array`);
+    }
+    return value;
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function stableStringify(value) {
+    return JSON.stringify(sortValue(value));
+}
+function sortValue(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortValue);
+    }
+    if (isPlainObject(value)) {
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            out[key] = sortValue(value[key]);
+        }
+        return out;
+    }
+    if (typeof value === "number" && !Number.isFinite(value)) {
+        throw new CodingCheckpointError("Fingerprint input must not contain non-finite numbers");
+    }
+    if (typeof value === "bigint" || typeof value === "function" || typeof value === "symbol") {
+        throw new CodingCheckpointError("Fingerprint input contains unsupported values");
+    }
+    return value;
+}
+/** Exported for tests that need a quick digest helper without importing crypto. */
+export function codingSha256Hex(data) {
+    const bytes = typeof data === "string" ? Buffer.from(data, "utf8") : data;
+    return createHash("sha256").update(bytes).digest("hex");
+}
+// Keep path join available for hosts constructing plan paths.
+export function codingPlanPathForTask(taskId) {
+    if (!TASK_ID.test(taskId)) {
+        throw new CodingCheckpointError("taskId has invalid format");
+    }
+    const safe = taskId.replace(/[^A-Za-z0-9._-]+/g, "_");
+    return join("plans", `${safe}.md`).replace(/\\/g, "/");
+}
+//# sourceMappingURL=coding-checkpoint.js.map

package/dist/git-exec.d.ts

@@ -0,0 +1,62 @@
+export declare class GitError extends Error {
+    readonly code = "ERR_PRISM_GIT";
+    readonly exitCode: number | null;
+    constructor(message: string, exitCode?: number | null);
+}
+export interface GitExecRequest {
+    readonly args: readonly string[];
+    readonly cwd: string;
+    readonly env?: Readonly<Record<string, string>>;
+    readonly stdin?: Buffer | string;
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+    readonly maxOutputBytes?: number;
+}
+export interface GitExecResult {
+    readonly exitCode: number | null;
+    readonly stdout: Buffer;
+    readonly stderr: Buffer;
+    readonly timedOut: boolean;
+    readonly aborted: boolean;
+    readonly outputBytes: number;
+}
+export type GitRunner = (request: GitExecRequest & {
+    gitPath: string;
+}) => Promise<GitExecResult>;
+/** Noninteractive, pager-safe, credential-prompt-free baseline for Git child processes. */
+export declare const SAFE_GIT_ENV: Readonly<Record<string, string>>;
+/** Config flags prepended to every git invocation to disable hooks/external helpers. */
+export declare const SAFE_GIT_CONFIG_ARGS: readonly ["-c", "core.hooksPath=/dev/null", "-c", "core.pager=cat", "-c", "sequence.editor=true", "-c", "credential.helper=", "-c", "advice.detachedHead=false"];
+export declare function assertAbsoluteGit(path: string): Promise<string>;
+/** Local spawn-based Git runner. Never invokes a shell. */
+export declare function runGitCli(request: GitExecRequest & {
+    gitPath: string;
+}): Promise<GitExecResult>;
+export interface CreateGitRunnerOptions {
+    readonly gitPath?: string;
+    readonly runner?: GitRunner;
+    /** Optional sandbox-style execFile adapter. Collects streamed onData into stdout. */
+    readonly execFile?: (request: {
+        file: string;
+        args: readonly string[];
+        cwd?: string;
+        env?: Readonly<Record<string, string>>;
+        onData?: (data: Buffer) => void;
+        signal?: AbortSignal;
+        timeout?: number;
+    }) => Promise<{
+        exitCode: number | null;
+    }>;
+    readonly maxOutputBytes?: number;
+    readonly timeoutMs?: number;
+}
+export interface BoundGitRunner {
+    readonly gitPath: string;
+    exec(request: GitExecRequest): Promise<GitExecResult>;
+}
+/**
+ * Resolve a bound Git runner from an absolute git path, custom runner, or sandbox execFile.
+ */
+export declare function createBoundGitRunner(options?: CreateGitRunnerOptions): Promise<BoundGitRunner>;
+export declare function gitText(result: GitExecResult, stream?: "stdout" | "stderr"): string;
+export declare function gitRequireOk(runner: BoundGitRunner, request: GitExecRequest, label: string): Promise<GitExecResult>;