@litfamily/litcodex 1.0.0

package/node_modules/@litcodex/lit-loop/dist/state-store.js

@@ -0,0 +1,471 @@
+// src/state-store.ts — M08/T13 durable state store (the ONLY fs authority for loop state).
+//
+// Resolves the state dir from the project root (never the module location), writes goals.json
+// ATOMICALLY via tmp-write→fsync→rename (a crash mid-write can never leave a half-truncated
+// plan), APPENDS ledger lines without rewriting, VALIDATES the plan schema on read, and on a
+// corruption QUARANTINES the bad bytes to a timestamped .bak + writes a recovery report +
+// appends a state_recovered ledger line + throws a typed recoverable error (NEVER auto-recreate,
+// NEVER discard goals). Serializes same-process mutations per state dir. It MUST NEVER read,
+// write, create, or reference the legacy runtime dir — runtime state lives ONLY under `.litcodex/lit-loop`.
+import { createHash } from "node:crypto";
+import { appendFile, mkdir, open, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { redactSecretsInValue } from "./redaction.js";
+import { LIT_LOOP_GOALS, litLoopBriefPath, litLoopDir, litLoopEvidenceDir, litLoopGoalsPath, litLoopLedgerPath, litLoopRelativeDir, normalizeSessionId, repoRelative, } from "./state-paths.js";
+import { isGoalId, iso, isUserModel, LitLoopStateError, } from "./state-types.js";
+// Re-export the path-layer scope helpers M09/M11 import via the store barrel.
+export { evidencePath, resolveLoopScope } from "./state-paths.js";
+/** Alias of `litLoopDir` under the name M09 (loop model) and M11 (doctor) import. */
+export function resolveLoopStateDir(repoRoot, scope) {
+    return litLoopDir(repoRoot, scope);
+}
+// ── errno helpers ────────────────────────────────────────────────────────────
+function errnoCode(err) {
+    return typeof err === "object" && err !== null && "code" in err
+        ? err.code
+        : undefined;
+}
+function writeFailed(message, cause, details) {
+    return new LitLoopStateError(message, "LIT_LOOP_WRITE_FAILED", {
+        cause,
+        details: { ...details, cause: errnoCode(cause) },
+    });
+}
+// ── atomic write primitive (tmp in same dir → fsync → rename) ────────────────
+async function atomicWrite(targetPath, contents) {
+    const dir = join(targetPath, "..");
+    const rand = Math.random().toString(36).slice(2, 10);
+    const tmp = `${targetPath}.${process.pid}.${Date.now()}.${rand}.tmp`;
+    let handle;
+    try {
+        handle = await open(tmp, "w");
+        await handle.writeFile(contents, "utf8");
+        await handle.sync(); // fsync: durability of tmp bytes before publish
+        await handle.close();
+        handle = undefined;
+        await rename(tmp, targetPath); // POSIX rename over existing target is atomic
+    }
+    catch (err) {
+        if (handle !== undefined) {
+            await handle.close().catch(() => undefined);
+        }
+        await unlink(tmp).catch(() => undefined); // best-effort cleanup; prior target untouched
+        throw writeFailed(`failed to write ${repoRelative(targetPath, dir)}`, err, { path: targetPath });
+    }
+}
+// ── plan validation (the single schema gate, A3 C7 + addendum §B.3) ──────────
+function isIsoString(v) {
+    return typeof v === "string" && v.length > 0 && !Number.isNaN(Date.parse(v));
+}
+function field(obj, key) {
+    return obj[key];
+}
+function validateGoal(goal) {
+    if (typeof goal !== "object" || goal === null) {
+        return false;
+    }
+    if (!isGoalId(field(goal, "id"))) {
+        return false;
+    }
+    if (typeof field(goal, "title") !== "string" || typeof field(goal, "objective") !== "string") {
+        return false;
+    }
+    const statuses = ["pending", "in_progress", "complete", "failed", "blocked"];
+    const status = field(goal, "status");
+    if (typeof status !== "string" || !statuses.includes(status)) {
+        return false;
+    }
+    const attempt = field(goal, "attempt");
+    if (typeof attempt !== "number" || !Number.isInteger(attempt) || attempt < 0) {
+        return false;
+    }
+    if (!isIsoString(field(goal, "createdAt")) || !isIsoString(field(goal, "updatedAt"))) {
+        return false;
+    }
+    const successCriteria = field(goal, "successCriteria");
+    if (!Array.isArray(successCriteria)) {
+        return false;
+    }
+    const critStatuses = ["pending", "pass", "fail", "blocked"];
+    for (const crit of successCriteria) {
+        if (typeof crit !== "object" || crit === null) {
+            return false;
+        }
+        const id = field(crit, "id");
+        if (typeof id !== "string" || !/^C\d{3}$/.test(id)) {
+            return false;
+        }
+        if (typeof field(crit, "scenario") !== "string" || typeof field(crit, "expectedEvidence") !== "string") {
+            return false;
+        }
+        if (!isUserModel(field(crit, "userModel"))) {
+            return false; // REJECTS "adversarial" and any non-3-value model
+        }
+        const cs = field(crit, "status");
+        if (typeof cs !== "string" || !critStatuses.includes(cs)) {
+            return false;
+        }
+        const cap = field(crit, "capturedEvidence");
+        if (!(cap === null || typeof cap === "string")) {
+            return false;
+        }
+    }
+    return true;
+}
+/** Structural plan validation. Returns the reason string on failure, or null when valid. */
+function planInvalidReason(plan) {
+    if (typeof plan !== "object" || plan === null) {
+        return "plan is not an object";
+    }
+    if (field(plan, "version") !== 1) {
+        return `version must be 1 (got ${JSON.stringify(field(plan, "version"))})`;
+    }
+    if (!isIsoString(field(plan, "createdAt")) || !isIsoString(field(plan, "updatedAt"))) {
+        return "createdAt/updatedAt must be ISO-8601 strings";
+    }
+    for (const f of ["briefPath", "goalsPath", "ledgerPath", "evidenceDir"]) {
+        if (typeof field(plan, f) !== "string") {
+            return `${f} must be a string`;
+        }
+    }
+    const sessionId = field(plan, "sessionId");
+    if (!(sessionId === null || typeof sessionId === "string")) {
+        return "sessionId must be a string or null";
+    }
+    const codexGoalMode = field(plan, "codexGoalMode");
+    if (codexGoalMode !== undefined && codexGoalMode !== "aggregate" && codexGoalMode !== "per_story") {
+        return "codexGoalMode must be aggregate or per_story when present";
+    }
+    const codexObjective = field(plan, "codexObjective");
+    if (codexObjective !== undefined && typeof codexObjective !== "string") {
+        return "codexObjective must be a string when present";
+    }
+    const goals = field(plan, "goals");
+    if (!Array.isArray(goals)) {
+        return "goals must be an array";
+    }
+    for (const goal of goals) {
+        if (!validateGoal(goal)) {
+            return "a goal failed schema validation";
+        }
+    }
+    const activeGoalId = field(plan, "activeGoalId");
+    if (activeGoalId !== undefined) {
+        if (typeof activeGoalId !== "string") {
+            return "activeGoalId must be a string when present";
+        }
+        const ids = new Set(goals.map((g) => g.id));
+        if (!ids.has(activeGoalId)) {
+            return `activeGoalId ${JSON.stringify(activeGoalId)} does not match any goal`;
+        }
+    }
+    return null;
+}
+function validatePlan(plan) {
+    const reason = planInvalidReason(plan);
+    if (reason !== null) {
+        throw new LitLoopStateError(`invalid lit-loop plan: ${reason}`, "LIT_LOOP_PLAN_INVALID", {
+            details: { reason },
+        });
+    }
+}
+// ── existence probe (A3 C6: false ONLY on ENOENT, throws WRITE_FAILED otherwise) ──
+function assertAbsolute(absPath) {
+    if (typeof absPath !== "string" || !isAbsolute(absPath)) {
+        throw new LitLoopStateError(`path must be absolute (got ${JSON.stringify(absPath)})`, "LIT_LOOP_REPO_ROOT_INVALID", { details: { absPath } });
+    }
+}
+export async function statExists(absPath) {
+    assertAbsolute(absPath);
+    try {
+        await stat(absPath);
+        return true;
+    }
+    catch (err) {
+        if (errnoCode(err) === "ENOENT") {
+            return false;
+        }
+        // A permission / IO / loop error MUST NOT masquerade as "absent".
+        throw writeFailed(`stat failed for ${absPath}`, err, { path: absPath });
+    }
+}
+// ── brief-file read (M09-addendum §A1.1: inert data, no normalization) ───────
+export class BriefFileMissingError extends Error {
+    constructor(path, cause) {
+        super(`brief file not found or not a regular file: ${path}`, cause === undefined ? undefined : { cause });
+        this.name = "BriefFileMissingError";
+        this.path = path;
+    }
+}
+export class BriefFileUnreadableError extends Error {
+    constructor(path, cause) {
+        super(`brief file is unreadable: ${path}`, cause === undefined ? undefined : { cause });
+        this.name = "BriefFileUnreadableError";
+        this.path = path;
+    }
+}
+/**
+ * Read `briefFilePath` as INERT UTF-8 text. The path is used AS GIVEN — no normalization, no
+ * re-rooting against `repoRoot`, no rejection (the bytes are data, never re-interpreted as a
+ * path/flag). ENOENT/EISDIR → BriefFileMissingError; EACCES/EIO → BriefFileUnreadableError.
+ */
+export async function readBriefFile(_repoRoot, briefFilePath) {
+    try {
+        return await readFile(briefFilePath, "utf8");
+    }
+    catch (err) {
+        const code = errnoCode(err);
+        if (code === "ENOENT" || code === "EISDIR") {
+            throw new BriefFileMissingError(briefFilePath, err);
+        }
+        throw new BriefFileUnreadableError(briefFilePath, err);
+    }
+}
+// ── mutation lock (canonical + alias, SAME reference; A3 C6) ─────────────────
+const mutationLocks = new Map();
+export function withMutationLock(repoRoot, scope, body) {
+    const key = `${repoRoot}\0${litLoopRelativeDir(scope)}`;
+    const prior = mutationLocks.get(key) ?? Promise.resolve();
+    const run = prior.then(body, body); // run after prior settles either way
+    // Store a poison-proof tail so a rejected body never blocks subsequent locks.
+    mutationLocks.set(key, run.catch(() => undefined));
+    return run;
+}
+/** @deprecated Alias of `withMutationLock` (SAME function reference, same lock map). */
+export const withStateMutationLock = withMutationLock;
+// ── writePlan (crash-atomic) ─────────────────────────────────────────────────
+export async function writePlan(repoRoot, plan, scope) {
+    const redactedPlan = redactSecretsInValue(plan);
+    validatePlan(redactedPlan); // throws LIT_LOOP_PLAN_INVALID before any write — never write a bad object
+    const dir = litLoopDir(repoRoot, scope);
+    try {
+        await mkdir(dir, { recursive: true });
+    }
+    catch (err) {
+        throw writeFailed(`failed to create ${dir}`, err, { path: dir });
+    }
+    await atomicWrite(litLoopGoalsPath(repoRoot, scope), `${JSON.stringify(redactedPlan, null, 2)}\n`);
+}
+// ── writeBrief (atomic, intentional overwrite; addendum §A) ──────────────────
+export async function writeBrief(repoRoot, brief, scope) {
+    const dir = litLoopDir(repoRoot, scope);
+    try {
+        await mkdir(dir, { recursive: true });
+    }
+    catch (err) {
+        throw writeFailed(`failed to create ${dir}`, err, { path: dir });
+    }
+    await atomicWrite(litLoopBriefPath(repoRoot, scope), redactSecretsInValue(brief));
+}
+export async function readBrief(repoRoot, scope) {
+    try {
+        return await readFile(litLoopBriefPath(repoRoot, scope), "utf8");
+    }
+    catch (err) {
+        if (errnoCode(err) === "ENOENT") {
+            throw new LitLoopStateError(`lit-loop brief not found at ${repoRelative(litLoopBriefPath(repoRoot, scope), repoRoot)}`, "LIT_LOOP_PLAN_MISSING", { details: { path: repoRelative(litLoopBriefPath(repoRoot, scope), repoRoot) } });
+        }
+        throw writeFailed("failed to read brief", err);
+    }
+}
+// ── appendLedger (append-only, never read-modify-write) ──────────────────────
+export async function appendLedger(repoRoot, entry, scope) {
+    const dir = litLoopDir(repoRoot, scope);
+    try {
+        await mkdir(dir, { recursive: true });
+    }
+    catch (err) {
+        throw writeFailed(`failed to create ${dir}`, err, { path: dir });
+    }
+    const filled = redactSecretsInValue({ ...entry, at: entry.at ?? iso() });
+    try {
+        await appendFile(litLoopLedgerPath(repoRoot, scope), `${JSON.stringify(filled)}\n`, "utf8");
+    }
+    catch (err) {
+        throw writeFailed("failed to append ledger entry", err, { kind: entry.kind });
+    }
+}
+export async function readLedger(repoRoot, scope) {
+    let raw;
+    try {
+        raw = await readFile(litLoopLedgerPath(repoRoot, scope), "utf8");
+    }
+    catch (err) {
+        if (errnoCode(err) === "ENOENT") {
+            return { entries: [], skipped: 0 };
+        }
+        throw writeFailed("failed to read ledger", err);
+    }
+    const entries = [];
+    let skipped = 0;
+    for (const line of raw.split(/\r?\n/)) {
+        if (line.trim() === "") {
+            continue;
+        }
+        try {
+            entries.push(JSON.parse(line));
+        }
+        catch {
+            skipped += 1; // fail-open: one bad line never blinds the audit trail
+        }
+    }
+    return { entries, skipped };
+}
+// ── ensureEvidenceDir ────────────────────────────────────────────────────────
+export async function ensureEvidenceDir(repoRoot, scope) {
+    const dir = litLoopEvidenceDir(repoRoot, scope);
+    try {
+        await mkdir(dir, { recursive: true });
+    }
+    catch (err) {
+        throw writeFailed(`failed to create ${dir}`, err, { path: dir });
+    }
+    return dir;
+}
+// ── corruption recovery (backup + report + ledger; NEVER auto-recreate) ──────
+function compactIso() {
+    // e.g. 20260613T090100Z — filesystem-safe, sortable.
+    return iso()
+        .replace(/[-:]/g, "")
+        .replace(/\.\d{3}Z$/, "Z");
+}
+function sha256(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+async function readReusableRecovery(repoRoot, dir, reportPath, rawHash, byteLength) {
+    try {
+        const report = JSON.parse(await readFile(reportPath, "utf8"));
+        if (report.file !== LIT_LOOP_GOALS ||
+            report.byteLength !== byteLength ||
+            report.sha256 !== rawHash ||
+            typeof report.backup !== "string") {
+            return undefined;
+        }
+        const backupPath = join(repoRoot, report.backup);
+        if (!backupPath.startsWith(`${dir}/`))
+            return undefined;
+        await stat(backupPath);
+        return { backupPath, report: report };
+    }
+    catch {
+        return undefined;
+    }
+}
+async function recoverCorrupt(repoRoot, scope, raw, cause) {
+    const dir = litLoopDir(repoRoot, scope);
+    const goalsPath = litLoopGoalsPath(repoRoot, scope);
+    const reason = cause instanceof Error ? cause.message : String(cause);
+    const reportPath = join(dir, "state-recovery.json");
+    const byteLength = Buffer.byteLength(raw, "utf8");
+    const rawHash = sha256(raw);
+    const reusable = await readReusableRecovery(repoRoot, dir, reportPath, rawHash, byteLength);
+    const backupPath = reusable?.backupPath ?? `${goalsPath}.corrupt-${compactIso()}.bak`;
+    // 1. Preserve the exact bad bytes for forensics — never delete the user's data.
+    if (reusable === undefined) {
+        await writeFile(backupPath, raw, "utf8").catch(() => undefined);
+    }
+    // 2. Machine-readable recovery report.
+    const report = reusable?.report ?? {
+        at: iso(),
+        file: LIT_LOOP_GOALS,
+        backup: repoRelative(backupPath, repoRoot),
+        reason,
+        byteLength,
+        sha256: rawHash,
+    };
+    if (reusable === undefined) {
+        await writeFile(reportPath, `${JSON.stringify(report, null, 2)}\n`, "utf8").catch(() => undefined);
+    }
+    // 3. Best-effort ledger line (recovery does not depend on the ledger succeeding).
+    await appendLedger(repoRoot, {
+        at: iso(),
+        kind: "state_recovered",
+        message: `lit-loop plan corrupt: ${reason}`,
+        before: { backup: report.backup },
+    }, scope).catch(() => undefined);
+    throw new LitLoopStateError(`lit-loop plan at ${repoRelative(goalsPath, repoRoot)} is corrupt; backed up.`, "LIT_LOOP_PLAN_CORRUPT", { cause, details: { backup: report.backup, report: repoRelative(reportPath, repoRoot) } });
+}
+// ── readPlan ─────────────────────────────────────────────────────────────────
+export async function readPlan(repoRoot, scope) {
+    const goalsPath = litLoopGoalsPath(repoRoot, scope);
+    let raw;
+    try {
+        raw = await readFile(goalsPath, "utf8");
+    }
+    catch (err) {
+        if (errnoCode(err) === "ENOENT") {
+            throw new LitLoopStateError(`lit-loop plan not found at ${repoRelative(goalsPath, repoRoot)}`, "LIT_LOOP_PLAN_MISSING", { details: { path: repoRelative(goalsPath, repoRoot) } });
+        }
+        throw writeFailed(`failed to read ${goalsPath}`, err, { path: goalsPath });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        return recoverCorrupt(repoRoot, scope, raw, err);
+    }
+    const reason = planInvalidReason(parsed);
+    if (reason !== null) {
+        return recoverCorrupt(repoRoot, scope, raw, new LitLoopStateError(reason, "LIT_LOOP_PLAN_INVALID", { details: { reason } }));
+    }
+    return parsed;
+}
+// ── initState (idempotent; dir → brief → plan → ledger) ──────────────────────
+export async function initState(repoRoot, args) {
+    const scope = { sessionId: args.sessionId ?? null };
+    const dir = litLoopDir(repoRoot, scope); // asserts repoRoot absolute
+    try {
+        await mkdir(dir, { recursive: true });
+        await mkdir(litLoopEvidenceDir(repoRoot, scope), { recursive: true });
+    }
+    catch (err) {
+        throw writeFailed(`failed to create ${dir}`, err, { path: dir });
+    }
+    // brief.md — write only if absent (never clobber a human-edited brief).
+    const briefPath = litLoopBriefPath(repoRoot, scope);
+    if (!(await statExists(briefPath))) {
+        await atomicWrite(briefPath, redactSecretsInValue(args.brief));
+    }
+    // goals.json — return an existing valid plan unchanged (idempotent).
+    if (await statExists(litLoopGoalsPath(repoRoot, scope))) {
+        const existing = await readPlan(repoRoot, scope);
+        return existing;
+    }
+    const now = iso();
+    const sessionId = normalizeSessionId(args.sessionId);
+    const plan = {
+        version: 1,
+        createdAt: now,
+        updatedAt: now,
+        briefPath: repoRelative(briefPath, repoRoot),
+        goalsPath: repoRelative(litLoopGoalsPath(repoRoot, scope), repoRoot),
+        ledgerPath: repoRelative(litLoopLedgerPath(repoRoot, scope), repoRoot),
+        evidenceDir: repoRelative(litLoopEvidenceDir(repoRoot, scope), repoRoot),
+        sessionId,
+        goals: [],
+    };
+    await writePlan(repoRoot, plan, scope);
+    await appendLedger(repoRoot, { at: now, kind: "plan_created", message: "Initialized lit-loop state" }, scope);
+    return plan;
+}
+// ── exit-code mapping (A3 C7 corrected + addendum §A.2: 3/4/5) ───────────────
+export function exitCodeFor(err) {
+    if (err instanceof LitLoopStateError) {
+        switch (err.code) {
+            case "LIT_LOOP_PLAN_MISSING":
+                return 3;
+            case "LIT_LOOP_PLAN_CORRUPT":
+                return 4;
+            case "LIT_LOOP_WRITE_FAILED":
+                return 5;
+            case "LIT_LOOP_PLAN_INVALID":
+            case "LIT_LOOP_EVIDENCE_NAME_UNSAFE":
+            case "LIT_LOOP_REPO_ROOT_INVALID":
+                return 2;
+            default:
+                return 1;
+        }
+    }
+    return 1;
+}

package/node_modules/@litcodex/lit-loop/dist/state-types.d.ts

@@ -0,0 +1,121 @@
+export type LitLoopGoalStatus = "pending" | "in_progress" | "complete" | "failed" | "blocked";
+export type LitLoopCriterionStatus = "pending" | "pass" | "fail" | "blocked";
+/**
+ * MVP user-model union — exactly three values (A3 C7 + S08-addendum §B.1.1). `"adversarial"`
+ * was dropped: M09's builder emits only these three, so admitting a fourth created a no-op
+ * branch + validation mismatch. Re-introducing it is a coordinated M08+M09 change.
+ */
+export type LitLoopUserModel = "happy" | "edge" | "regression";
+export type LitLoopCodexGoalMode = "aggregate" | "per_story";
+/** Frozen tuple of the three user-model values (enumerable, single source). */
+export declare const LIT_LOOP_USER_MODELS: readonly LitLoopUserModel[];
+/** Lit-loop goal events plus canonical start-work lifecycle events. */
+export declare const LIT_LOOP_LEDGER_EVENT_KINDS: readonly ["plan_created", "goal_added", "goal_started", "goal_resumed", "goal_retried", "goal_completed", "goal_failed", "goal_blocked", "evidence_captured", "criterion_failed", "criterion_blocked", "criteria_revised", "state_recovered", "start_work_initialized", "start_work_continuation_issued", "start_work_paused", "start_work_resumed", "start_work_cancelled", "start_work_completed"];
+export type LitLoopLedgerEventKind = (typeof LIT_LOOP_LEDGER_EVENT_KINDS)[number];
+/** Goal-id: uppercase `G`, exactly 3 digits, optional non-empty lowercase-slug. `G001-` invalid. */
+export declare const LIT_LOOP_GOAL_ID_RE: RegExp;
+/** Criterion-id: uppercase `C`, exactly 3 digits. */
+export declare const LIT_LOOP_CRITERION_ID_RE: RegExp;
+export interface LitLoopCriterion {
+    readonly id: string;
+    readonly scenario: string;
+    readonly userModel: LitLoopUserModel;
+    readonly expectedEvidence: string;
+    capturedEvidence: string | null;
+    status: LitLoopCriterionStatus;
+    capturedAt?: string;
+    notes?: string;
+}
+export interface LitLoopGoal {
+    id: string;
+    title: string;
+    objective: string;
+    status: LitLoopGoalStatus;
+    successCriteria: LitLoopCriterion[];
+    attempt: number;
+    createdAt: string;
+    updatedAt: string;
+    startedAt?: string;
+    completedAt?: string;
+    failedAt?: string;
+    evidence?: string;
+    failureReason?: string;
+}
+export interface LitLoopPlan {
+    version: 1;
+    createdAt: string;
+    updatedAt: string;
+    briefPath: string;
+    goalsPath: string;
+    ledgerPath: string;
+    evidenceDir: string;
+    sessionId: string | null;
+    codexGoalMode?: LitLoopCodexGoalMode;
+    codexObjective?: string;
+    activeGoalId?: string;
+    goals: LitLoopGoal[];
+}
+export interface LitLoopLedgerEntry {
+    at: string;
+    kind: LitLoopLedgerEventKind;
+    goalId?: string;
+    criterionId?: string;
+    goalStatus?: LitLoopGoalStatus;
+    criterionStatus?: LitLoopCriterionStatus;
+    message?: string;
+    evidence?: string;
+    fromStatus?: LitLoopGoalStatus;
+    attempt?: number;
+    before?: unknown;
+    after?: unknown;
+    workId?: string;
+    transitionId?: string;
+    revision?: number;
+    workStatus?: "active" | "paused" | "abandoned" | "completed";
+    fromWorkStatus?: "active" | "paused" | "abandoned" | "completed";
+    toWorkStatus?: "active" | "paused" | "abandoned" | "completed";
+    plan?: string;
+    sessionId?: string;
+    reason?: string;
+    turnId?: string;
+    reasonCode?: "authorization_required" | "credential_required" | "host_capability_required" | "explicit_user_resume" | "user_cancelled" | "completed";
+    progressToken?: string;
+    initFingerprint?: string;
+    boundary?: {
+        boundary_id: string;
+        authority_id: string;
+        action: string;
+        root: string;
+    };
+    grant?: {
+        grant_id: string;
+        authority_id: string;
+        boundary_id: string;
+        action: string;
+        root: string;
+    };
+}
+/** Caller-supplied ledger entry: `at` is optional because `appendLedger` fills it when absent. */
+export type LitLoopLedgerInput = Omit<LitLoopLedgerEntry, "at"> & {
+    at?: string;
+};
+export interface LitLoopStateErrorOptions {
+    readonly cause?: unknown;
+    readonly details?: Record<string, unknown>;
+}
+/**
+ * The single error type the store throws. Consumers branch on the stable SCREAMING_SNAKE
+ * `.code` (NOT on `instanceof` subclasses — none exist). `details` is undefined unless supplied.
+ */
+export declare class LitLoopStateError extends Error {
+    readonly name = "LitLoopStateError";
+    readonly code: string;
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, code: string, opts?: LitLoopStateErrorOptions);
+}
+/** Single clock seam. Tests may inject a fake by spying on this module export. */
+export declare function iso(): string;
+export declare function isUserModel(value: unknown): value is LitLoopUserModel;
+export declare function isLedgerEventKind(value: unknown): value is LitLoopLedgerEventKind;
+export declare function isGoalId(value: unknown): value is string;
+export declare function isCriterionId(value: unknown): value is string;

package/node_modules/@litcodex/lit-loop/dist/state-types.js

@@ -0,0 +1,67 @@
+// src/state-types.ts — M08/T13 SINGLE schema source (A3 C7, S08-addendum §B).
+//
+// The persisted TypeScript shapes for the lit-loop durable state, the status/kind unions, the
+// `LitLoopStateError` class, the `iso()` clock seam, and the small pure validators the store
+// (and M09's plan builder) share. Types + error + pure predicates only; ZERO I/O. M09's
+// `loop-types.ts` is a re-export barrel of these shapes — no parallel schema is declared anywhere.
+/** Frozen tuple of the three user-model values (enumerable, single source). */
+export const LIT_LOOP_USER_MODELS = Object.freeze(["happy", "edge", "regression"]);
+/** Lit-loop goal events plus canonical start-work lifecycle events. */
+export const LIT_LOOP_LEDGER_EVENT_KINDS = [
+    "plan_created",
+    "goal_added",
+    "goal_started",
+    "goal_resumed",
+    "goal_retried",
+    "goal_completed",
+    "goal_failed",
+    "goal_blocked",
+    "evidence_captured",
+    "criterion_failed",
+    "criterion_blocked",
+    "criteria_revised",
+    "state_recovered",
+    "start_work_initialized",
+    "start_work_continuation_issued",
+    "start_work_paused",
+    "start_work_resumed",
+    "start_work_cancelled",
+    "start_work_completed",
+];
+// ── Id regexes (A3 Part D / S08-addendum §B.1.2) ─────────────────────────────
+/** Goal-id: uppercase `G`, exactly 3 digits, optional non-empty lowercase-slug. `G001-` invalid. */
+export const LIT_LOOP_GOAL_ID_RE = /^G\d{3}(-[a-z0-9-]+)?$/;
+/** Criterion-id: uppercase `C`, exactly 3 digits. */
+export const LIT_LOOP_CRITERION_ID_RE = /^C\d{3}$/;
+/**
+ * The single error type the store throws. Consumers branch on the stable SCREAMING_SNAKE
+ * `.code` (NOT on `instanceof` subclasses — none exist). `details` is undefined unless supplied.
+ */
+export class LitLoopStateError extends Error {
+    constructor(message, code, opts) {
+        super(message, opts?.cause === undefined ? undefined : { cause: opts.cause });
+        this.name = "LitLoopStateError";
+        this.code = code;
+        if (opts?.details !== undefined) {
+            this.details = opts.details;
+        }
+    }
+}
+// ── Clock seam ───────────────────────────────────────────────────────────────
+/** Single clock seam. Tests may inject a fake by spying on this module export. */
+export function iso() {
+    return new Date().toISOString();
+}
+// ── Pure validators (shared by the store's validatePlan and M09's builder tests) ──
+export function isUserModel(value) {
+    return typeof value === "string" && LIT_LOOP_USER_MODELS.includes(value);
+}
+export function isLedgerEventKind(value) {
+    return typeof value === "string" && LIT_LOOP_LEDGER_EVENT_KINDS.includes(value);
+}
+export function isGoalId(value) {
+    return typeof value === "string" && LIT_LOOP_GOAL_ID_RE.test(value);
+}
+export function isCriterionId(value) {
+    return typeof value === "string" && LIT_LOOP_CRITERION_ID_RE.test(value);
+}