@latysh-development/monolith 0.0.0-stage → 0.1.0-alpha.0

package/dist/coordinatorium/mission.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Tactical Coordinatorium — mission lifecycle.
+ *
+ * A mission is a unit of development work tracked across AI sessions.
+ * This module owns mission semantics (ID generation, valid transitions);
+ * state-keeper.ts owns persistence and never knows what a mission is.
+ */
+import { type StateReadTarget, type StateWriteTarget } from './state-keeper.js';
+import type { Mission, MissionResult } from './types.js';
+export interface StartMissionInput {
+    title: string;
+    system: string;
+}
+/**
+ * Register a new mission as in_progress. ID generation happens inside the
+ * same locked critical section as the write, so concurrent `start` calls
+ * from independent processes can never collide on an ID.
+ */
+export declare function startMission(target: StateWriteTarget, input: StartMissionInput): Promise<Mission>;
+export declare function listMissions(target: StateReadTarget): Promise<Mission[]>;
+export declare function getMission(target: StateReadTarget, id: string): Promise<Mission>;
+export interface FinishMissionInput {
+    result: MissionResult;
+    summary?: string | null;
+}
+/**
+ * Transition a mission from in_progress to a terminal state. Any other
+ * starting status (already completed/failed/cancelled) is rejected — once
+ * terminal, a mission's lifecycle is closed.
+ */
+export declare function finishMission(target: StateWriteTarget, id: string, input: FinishMissionInput): Promise<Mission>;
+//# sourceMappingURL=mission.d.ts.map

package/dist/coordinatorium/mission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mission.d.ts","sourceRoot":"","sources":["../../src/coordinatorium/mission.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAA0B,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAExG,OAAO,KAAK,EAAuB,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAc9E,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAUD;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,gBAAgB,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC,CAqBvG;AAED,wBAAsB,YAAY,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAG9E;AAED,wBAAsB,UAAU,CAAC,MAAM,EAAE,eAAe,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAKtF;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,aAAa,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,gBAAgB,EACxB,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,OAAO,CAAC,CAsBlB"}

package/dist/coordinatorium/mission.js

@@ -0,0 +1,87 @@
+/**
+ * Tactical Coordinatorium — mission lifecycle.
+ *
+ * A mission is a unit of development work tracked across AI sessions.
+ * This module owns mission semantics (ID generation, valid transitions);
+ * state-keeper.ts owns persistence and never knows what a mission is.
+ */
+import { mutateState, readState } from './state-keeper.js';
+import { MissionNotFoundError, InvalidTransitionError, ValidationError } from './errors.js';
+const MISSION_ID_RE = /^MIS-(\d+)$/;
+const MISSION_RESULTS = ['completed', 'failed', 'cancelled'];
+function nextMissionId(missions) {
+    let max = 0;
+    for (const id of Object.keys(missions)) {
+        const match = MISSION_ID_RE.exec(id);
+        if (match)
+            max = Math.max(max, Number(match[1]));
+    }
+    return `MIS-${String(max + 1).padStart(4, '0')}`;
+}
+function requireNonEmptyString(value, field) {
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        throw new ValidationError(`"${field}" must be a non-empty string`);
+    }
+    return trimmed;
+}
+/**
+ * Register a new mission as in_progress. ID generation happens inside the
+ * same locked critical section as the write, so concurrent `start` calls
+ * from independent processes can never collide on an ID.
+ */
+export async function startMission(target, input) {
+    const title = requireNonEmptyString(input.title, 'title');
+    const system = requireNonEmptyString(input.system, 'system');
+    const { result } = await mutateState(target, (draft) => {
+        const id = nextMissionId(draft.tactical.missions);
+        const now = new Date().toISOString();
+        const mission = {
+            id,
+            title,
+            system,
+            status: 'in_progress',
+            startedAt: now,
+            updatedAt: now,
+            summary: null,
+        };
+        draft.tactical.missions[id] = mission;
+        return mission;
+    });
+    return result;
+}
+export async function listMissions(target) {
+    const state = await readState(target);
+    return Object.values(state.tactical.missions).sort((a, b) => a.startedAt.localeCompare(b.startedAt));
+}
+export async function getMission(target, id) {
+    const state = await readState(target);
+    const mission = state.tactical.missions[id];
+    if (!mission)
+        throw new MissionNotFoundError(id);
+    return mission;
+}
+/**
+ * Transition a mission from in_progress to a terminal state. Any other
+ * starting status (already completed/failed/cancelled) is rejected — once
+ * terminal, a mission's lifecycle is closed.
+ */
+export async function finishMission(target, id, input) {
+    if (!MISSION_RESULTS.includes(input.result)) {
+        throw new ValidationError(`"result" must be one of ${MISSION_RESULTS.join(', ')}, got "${String(input.result)}"`);
+    }
+    const { result } = await mutateState(target, (draft) => {
+        const mission = draft.tactical.missions[id];
+        if (!mission)
+            throw new MissionNotFoundError(id);
+        if (mission.status !== 'in_progress') {
+            throw new InvalidTransitionError(`Mission "${id}" is already "${mission.status}" and cannot transition to "${input.result}"`);
+        }
+        mission.status = input.result;
+        mission.updatedAt = new Date().toISOString();
+        if (input.summary !== undefined)
+            mission.summary = input.summary;
+        return mission;
+    });
+    return result;
+}

package/dist/coordinatorium/state-keeper.d.ts

@@ -0,0 +1,115 @@
+/**
+ * State Keeper — the single point of read/write access to state.json.
+ *
+ * Guarantees:
+ * - Atomic persistence: writes land via write-temp-then-rename, so a reader
+ *   never observes a partially written file.
+ * - No lost updates: every mutation runs inside a cross-process lock (see
+ *   lock.ts), read-modify-write, with a monotonic revision bump.
+ * - Never silently overwrites corrupted or unsupported state: malformed
+ *   JSON or a schema mismatch throws before anything is written.
+ *
+ * AI reports state; this module validates and persists it. It has no
+ * knowledge of what a "mission" is — that belongs to mission.ts.
+ */
+import { type LockOptions } from './lock.js';
+import { type WriteWarning } from '../root/index.js';
+import { type CoordinatoriumState } from './types.js';
+export declare const STATE_FILE_NAME = "state.json";
+/**
+ * Protective ceiling for `state.json` (SEC-001B.1) — NOT a retention policy.
+ * Append-only checkpoints grow the file without bound; see STATE-001.
+ * Enforced on read (bounded reader) and before an atomic write.
+ */
+export declare const MAX_STATE_BYTES: number;
+export declare function stateFilePath(stateDir: string): string;
+/**
+ * Where a write may land (SEC-001B.2, ADR-012). There is no default and no
+ * plain-string form: the caller states which trust model applies.
+ *
+ *  - `project`: `projectRoot` is the boundary. `stateDir` must lie inside it and
+ *    no component below the root may be a symlink (even one that stays inside).
+ *  - `trusted-directory`: the caller asserts that `stateDir` AND ALL ITS
+ *    ANCESTORS are trusted. Nothing about the ancestors is checked (so a
+ *    symlinked `.monolith` is invisible in this mode); only what lies below
+ *    `stateDir` is. A missing `stateDir` is created.
+ *
+ * `onWarning` receives non-fatal findings reported after a successful publish
+ * (durability downgrade, platform note, ...). It is called once per warning,
+ * after the state lock has been released; an exception it throws is ignored and
+ * never affects the result. Without it they are only returned by `mutateState`.
+ */
+export type StateWriteTarget = {
+    scope: 'project';
+    projectRoot: string;
+    stateDir: string;
+    onWarning?: (warning: WriteWarning) => void;
+} | {
+    scope: 'trusted-directory';
+    stateDir: string;
+    onWarning?: (warning: WriteWarning) => void;
+};
+/** Project-scoped write target (the CLI always uses this). */
+export declare function projectTarget(projectRoot: string, stateDir: string, onWarning?: (warning: WriteWarning) => void): StateWriteTarget;
+/** Trusted-directory write target: `stateDir` and its ancestors are asserted trusted by the caller. */
+export declare function trustedDirectoryTarget(stateDir: string, onWarning?: (warning: WriteWarning) => void): StateWriteTarget;
+/**
+ * Where a read may look (SEC-001B.1-R). Same shape and same scopes as a write
+ * target, minus `onWarning`; there is no default and no plain-string form. A
+ * `StateWriteTarget` is accepted as is.
+ */
+export type StateReadTarget = {
+    scope: 'project';
+    projectRoot: string;
+    stateDir: string;
+} | {
+    scope: 'trusted-directory';
+    stateDir: string;
+};
+/**
+ * Validate the shape of parsed JSON and return a typed, defensively-copied
+ * CoordinatoriumState. Throws StateSchemaError for anything that does not
+ * match a supported schema version — this function never "fixes" or
+ * partially accepts malformed state.
+ *
+ * Supports exactly two on-disk shapes:
+ * - `schemaVersion: 2` (current) — `tactical.checkpoints` is required.
+ * - `schemaVersion: 1` (legacy, pre-COORDINATORIUM-002) — migrated
+ *   in-memory to v2 on read (see `migrateV1ToV2`). Anything else
+ *   (including a *newer* version this binary doesn't know about) is
+ *   rejected outright — this is the deliberate fix for the compatibility
+ *   gap an independent review found in the first COORDINATORIUM-002 cut:
+ *   that cut kept `schemaVersion` at 1 while adding `tactical.checkpoints`,
+ *   so an *older* binary (hardcoded to `schemaVersion === 1`, with no
+ *   notion of checkpoints) could read a checkpoint-bearing v1-tagged file,
+ *   reconstruct state from only the fields it knew about (`tactical: {
+ *   missions }`, dropping checkpoints entirely — this function has never
+ *   been a passthrough for unknown fields), and silently overwrite the
+ *   file on its next mutateState call, destroying checkpoint history with
+ *   no error raised. Bumping to 2 converts that silent data loss into a
+ *   loud, immediate `StateSchemaError` for any reader that doesn't
+ *   understand v2 — the version check below runs before anything is ever
+ *   read into a mutable draft, so mutateState never reaches its write step
+ *   (same proven pattern as the existing corrupted-JSON guard).
+ */
+export declare function validateState(raw: unknown): CoordinatoriumState;
+/**
+ * Read current state without taking a lock. If the file does not exist,
+ * returns a fresh initial state WITHOUT persisting it — read paths never
+ * have the side effect of creating state.json. Corrupted JSON or an
+ * unsupported schema throws rather than being silently replaced.
+ */
+export declare function readState(target: StateReadTarget): Promise<CoordinatoriumState>;
+/**
+ * Read-modify-write under an exclusive cross-process lock. `mutator`
+ * receives a deep-cloned draft of the current state and an `applyResult`
+ * callback to hand back an arbitrary value (e.g. the mission it just
+ * created) alongside the write. The revision is incremented exactly once
+ * per successful call, after the mutator returns.
+ */
+export declare function mutateState<T>(target: StateWriteTarget, mutator: (draft: CoordinatoriumState) => T, lockOptions?: LockOptions): Promise<{
+    state: CoordinatoriumState;
+    result: T;
+    warnings: WriteWarning[];
+}>;
+//# sourceMappingURL=state-keeper.d.ts.map

package/dist/coordinatorium/state-keeper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-keeper.d.ts","sourceRoot":"","sources":["../../src/coordinatorium/state-keeper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAE1D,OAAO,EASL,KAAK,YAAY,EAClB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAIL,KAAK,mBAAmB,EAIzB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,eAAe,eAAe,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,eAAe,QAAmB,CAAC;AAEhD,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEtD;AAMD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,IAAI,CAAA;CAAE,GACxG;IAAE,KAAK,EAAE,mBAAmB,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,IAAI,CAAA;CAAE,CAAC;AAElG,8DAA8D;AAC9D,wBAAgB,aAAa,CAC3B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,IAAI,GAC1C,gBAAgB,CAElB;AAED,uGAAuG;AACvG,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,IAAI,GAAG,gBAAgB,CAEtH;AAwCD;;;;GAIG;AACH,MAAM,MAAM,eAAe,GACvB;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC3D;IAAE,KAAK,EAAE,mBAAmB,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AA8FrD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,mBAAmB,CAmE/D;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAqCrF;AA0ED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,CAAC,EACjC,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,CAAC,EAC1C,WAAW,CAAC,EAAE,WAAW,GACxB,OAAO,CAAC;IAAE,KAAK,EAAE,mBAAmB,CAAC;IAAC,MAAM,EAAE,CAAC,CAAC;IAAC,QAAQ,EAAE,YAAY,EAAE,CAAA;CAAE,CAAC,CA0B9E"}

package/dist/coordinatorium/state-keeper.js

@@ -0,0 +1,396 @@
+/**
+ * State Keeper — the single point of read/write access to state.json.
+ *
+ * Guarantees:
+ * - Atomic persistence: writes land via write-temp-then-rename, so a reader
+ *   never observes a partially written file.
+ * - No lost updates: every mutation runs inside a cross-process lock (see
+ *   lock.ts), read-modify-write, with a monotonic revision bump.
+ * - Never silently overwrites corrupted or unsupported state: malformed
+ *   JSON or a schema mismatch throws before anything is written.
+ *
+ * AI reports state; this module validates and persists it. It has no
+ * knowledge of what a "mission" is — that belongs to mission.ts.
+ */
+import { lstatSync, mkdirSync } from 'fs';
+import { isAbsolute, join } from 'path';
+import { acquireLock } from './lock.js';
+import { StateCorruptedError, StateSchemaError, StateFileError } from './errors.js';
+import { SafeWriteError, openParent, projectBoundary, readBoundedFileStable, replaceFile, trustedDirectoryBoundary, } from '../root/index.js';
+import { STATE_SCHEMA_VERSION, LEGACY_SCHEMA_VERSION_V1, createInitialState, } from './types.js';
+export const STATE_FILE_NAME = 'state.json';
+/**
+ * Protective ceiling for `state.json` (SEC-001B.1) — NOT a retention policy.
+ * Append-only checkpoints grow the file without bound; see STATE-001.
+ * Enforced on read (bounded reader) and before an atomic write.
+ */
+export const MAX_STATE_BYTES = 16 * 1024 * 1024;
+export function stateFilePath(stateDir) {
+    return join(stateDir, STATE_FILE_NAME);
+}
+function lockFilePath(stateDir) {
+    return `${stateFilePath(stateDir)}.lock`;
+}
+/** Project-scoped write target (the CLI always uses this). */
+export function projectTarget(projectRoot, stateDir, onWarning) {
+    return { scope: 'project', projectRoot, stateDir, onWarning };
+}
+/** Trusted-directory write target: `stateDir` and its ancestors are asserted trusted by the caller. */
+export function trustedDirectoryTarget(stateDir, onWarning) {
+    return { scope: 'trusted-directory', stateDir, onWarning };
+}
+function scopeRequired(fn, stateDir) {
+    return new SafeWriteError(`${fn} requires an explicit write scope. Replace ${fn}(dir, ...) with ` +
+        `${fn}({ scope: 'trusted-directory', stateDir: dir }, ...) when dir and its ancestors are trusted, or with ` +
+        `${fn}({ scope: 'project', projectRoot, stateDir }, ...) when acting on a project (ADR-012).`, {
+        code: 'WRITE_SCOPE_REQUIRED',
+        phase: 'scope',
+        publication: 'NOT_PUBLISHED',
+        path: typeof stateDir === 'string' ? stateDir : '',
+    });
+}
+/** Validates the scope and builds the boundary. Throws SafeWriteError; touches nothing in `project` scope. */
+function resolveWriteTarget(target, fn) {
+    if (typeof target !== 'object' || target === null)
+        throw scopeRequired(fn, target);
+    const t = target;
+    if (typeof t.stateDir !== 'string' || t.stateDir.length === 0)
+        throw scopeRequired(fn, t.stateDir);
+    if (t.scope === 'project') {
+        if (typeof t.projectRoot !== 'string' || t.projectRoot.length === 0)
+            throw scopeRequired(fn, t.stateDir);
+        return { boundary: projectBoundary(t.projectRoot), stateDir: t.stateDir, onWarning: t.onWarning };
+    }
+    if (t.scope === 'trusted-directory') {
+        // The caller vouches for the directory and its ancestors, so creating it
+        // (and any missing ancestors) is within the model they chose.
+        mkdirSync(t.stateDir, { recursive: true });
+        return { boundary: trustedDirectoryBoundary(t.stateDir), stateDir: t.stateDir, onWarning: t.onWarning };
+    }
+    throw scopeRequired(fn, t.stateDir);
+}
+/** Validates the read scope; returns the boundary directory. Throws StateFileError, touches nothing. */
+function resolveReadTarget(target, fn) {
+    const bad = (why) => new StateFileError('READ_BOUNDARY_INVALID', `${fn} requires an explicit read scope (${why}). Use { scope: 'project', projectRoot, stateDir } for a project, ` +
+        `or { scope: 'trusted-directory', stateDir } when stateDir is trusted (SEC-001B.1-R).`);
+    if (typeof target !== 'object' || target === null)
+        throw bad('got a non-object');
+    const t = target;
+    // Every path is validated here, before any filesystem call: a path that cannot be
+    // trusted must never be probed (and so never "not found" -> empty state) (L-2).
+    // The cwd is never a boundary, so a relative path is refused, not resolved.
+    if (typeof t.stateDir !== 'string' || t.stateDir.length === 0)
+        throw bad('stateDir is missing');
+    if (!isAbsolute(t.stateDir))
+        throw bad('stateDir must be an absolute path');
+    if (t.scope === 'project') {
+        if (typeof t.projectRoot !== 'string' || t.projectRoot.length === 0)
+            throw bad('projectRoot is missing');
+        if (!isAbsolute(t.projectRoot))
+            throw bad('projectRoot must be an absolute path');
+        return { boundary: t.projectRoot, stateDir: t.stateDir };
+    }
+    if (t.scope === 'trusted-directory')
+        return { boundary: t.stateDir, stateDir: t.stateDir };
+    throw bad('unknown scope');
+}
+const MISSION_STATUSES = ['in_progress', 'completed', 'failed', 'cancelled'];
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function validateMission(id, raw) {
+    if (!isPlainObject(raw)) {
+        throw new StateSchemaError(`Mission "${id}" is not an object`);
+    }
+    const { title, system, status, startedAt, updatedAt, summary } = raw;
+    if (raw.id !== id) {
+        throw new StateSchemaError(`Mission "${id}" has mismatched id field "${String(raw.id)}"`);
+    }
+    if (typeof title !== 'string' || title.length === 0) {
+        throw new StateSchemaError(`Mission "${id}" has an invalid title`);
+    }
+    if (typeof system !== 'string' || system.length === 0) {
+        throw new StateSchemaError(`Mission "${id}" has an invalid system`);
+    }
+    if (typeof status !== 'string' || !MISSION_STATUSES.includes(status)) {
+        throw new StateSchemaError(`Mission "${id}" has an invalid status "${String(status)}"`);
+    }
+    if (typeof startedAt !== 'string') {
+        throw new StateSchemaError(`Mission "${id}" has an invalid startedAt`);
+    }
+    if (typeof updatedAt !== 'string') {
+        throw new StateSchemaError(`Mission "${id}" has an invalid updatedAt`);
+    }
+    if (summary !== null && typeof summary !== 'string') {
+        throw new StateSchemaError(`Mission "${id}" has an invalid summary`);
+    }
+    return { id, title, system, status: status, startedAt, updatedAt, summary };
+}
+function validateCheckpoint(id, raw) {
+    if (!isPlainObject(raw)) {
+        throw new StateSchemaError(`Checkpoint "${id}" is not an object`);
+    }
+    const { missionId, createdAt, summary, remainingSteps, context } = raw;
+    if (raw.id !== id) {
+        throw new StateSchemaError(`Checkpoint "${id}" has mismatched id field "${String(raw.id)}"`);
+    }
+    if (typeof missionId !== 'string' || missionId.length === 0) {
+        throw new StateSchemaError(`Checkpoint "${id}" has an invalid missionId`);
+    }
+    if (typeof createdAt !== 'string') {
+        throw new StateSchemaError(`Checkpoint "${id}" has an invalid createdAt`);
+    }
+    if (typeof summary !== 'string' || summary.length === 0) {
+        throw new StateSchemaError(`Checkpoint "${id}" has an invalid summary`);
+    }
+    if (!Array.isArray(remainingSteps) || !remainingSteps.every((s) => typeof s === 'string' && s.length > 0)) {
+        throw new StateSchemaError(`Checkpoint "${id}" has an invalid remainingSteps`);
+    }
+    if (context !== null && typeof context !== 'string') {
+        throw new StateSchemaError(`Checkpoint "${id}" has an invalid context`);
+    }
+    return {
+        id,
+        missionId,
+        createdAt,
+        summary,
+        remainingSteps: [...remainingSteps],
+        context: context ?? null,
+    };
+}
+/**
+ * Validate the shape of parsed JSON and return a typed, defensively-copied
+ * CoordinatoriumState. Throws StateSchemaError for anything that does not
+ * match a supported schema version — this function never "fixes" or
+ * partially accepts malformed state.
+ *
+ * Supports exactly two on-disk shapes:
+ * - `schemaVersion: 2` (current) — `tactical.checkpoints` is required.
+ * - `schemaVersion: 1` (legacy, pre-COORDINATORIUM-002) — migrated
+ *   in-memory to v2 on read (see `migrateV1ToV2`). Anything else
+ *   (including a *newer* version this binary doesn't know about) is
+ *   rejected outright — this is the deliberate fix for the compatibility
+ *   gap an independent review found in the first COORDINATORIUM-002 cut:
+ *   that cut kept `schemaVersion` at 1 while adding `tactical.checkpoints`,
+ *   so an *older* binary (hardcoded to `schemaVersion === 1`, with no
+ *   notion of checkpoints) could read a checkpoint-bearing v1-tagged file,
+ *   reconstruct state from only the fields it knew about (`tactical: {
+ *   missions }`, dropping checkpoints entirely — this function has never
+ *   been a passthrough for unknown fields), and silently overwrite the
+ *   file on its next mutateState call, destroying checkpoint history with
+ *   no error raised. Bumping to 2 converts that silent data loss into a
+ *   loud, immediate `StateSchemaError` for any reader that doesn't
+ *   understand v2 — the version check below runs before anything is ever
+ *   read into a mutable draft, so mutateState never reaches its write step
+ *   (same proven pattern as the existing corrupted-JSON guard).
+ */
+export function validateState(raw) {
+    if (!isPlainObject(raw)) {
+        throw new StateSchemaError('State root is not an object');
+    }
+    if (raw.schemaVersion !== STATE_SCHEMA_VERSION && raw.schemaVersion !== LEGACY_SCHEMA_VERSION_V1) {
+        throw new StateSchemaError(`Unsupported schemaVersion "${String(raw.schemaVersion)}" ` +
+            `(expected ${STATE_SCHEMA_VERSION}, or legacy ${LEGACY_SCHEMA_VERSION_V1} for migration)`);
+    }
+    if (typeof raw.revision !== 'number' || !Number.isInteger(raw.revision) || raw.revision < 0) {
+        throw new StateSchemaError(`Invalid revision "${String(raw.revision)}"`);
+    }
+    if (!isPlainObject(raw.strategic) || !isPlainObject(raw.strategic.systems)) {
+        throw new StateSchemaError('Invalid strategic.systems');
+    }
+    if (!isPlainObject(raw.tactical) || !isPlainObject(raw.tactical.missions)) {
+        throw new StateSchemaError('Invalid tactical.missions');
+    }
+    const missions = {};
+    for (const [id, m] of Object.entries(raw.tactical.missions)) {
+        missions[id] = validateMission(id, m);
+    }
+    const rawCheckpoints = raw.tactical.checkpoints;
+    const checkpoints = {};
+    if (raw.schemaVersion === LEGACY_SCHEMA_VERSION_V1) {
+        // v1→v2 migration path: a genuine pre-COORDINATORIUM-002 file has no
+        // `checkpoints` key at all — default to {}. Tolerate (and validate) one
+        // being present anyway, defensively, in case a file was ever written by
+        // the since-corrected transitional code that kept schemaVersion at 1
+        // while already writing checkpoints — nothing is lost either way.
+        if (rawCheckpoints !== undefined && !isPlainObject(rawCheckpoints)) {
+            throw new StateSchemaError('Invalid tactical.checkpoints');
+        }
+        if (rawCheckpoints !== undefined) {
+            for (const [id, c] of Object.entries(rawCheckpoints)) {
+                checkpoints[id] = validateCheckpoint(id, c);
+            }
+        }
+    }
+    else {
+        // schemaVersion === STATE_SCHEMA_VERSION (2): every v2 writer always
+        // serializes tactical.checkpoints (even as {}), so its absence here is
+        // itself a sign of a malformed/hand-edited file, not a legacy case —
+        // required, not defaulted.
+        if (!isPlainObject(rawCheckpoints)) {
+            throw new StateSchemaError('Invalid tactical.checkpoints');
+        }
+        for (const [id, c] of Object.entries(rawCheckpoints)) {
+            checkpoints[id] = validateCheckpoint(id, c);
+        }
+    }
+    // Migration is applied purely in-memory here — revision and every
+    // mission/checkpoint field are carried over exactly, only schemaVersion
+    // is relabeled. No write happens during a read (same "reads are never a
+    // side effect" rule as the missing-file case in readState below); the
+    // migrated v2 shape is only ever persisted to disk the next time
+    // mutateState's existing atomic read-modify-write cycle runs — no
+    // separate migration-write path, no new on-disk mechanism.
+    return {
+        schemaVersion: STATE_SCHEMA_VERSION,
+        revision: raw.revision,
+        strategic: { systems: { ...raw.strategic.systems } },
+        tactical: { missions, checkpoints },
+    };
+}
+/**
+ * Read current state without taking a lock. If the file does not exist,
+ * returns a fresh initial state WITHOUT persisting it — read paths never
+ * have the side effect of creating state.json. Corrupted JSON or an
+ * unsupported schema throws rather than being silently replaced.
+ */
+export async function readState(target) {
+    const { boundary, stateDir } = resolveReadTarget(target, 'readState');
+    const filePath = stateFilePath(stateDir);
+    // A trusted directory that does not exist holds no state (it is the boundary,
+    // so it cannot be walked to). In `project` scope a missing directory is
+    // reported by the reader itself as FILE_MISSING. Only ENOENT on the path itself
+    // counts as "does not exist": `existsSync` would also say so for a dangling
+    // symlink or a loop, and an unusable boundary is not an empty state — those fall
+    // through to the reader, which refuses them (READ_BOUNDARY_INVALID) (L-2).
+    if (target.scope === 'trusted-directory') {
+        try {
+            lstatSync(stateDir);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return createInitialState();
+        }
+    }
+    // Unified safe read (SEC-001B.1-R): explicit boundary, no symlink or hardlink,
+    // non-blocking (a FIFO at this path cannot hang us), capped at MAX_STATE_BYTES.
+    const read = readBoundedFileStable(filePath, `"${filePath}"`, { boundary, maxBytes: MAX_STATE_BYTES, allowEmpty: true }, true);
+    if (!read.ok) {
+        if (read.code === 'FILE_MISSING')
+            return createInitialState();
+        throw new StateFileError(read.code, read.detail);
+    }
+    const raw = 'content' in read ? read.content : '';
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new StateCorruptedError(`"${filePath}" is not valid JSON: ${msg}`);
+    }
+    return validateState(parsed);
+}
+/**
+ * The read that precedes a write. A symlink or hardlink at the destination is
+ * reported with the write-side typed error and `NOT_PUBLISHED`, exactly as before
+ * the unified read (SEC-001B.2 compat). Every other read failure — a FIFO or
+ * special file included (SEC-001B.1) — stays the StateFileError of the read.
+ */
+async function readStateForWrite(target, stateDir) {
+    try {
+        return await readState(target);
+    }
+    catch (err) {
+        if (err instanceof StateFileError) {
+            const code = err.fileCode === 'FILE_SYMLINK'
+                ? 'WRITE_TARGET_SYMLINK'
+                : err.fileCode === 'FILE_HARDLINKED'
+                    ? 'WRITE_TARGET_HARDLINKED'
+                    : null;
+            if (code !== null) {
+                throw new SafeWriteError(`${err.message} (refusing to replace it)`, {
+                    code,
+                    phase: 'validate',
+                    publication: 'NOT_PUBLISHED',
+                    path: stateFilePath(stateDir),
+                    cause: err,
+                });
+            }
+        }
+        throw err;
+    }
+}
+/**
+ * Persist `state` through the safe-write primitive (SEC-001B.2, ADR-012):
+ * temp file (`O_EXCL|O_NOFOLLOW`, `0600`) -> fsync -> `rename`, then fsync of
+ * the directory. A new `state.json` is `0600`; an existing one keeps its mode.
+ * A symlink, FIFO/special file or hardlinked file at the destination is
+ * refused (never replaced). Throws SafeWriteError with publication
+ * NOT_PUBLISHED or UNKNOWN; once published nothing throws — later findings are
+ * returned as warnings.
+ */
+function atomicWriteState(parent, filePath, state) {
+    const serialized = `${JSON.stringify(state, null, 2)}\n`;
+    // Refuse BEFORE creating the temp file: an oversized state.json would be
+    // unreadable by readState, locking the project out of its own state. The
+    // existing state.json is left untouched; nothing is compacted or dropped.
+    const bytes = Buffer.byteLength(serialized, 'utf8');
+    if (bytes > MAX_STATE_BYTES) {
+        throw new StateFileError('FILE_TOO_LARGE', `refusing to write "${filePath}": ${bytes} bytes exceeds the ${MAX_STATE_BYTES}-byte limit (see STATE-001); state was not modified.`);
+    }
+    return replaceFile(parent, STATE_FILE_NAME, serialized, {
+        mode: 0o600,
+        preserveMode: true,
+        durability: 'full',
+        maxBytes: MAX_STATE_BYTES,
+    }).warnings;
+}
+/** The write is already published; a throwing callback must not turn it into a failure. */
+function reportWarnings(warnings, onWarning) {
+    if (!onWarning)
+        return;
+    for (const w of warnings) {
+        try {
+            onWarning(w);
+        }
+        catch {
+            /* ignored on purpose */
+        }
+    }
+}
+/**
+ * Read-modify-write under an exclusive cross-process lock. `mutator`
+ * receives a deep-cloned draft of the current state and an `applyResult`
+ * callback to hand back an arbitrary value (e.g. the mission it just
+ * created) alongside the write. The revision is incremented exactly once
+ * per successful call, after the mutator returns.
+ */
+export async function mutateState(target, mutator, lockOptions) {
+    const { boundary, stateDir, onWarning } = resolveWriteTarget(target, 'mutateState');
+    const warnings = [];
+    // The instance's state directory may not exist yet (e.g. an existing
+    // project's first mission before any state.json has ever been written).
+    // Creating it here — component by component, refusing symlinks below the
+    // boundary — is the "safe, explicit initialization path" for that case; it
+    // never touches a state.json that already exists.
+    const parent = openParent(boundary, stateDir, { create: true });
+    const release = await acquireLock(lockFilePath(stateDir), lockOptions, {}, parent);
+    let draft;
+    let result;
+    try {
+        const current = await readStateForWrite(target, stateDir);
+        draft = structuredClone(current);
+        result = mutator(draft);
+        draft.revision = current.revision + 1;
+        warnings.push(...atomicWriteState(parent, stateFilePath(stateDir), draft));
+    }
+    finally {
+        release();
+    }
+    // The write is published and the lock is released: caller code runs outside
+    // the critical section, so a slow or re-entrant callback cannot hold up (or
+    // deadlock against) other writers.
+    reportWarnings(warnings, onWarning);
+    return { state: draft, result, warnings };
+}