@delegance/claude-autopilot 5.2.2 → 6.2.2

package/dist/src/core/run-state/state.d.ts

@@ -0,0 +1,40 @@
+import { type RunState, type WriterId } from './types.ts';
+/** Lowest `schema_version` value this binary can replay. Bump only on a
+ *  major release that drops support for a prior wire shape. */
+export declare const RUN_STATE_MIN_SUPPORTED_SCHEMA_VERSION: 1;
+/** Highest `schema_version` value this binary can replay. Always equal to
+ *  the writer's `RUN_STATE_SCHEMA_VERSION` — the writer never produces a
+ *  newer shape than the reader on the same binary. */
+export declare const RUN_STATE_MAX_SUPPORTED_SCHEMA_VERSION: 1;
+export declare function statePath(runDir: string): string;
+/** Write the snapshot atomically. Sequence:
+ *    open(tmp, 'w') → write → fsync(fd) → close → rename → fsync(dirfd).
+ *
+ *  If any step fails, the tmp file is best-effort-cleaned. The pre-existing
+ *  state.json is untouched until the rename, so a crash anywhere before
+ *  rename leaves the previous snapshot intact. */
+export declare function writeStateSnapshot(runDir: string, state: RunState): void;
+/** Read the snapshot. Returns null if missing. Throws GuardrailError(
+ *  corrupted_state) if it's present but unparseable — recoverState() handles
+ *  the fallback to events-replay. */
+export declare function readStateSnapshot(runDir: string): RunState | null;
+export interface RecoverStateOptions {
+    /** Writer that will own the recovery's `index.rebuilt` event. The
+     *  caller must already hold the run's advisory lock. */
+    writerId: WriterId;
+    /** runId override; defaults to basename(runDir). */
+    runId?: string;
+}
+export interface RecoverStateResult {
+    state: RunState;
+    /** True if recovery actually re-derived the snapshot (vs. just reading
+     *  a healthy one). */
+    recovered: boolean;
+    /** When `recovered === true`, the cause that triggered the rebuild. */
+    cause?: 'missing' | 'corrupt';
+}
+/** Open-or-recover the snapshot. If state.json is missing or corrupt, fall
+ *  back to events.ndjson replay, persist the result, and emit
+ *  `index.rebuilt`. The caller MUST already hold the advisory lock. */
+export declare function recoverState(runDir: string, opts: RecoverStateOptions): RecoverStateResult;
+//# sourceMappingURL=state.d.ts.map

package/dist/src/core/run-state/state.js

@@ -0,0 +1,164 @@
+// src/core/run-state/state.ts
+//
+// Atomic snapshot writer for state.json. Persistence protocol per spec:
+//   1. write to state.json.tmp
+//   2. fsync(file) on the tmp
+//   3. rename tmp → state.json
+//   4. fsync(dir) so the rename is durable
+//
+// readStateSnapshot() returns null if the snapshot is missing (the canonical
+// "fresh run" state) and throws if it's present-but-corrupt. recoverState()
+// is the resilience entry point — it falls back to events.ndjson replay if
+// the snapshot is unreadable, then rewrites a clean snapshot and emits an
+// `index.rebuilt` event.
+//
+// Spec: docs/specs/v6-run-state-engine.md "Persistence protocol — Durable
+// append", "Failure modes the user should never have to debug".
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { GuardrailError } from "../errors.js";
+import { appendEvent, replayState } from "./events.js";
+import { RUN_STATE_SCHEMA_VERSION } from "./types.js";
+// ---------------------------------------------------------------------------
+// v6.2.2 — cache contract version policy (per spec / codex WARNING #1).
+//
+// `replayState()` uses these bounds to reject run dirs whose `schema_version`
+// is outside the supported window. Strict equality would block resume across
+// rolling deploys / mixed binary fleets — the window allows additive minor
+// schema bumps to ship without breaking forward-read on older readers, and a
+// future major (v7) resets `MIN_SUPPORTED` to break with the past explicitly.
+// ---------------------------------------------------------------------------
+/** Lowest `schema_version` value this binary can replay. Bump only on a
+ *  major release that drops support for a prior wire shape. */
+export const RUN_STATE_MIN_SUPPORTED_SCHEMA_VERSION = 1;
+/** Highest `schema_version` value this binary can replay. Always equal to
+ *  the writer's `RUN_STATE_SCHEMA_VERSION` — the writer never produces a
+ *  newer shape than the reader on the same binary. */
+export const RUN_STATE_MAX_SUPPORTED_SCHEMA_VERSION = RUN_STATE_SCHEMA_VERSION;
+const STATE_FILE = 'state.json';
+const STATE_TMP = 'state.json.tmp';
+export function statePath(runDir) {
+    return path.join(runDir, STATE_FILE);
+}
+function tmpPath(runDir) {
+    return path.join(runDir, STATE_TMP);
+}
+/** Write the snapshot atomically. Sequence:
+ *    open(tmp, 'w') → write → fsync(fd) → close → rename → fsync(dirfd).
+ *
+ *  If any step fails, the tmp file is best-effort-cleaned. The pre-existing
+ *  state.json is untouched until the rename, so a crash anywhere before
+ *  rename leaves the previous snapshot intact. */
+export function writeStateSnapshot(runDir, state) {
+    fs.mkdirSync(runDir, { recursive: true });
+    const data = JSON.stringify(state, null, 2);
+    const tmp = tmpPath(runDir);
+    const target = statePath(runDir);
+    const fd = fs.openSync(tmp, 'w');
+    let wroteOk = false;
+    try {
+        fs.writeSync(fd, data);
+        fs.fsyncSync(fd);
+        wroteOk = true;
+    }
+    finally {
+        fs.closeSync(fd);
+        if (!wroteOk) {
+            try {
+                fs.unlinkSync(tmp);
+            }
+            catch { /* ignore */ }
+        }
+    }
+    fs.renameSync(tmp, target);
+    // fsync the parent directory so the rename is durable on power-loss.
+    // On Linux/macOS this is best-effort (ENOTSUP on some filesystems for
+    // dir fds); we swallow expected platform-specific failures so a
+    // working-directory on tmpfs / SMB / etc. doesn't break the writer.
+    try {
+        const dirFd = fs.openSync(runDir, 'r');
+        try {
+            fs.fsyncSync(dirFd);
+        }
+        finally {
+            fs.closeSync(dirFd);
+        }
+    }
+    catch (err) {
+        const code = err.code;
+        // EISDIR happens on some Windows configs where opening a dir for read
+        // isn't permitted; EPERM/ENOTSUP on certain FS. We don't escalate —
+        // the rename itself is atomic; dir-fsync is a defense-in-depth.
+        if (code !== 'EISDIR' && code !== 'EPERM' && code !== 'ENOTSUP') {
+            // Anything else, surface as warning via a thrown GuardrailError so
+            // callers can decide. We choose `corrupted_state` as the closest
+            // category since the snapshot may not have been durably committed.
+            throw new GuardrailError(`state.json: dir fsync failed: ${err.message}`, {
+                code: 'corrupted_state',
+                provider: 'run-state',
+                details: { runDir, errno: code },
+            });
+        }
+    }
+}
+/** Read the snapshot. Returns null if missing. Throws GuardrailError(
+ *  corrupted_state) if it's present but unparseable — recoverState() handles
+ *  the fallback to events-replay. */
+export function readStateSnapshot(runDir) {
+    const p = statePath(runDir);
+    if (!fs.existsSync(p))
+        return null;
+    const raw = fs.readFileSync(p, 'utf8');
+    if (!raw) {
+        throw new GuardrailError(`state.json: empty file`, {
+            code: 'corrupted_state',
+            provider: 'run-state',
+            details: { runDir },
+        });
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new GuardrailError(`state.json: corrupt JSON: ${err.message}`, {
+            code: 'corrupted_state',
+            provider: 'run-state',
+            details: { runDir, error: err.message },
+        });
+    }
+}
+/** Open-or-recover the snapshot. If state.json is missing or corrupt, fall
+ *  back to events.ndjson replay, persist the result, and emit
+ *  `index.rebuilt`. The caller MUST already hold the advisory lock. */
+export function recoverState(runDir, opts) {
+    let cause = null;
+    let snapshot = null;
+    try {
+        snapshot = readStateSnapshot(runDir);
+        if (!snapshot)
+            cause = 'missing';
+    }
+    catch (err) {
+        if (err instanceof GuardrailError && err.code === 'corrupted_state') {
+            cause = 'corrupt';
+        }
+        else {
+            throw err;
+        }
+    }
+    if (!cause && snapshot) {
+        return { state: snapshot, recovered: false };
+    }
+    // Recovery path. Replay first, then persist, then emit event in that
+    // order — emitting the event before persisting would leave a record of
+    // a recovery that didn't actually land if we crash between the two.
+    const replayed = replayState(runDir);
+    writeStateSnapshot(runDir, replayed);
+    appendEvent(runDir, { event: 'index.rebuilt', cause: cause }, { writerId: opts.writerId, ...(opts.runId !== undefined ? { runId: opts.runId } : {}) });
+    return {
+        state: replayed,
+        recovered: true,
+        cause: cause,
+    };
+}
+//# sourceMappingURL=state.js.map

package/dist/src/core/run-state/types.d.ts

@@ -0,0 +1,278 @@
+/** Schema version for everything written by this engine. Bump on breaking
+ *  changes to RunState / RunEvent / PhaseSnapshot shape. */
+export declare const RUN_STATE_SCHEMA_VERSION: 1;
+export type SchemaVersion = typeof RUN_STATE_SCHEMA_VERSION;
+/** Identifies a single OS-level writer. PID + a hash of the hostname (we
+ *  don't persist the raw hostname to the lock metadata so co-tenant signal
+ *  doesn't leak between users sharing a directory). */
+export interface WriterId {
+    pid: number;
+    hostHash: string;
+}
+/** Top-level run status, mirroring the lifecycle diagram in the spec. */
+export type RunStatus = 'pending' | 'running' | 'paused' | 'success' | 'failed' | 'aborted';
+/** Per-phase status within a run. */
+export type PhaseStatus = 'pending' | 'running' | 'succeeded' | 'failed' | 'skipped' | 'aborted';
+/** External operation reference — the persisted breadcrumb that makes replay
+ *  decisions deterministic. Used heavily in Phase 6 (idempotency contracts);
+ *  typed now so events can carry it without later schema churn.
+ *
+ *  v6.2.1 — `migration-batch` joins the union as the side-effect contract's
+ *  PRE-effect breadcrumb for the `migrate` phase. Semantics: a deterministic
+ *  id covers a planned migration batch and is emitted BEFORE the dispatcher
+ *  is invoked, so a partial crash leaves a resume target visible to the
+ *  orchestrator's preflight readback. The post-effect `migration-version`
+ *  refs (one per actually-applied migration) remain authoritative for
+ *  reconciliation; `migration-batch` exists purely so resume can tell
+ *  "we started this batch but didn't finish" apart from "we never started." */
+export type ExternalRefKind = 'github-pr' | 'github-comment' | 'git-remote-push' | 'deploy' | 'migration-batch' | 'migration-version' | 'rollback-target' | 'spec-file' | 'plan-file' | 'sarif-artifact' | 'review-comments';
+export interface ExternalRef {
+    kind: ExternalRefKind;
+    /** Provider-specific identifier (PR number, commit SHA, deploy ID, …). */
+    id: string;
+    provider?: string;
+    /** Human-readable artifact link if the provider exposes one. */
+    url?: string;
+    /** ISO timestamp of the platform's confirmation. */
+    observedAt: string;
+}
+/** Per-phase artifact pointer recorded inside the snapshot. */
+export interface PhaseArtifactRef {
+    /** Logical name (e.g. "spec", "plan", "impl-diff"). */
+    name: string;
+    /** Path inside `artifacts/` (relative to run dir). */
+    path: string;
+    sha256?: string;
+    size?: number;
+    copiedAt?: string;
+}
+/** Snapshot of a single phase, persisted under `phases/<name>.json` and
+ *  reflected inside state.json's `phases[]`. */
+export interface PhaseSnapshot {
+    schema_version: SchemaVersion;
+    name: string;
+    /** Order within the run (0-indexed). */
+    index: number;
+    status: PhaseStatus;
+    /** True iff `RunPhase.idempotent` was declared true at registration. */
+    idempotent: boolean;
+    /** True iff `RunPhase.hasSideEffects` was declared true at registration. */
+    hasSideEffects: boolean;
+    startedAt?: string;
+    endedAt?: string;
+    durationMs?: number;
+    /** Sum of `phase.cost` events for this phase. */
+    costUSD: number;
+    attempts: number;
+    /** Last failure message (string) if status === 'failed'. */
+    lastError?: string;
+    artifacts: PhaseArtifactRef[];
+    externalRefs: ExternalRef[];
+    /** Phase-specific metadata. Free-form; engine doesn't introspect. */
+    meta?: Record<string, unknown>;
+    /** Phase 6 — last successful output, persisted so a future
+     *  `skip-already-applied` decision can return it without re-execution.
+     *  The engine writes this on every `phase.success`; absent on failed
+     *  / pre-Phase-6 snapshots. JSON-serializable values only. */
+    result?: unknown;
+}
+/** The state.json checkpoint. Authoritative answer is always
+ *  events.ndjson; this is a derived snapshot for O(1) status queries. */
+export interface RunState {
+    schema_version: SchemaVersion;
+    runId: string;
+    /** ULID generation time, ISO. */
+    startedAt: string;
+    endedAt?: string;
+    status: RunStatus;
+    /** Phase order is fixed at run creation. */
+    phases: PhaseSnapshot[];
+    /** Index into `phases[]` of the currently-running or last-attempted phase. */
+    currentPhaseIdx: number;
+    /** Sum of phase.cost events across the whole run. */
+    totalCostUSD: number;
+    /** Last seq written to events.ndjson at the time of the snapshot. */
+    lastEventSeq: number;
+    /** The writer that wrote this snapshot. */
+    writerId: WriterId;
+    /** Working directory the run was started in (absolute path). */
+    cwd: string;
+    /** Snapshot of the run config at creation (subset of guardrail.config.yaml).
+     *  Free-form; engine doesn't introspect here, later phases do. */
+    config?: Record<string, unknown>;
+}
+/** Universal envelope on every event line. */
+export interface RunEventBase {
+    schema_version: SchemaVersion;
+    /** ISO timestamp. */
+    ts: string;
+    runId: string;
+    /** Monotonic per-run sequence. Receivers MUST detect gaps. */
+    seq: number;
+    /** The writer that appended this event. */
+    writerId: WriterId;
+}
+export interface RunStartEvent extends RunEventBase {
+    event: 'run.start';
+    phases: string[];
+    config?: Record<string, unknown>;
+}
+export interface RunCompleteEvent extends RunEventBase {
+    event: 'run.complete';
+    status: 'success' | 'failed' | 'aborted';
+    totalCostUSD: number;
+    durationMs: number;
+}
+export interface RunWarningEvent extends RunEventBase {
+    event: 'run.warning';
+    message: string;
+    details?: Record<string, unknown>;
+}
+export interface RunRecoveryEvent extends RunEventBase {
+    event: 'run.recovery';
+    reason: 'recovered-from-partial-write' | 'recovered-from-corrupt-snapshot' | 'recovered-from-missing-snapshot';
+    details?: Record<string, unknown>;
+}
+export interface PhaseStartEvent extends RunEventBase {
+    event: 'phase.start';
+    phase: string;
+    phaseIdx: number;
+    idempotent: boolean;
+    hasSideEffects: boolean;
+    /** Attempt counter, 1-based. >1 implies a resume / retry. */
+    attempt: number;
+}
+export interface PhaseSuccessEvent extends RunEventBase {
+    event: 'phase.success';
+    phase: string;
+    phaseIdx: number;
+    durationMs: number;
+    artifacts: PhaseArtifactRef[];
+}
+export interface PhaseFailedEvent extends RunEventBase {
+    event: 'phase.failed';
+    phase: string;
+    phaseIdx: number;
+    durationMs: number;
+    /** Stringified error message. Stack traces stay out of the durable log. */
+    error: string;
+    /** Optional structured error code (matches GuardrailError.code if thrown). */
+    errorCode?: string;
+}
+export interface PhaseAbortedEvent extends RunEventBase {
+    event: 'phase.aborted';
+    phase: string;
+    phaseIdx: number;
+    reason: 'user-interrupt' | 'budget-exceeded' | 'lock-takeover' | 'crash';
+}
+export interface PhaseCostEvent extends RunEventBase {
+    event: 'phase.cost';
+    phase: string;
+    phaseIdx: number;
+    provider: string;
+    inputTokens: number;
+    outputTokens: number;
+    costUSD: number;
+}
+export interface PhaseExternalRefEvent extends RunEventBase {
+    event: 'phase.externalRef';
+    phase: string;
+    phaseIdx: number;
+    ref: ExternalRef;
+}
+export interface PhaseNeedsHumanEvent extends RunEventBase {
+    event: 'phase.needs-human';
+    phase: string;
+    phaseIdx: number;
+    reason: string;
+    /** Hint surfaced to the user / CI consumer. */
+    nextActions?: string[];
+}
+export interface LockTakeoverEvent extends RunEventBase {
+    event: 'lock.takeover';
+    /** Identity of the writer who previously held the lock (best-effort —
+     *  may be null if metadata was missing). */
+    previousWriter: WriterId | null;
+    reason: string;
+}
+export interface IndexRebuiltEvent extends RunEventBase {
+    event: 'index.rebuilt';
+    /** Why the rebuild was needed: "missing", "corrupt", or "force". */
+    cause: 'missing' | 'corrupt' | 'force';
+}
+/** Phase 4 — budget enforcement preflight. Emitted by `runPhase` BEFORE
+ *  `phase.start` for every phase whose parent run carries a `BudgetConfig`.
+ *  Carries the full `BudgetCheck` payload from `checkPhaseBudget` so
+ *  consumers (cost dashboards, CI) can attribute spend and decisions
+ *  without re-running the policy. Per the v6 spec "Budget enforcement"
+ *  section + Codex CRITICAL #3 (two-layer guard, layer 2 always runs). */
+export interface BudgetCheckEvent extends RunEventBase {
+    event: 'budget.check';
+    phase: string;
+    phaseIdx: number;
+    decision: 'proceed' | 'pause' | 'hard-fail';
+    /** `estimate.high` from `RunPhase.estimateCost` if it returned a value;
+     *  null when the phase doesn't implement estimateCost. Layer 2 (the
+     *  mandatory floor) ALWAYS runs regardless. */
+    estimatedHigh: number | null;
+    /** Sum of every prior `phase.cost` event in this run, in USD. */
+    actualSoFar: number;
+    /** The reserve the runner deducted against `perRunUSD` for this phase
+     *  (Layer 2 floor, expressed in USD). */
+    reserveApplied: number;
+    /** USD remaining under `perRunUSD` after `actualSoFar` + the larger of
+     *  `estimatedHigh` and `reserveApplied`. May be negative on hard-fail. */
+    capRemaining: number;
+    reason: string;
+    /** v6.2.0 — which scope produced the decision. `'phase'` (legacy
+     *  default) is the single-phase wrapper path; `'run'` is the
+     *  orchestrator's cross-phase mode. Optional only for back-compat
+     *  with older events.ndjson files; events emitted on v6.2.0+ always
+     *  carry a value. */
+    scope?: 'phase' | 'run';
+}
+/** Phase 6 — emitted when a `forceReplay` override flips a needs-human (or
+ *  any other refusal) into a retry. Carries the phase and the refs that
+ *  WERE consulted so the durable log shows exactly what was overridden.
+ *  Spec: "a `--force-replay` override writes an explicit `replay.override`
+ *  event with user-supplied reason." */
+export interface ReplayOverrideEvent extends RunEventBase {
+    event: 'replay.override';
+    phase: string;
+    phaseIdx: number;
+    /** Free-form user / CI reason for the override. */
+    reason: string;
+    /** Refs the underlying refusal cited (echoed for triage). */
+    refsConsulted: ExternalRef[];
+}
+/** Discriminated union of every event variant. Add new variants here and
+ *  the code that switches over `event` will type-error at compile time. */
+export type RunEvent = RunStartEvent | RunCompleteEvent | RunWarningEvent | RunRecoveryEvent | PhaseStartEvent | PhaseSuccessEvent | PhaseFailedEvent | PhaseAbortedEvent | PhaseCostEvent | PhaseExternalRefEvent | PhaseNeedsHumanEvent | LockTakeoverEvent | IndexRebuiltEvent | BudgetCheckEvent | ReplayOverrideEvent;
+/** Distributive Omit so the discriminated-union shape is preserved when we
+ *  strip the fields the appender fills in. Plain `Omit<RunEvent, ...>`
+ *  collapses the union into a single intersection and loses variant-specific
+ *  fields — so a literal `{ event: 'phase.cost', costUSD: 1, ... }` would
+ *  fail typecheck. */
+type DistributiveOmit<T, K extends keyof T> = T extends unknown ? Omit<T, K> : never;
+/** When appending we don't know `seq`, `ts`, `runId`, `schema_version`,
+ *  or `writerId` yet — the appender supplies them. */
+export type RunEventInput = DistributiveOmit<RunEvent, 'seq' | 'ts' | 'runId' | 'schema_version' | 'writerId'>;
+export interface RunIndexEntry {
+    runId: string;
+    status: RunStatus;
+    startedAt: string;
+    endedAt?: string;
+    totalCostUSD: number;
+    /** Last completed phase name (for `runs list` summary). */
+    lastPhase?: string;
+    /** True if state.json was synthesized via replay because it was missing
+     *  or corrupt at last open. Surfaces as a warning in the UI. */
+    recovered?: boolean;
+}
+export interface RunIndex {
+    schema_version: SchemaVersion;
+    /** Newest first. */
+    runs: RunIndexEntry[];
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/src/core/run-state/types.js

@@ -0,0 +1,13 @@
+// src/core/run-state/types.ts
+//
+// v6 Run State Engine — pure data layer types. Phase 1 (persistence) only.
+// Behavior — phase wrapping, CLI verbs, budget enforcement, etc. — lands in
+// later phases. The shapes here are versioned via `schema_version: 1` so a
+// future migration can detect and migrate older runs.
+//
+// Spec: docs/specs/v6-run-state-engine.md ("State on disk", "Run lifecycle",
+// "Idempotency rules + external operation ledger", "Persistence protocol").
+/** Schema version for everything written by this engine. Bump on breaking
+ *  changes to RunState / RunEvent / PhaseSnapshot shape. */
+export const RUN_STATE_SCHEMA_VERSION = 1;
+//# sourceMappingURL=types.js.map

package/dist/src/core/run-state/ulid.d.ts

@@ -0,0 +1,11 @@
+/** Validate that a string matches the ULID shape (length + alphabet). */
+export declare function isValidULID(s: string): boolean;
+/** Generate a new ULID. Optionally pass a fixed `now` (ms epoch) for tests. */
+export declare function ulid(now?: number): string;
+/** Decode the timestamp-portion of a ULID back to ms epoch. Throws on
+ *  malformed input. Useful for `runs list` ordering and for tests. */
+export declare function decodeTime(id: string): number;
+/** Exposed for tests that want to verify alphabet membership. */
+export declare const ULID_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+export declare const ULID_LENGTH: number;
+//# sourceMappingURL=ulid.d.ts.map

package/dist/src/core/run-state/ulid.js

@@ -0,0 +1,95 @@
+// src/core/run-state/ulid.ts
+//
+// Tiny pure-TS ULID generator. We deliberately avoid pulling in the `ulid`
+// npm package — the algorithm is short and the runtime dep budget for the
+// engine is tight. Conforms to https://github.com/ulid/spec :
+//
+//   - 26 characters, Crockford's Base32 (no I, L, O, U).
+//   - First 10 chars  = 48-bit Unix-millisecond timestamp (ms since epoch).
+//   - Last 16 chars   = 80 bits of randomness (crypto.randomBytes).
+//   - Lexicographic sort == chronological sort (within ms; tie-break is
+//     random within the same ms — Phase 1 does not implement the optional
+//     monotonic-overflow within-ms behavior, since runIDs are issued by a
+//     single writer and one-per-millisecond is unreachable in practice).
+//   - URL-safe (Crockford Base32 only emits [0-9A-Z]).
+import { randomBytes } from 'node:crypto';
+const ENCODING = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'; // Crockford Base32 alphabet (32 chars).
+const ENCODING_LEN = ENCODING.length; // 32.
+const TIME_LEN = 10;
+const RANDOM_LEN = 16;
+const ULID_LEN = TIME_LEN + RANDOM_LEN; // 26.
+/** Max representable timestamp = 2^48 - 1 ms. Sanity-check, not a bug
+ *  most callers will hit (it's the year 10889). */
+const TIME_MAX = 281474976710655;
+/** Validate that a string matches the ULID shape (length + alphabet). */
+export function isValidULID(s) {
+    if (typeof s !== 'string')
+        return false;
+    if (s.length !== ULID_LEN)
+        return false;
+    for (let i = 0; i < ULID_LEN; i++) {
+        if (ENCODING.indexOf(s[i]) < 0)
+            return false;
+    }
+    return true;
+}
+function encodeTime(now) {
+    if (!Number.isFinite(now) || now < 0 || now > TIME_MAX) {
+        throw new RangeError(`ulid: timestamp out of range (got ${now})`);
+    }
+    let out = '';
+    let t = now;
+    for (let i = TIME_LEN - 1; i >= 0; i--) {
+        const mod = t % ENCODING_LEN;
+        out = ENCODING[mod] + out;
+        t = (t - mod) / ENCODING_LEN;
+    }
+    return out;
+}
+function encodeRandom() {
+    // 16 chars * 5 bits each = 80 bits. We draw 10 bytes (80 bits) of
+    // crypto-grade randomness and encode 5 bits at a time. Any extra fractional
+    // bits are discarded — this is the standard ULID approach.
+    const bytes = randomBytes(10);
+    // Pack the 10 bytes into a 80-bit unsigned integer view, 5-bit chunks.
+    // We do it manually rather than using BigInt for portability — the array
+    // is short enough that the explicit math is just as fast and avoids any
+    // dependency on BigInt-typed regression in older runtimes.
+    const bits = new Array(80);
+    for (let i = 0; i < 10; i++) {
+        const b = bytes[i];
+        for (let j = 0; j < 8; j++) {
+            bits[i * 8 + j] = (b >> (7 - j)) & 1;
+        }
+    }
+    let out = '';
+    for (let i = 0; i < RANDOM_LEN; i++) {
+        let v = 0;
+        for (let j = 0; j < 5; j++) {
+            v = (v << 1) | bits[i * 5 + j];
+        }
+        out += ENCODING[v];
+    }
+    return out;
+}
+/** Generate a new ULID. Optionally pass a fixed `now` (ms epoch) for tests. */
+export function ulid(now = Date.now()) {
+    return encodeTime(now) + encodeRandom();
+}
+/** Decode the timestamp-portion of a ULID back to ms epoch. Throws on
+ *  malformed input. Useful for `runs list` ordering and for tests. */
+export function decodeTime(id) {
+    if (!isValidULID(id)) {
+        throw new Error(`ulid: not a valid ULID: ${String(id)}`);
+    }
+    let t = 0;
+    for (let i = 0; i < TIME_LEN; i++) {
+        const idx = ENCODING.indexOf(id[i]);
+        t = t * ENCODING_LEN + idx;
+    }
+    return t;
+}
+/** Exposed for tests that want to verify alphabet membership. */
+export const ULID_ALPHABET = ENCODING;
+export const ULID_LENGTH = ULID_LEN;
+//# sourceMappingURL=ulid.js.map

package/dist/src/core/schema-alignment/extractor/index.d.ts

@@ -1,3 +1,3 @@
 import type { SchemaEntity } from '../types.ts';
-export declare function extract(filePath: string): SchemaEntity[];
+export declare function extract(filePath: string, previousContent?: string | null): SchemaEntity[];
 //# sourceMappingURL=index.d.ts.map

package/dist/src/core/schema-alignment/extractor/index.js

@@ -3,7 +3,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { extractFromSql } from "./sql.js";
 import { extractFromPrisma } from "./prisma.js";
-export function extract(filePath) {
+export function extract(filePath, previousContent) {
     let content;
     try {
         content = fs.readFileSync(filePath, 'utf8');
@@ -16,7 +16,7 @@ export function extract(filePath) {
     if (ext === '.sql')
         return extractFromSql(content);
     if (base === 'schema.prisma' || ext === '.prisma')
-        return extractFromPrisma(content);
+        return extractFromPrisma(content, previousContent);
     process.stderr.write(`[schema-alignment] no extractor for ${ext} files — skipping ${path.basename(filePath)}\n`);
     return [];
 }

package/dist/src/core/schema-alignment/extractor/prisma.d.ts

@@ -1,3 +1,15 @@
 import type { SchemaEntity } from '../types.ts';
-export declare function extractFromPrisma(content: string): SchemaEntity[];
+/**
+ * Extract schema entities from a Prisma schema file.
+ *
+ * When `previousContent` is provided, only the diff (added/removed fields,
+ * new/dropped tables) is emitted — this avoids over-reporting when a user
+ * touches schema.prisma for any reason (adding one field, editing a comment)
+ * and every long-existing field gets re-checked against type/API/UI layers.
+ *
+ * When `previousContent` is null/undefined, every model and field is emitted
+ * — the original "all entities are new" behavior used as a fallback when git
+ * history isn't available.
+ */
+export declare function extractFromPrisma(content: string, previousContent?: string | null): SchemaEntity[];
 //# sourceMappingURL=prisma.d.ts.map