@substrate-ai/sdlc 0.19.54

package/dist/run-model/recovery-history.js

@@ -0,0 +1,83 @@
+/**
+ * RecoveryEntry and CostAccumulation schemas — Story 52-8.
+ *
+ * Provides Zod schemas and TypeScript types for recovery history and cost
+ * accumulation data stored in the run manifest. Consumed by Epic 53 cost
+ * governance and Epic 54 recovery engine.
+ */
+import { z } from 'zod';
+// ---------------------------------------------------------------------------
+// RecoveryOutcome
+// ---------------------------------------------------------------------------
+/**
+ * Outcome of a recovery attempt.
+ *
+ * The string fallback must be last in the union so Zod evaluates the literal
+ * variants first — a leading z.string() would swallow all literals. This
+ * follows the v0.19.6 extensible union pattern used throughout the codebase.
+ */
+export const RecoveryOutcomeSchema = z.union([
+    z.literal('retried'),
+    z.literal('escalated'),
+    z.literal('skipped'),
+    z.string(), // extensible fallback — must be last (v0.19.6 pattern)
+]);
+// ---------------------------------------------------------------------------
+// RecoveryEntry
+// ---------------------------------------------------------------------------
+/**
+ * A single recovery attempt recorded in the run manifest.
+ *
+ * `attempt_number` is 1-indexed: 1 = first retry, NOT the initial dispatch.
+ * The initial dispatch of a story is never recorded as a RecoveryEntry.
+ *
+ * `strategy` is free-form (e.g., `'retry-with-context'`, `'re-scope'`).
+ *
+ * `cost_usd` is the cost of THIS single retry attempt only — NOT cumulative.
+ * Cumulative per-story retry cost is tracked in `CostAccumulation.per_story`.
+ */
+export const RecoveryEntrySchema = z.object({
+    /** Story key that triggered this recovery attempt (e.g. '52-8'). */
+    story_key: z.string(),
+    /** 1-indexed attempt number — 1 = first retry, not initial dispatch. */
+    attempt_number: z.number().int().nonnegative(),
+    /** Recovery strategy applied (e.g., 'retry-with-context', 're-scope'). */
+    strategy: z.string(),
+    /** Root cause classification string (informational, for completion report). */
+    root_cause: z.string(),
+    /** Outcome of this recovery attempt. */
+    outcome: RecoveryOutcomeSchema,
+    /** Cost of this single retry attempt in USD (NOT cumulative). */
+    cost_usd: z.number().nonnegative(),
+    /** ISO-8601 timestamp when this recovery was initiated. */
+    timestamp: z.string(),
+});
+// ---------------------------------------------------------------------------
+// CostAccumulation
+// ---------------------------------------------------------------------------
+/**
+ * Accumulated retry cost data for a pipeline run.
+ *
+ * `per_story` maps story_key → sum of all RecoveryEntry.cost_usd for that
+ * story. It does NOT include the initial dispatch cost, which is tracked in
+ * `PerStoryState.cost_usd`.
+ *
+ * `run_total` is the sum of all RecoveryEntry.cost_usd values in the run
+ * (i.e., total retry cost only, not total run cost).
+ *
+ * An empty `{ per_story: {}, run_total: 0 }` is the valid initial value.
+ */
+export const CostAccumulationSchema = z.object({
+    /**
+     * Per-story cumulative retry cost in USD.
+     * Maps story_key → sum of all RecoveryEntry.cost_usd for that story.
+     * Does NOT include the initial dispatch cost (tracked in PerStoryState.cost_usd).
+     */
+    per_story: z.record(z.string(), z.number().nonnegative()),
+    /**
+     * Total retry cost for the entire run in USD.
+     * Equal to sum of all RecoveryEntry.cost_usd values.
+     */
+    run_total: z.number().nonnegative(),
+});
+//# sourceMappingURL=recovery-history.js.map

package/dist/run-model/recovery-history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery-history.js","sourceRoot":"","sources":["../../src/run-model/recovery-history.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC;IAC3C,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;IACpB,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC;IACtB,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;IACpB,CAAC,CAAC,MAAM,EAAE,EAAE,uDAAuD;CACpE,CAAC,CAAA;AAIF,8EAA8E;AAC9E,gBAAgB;AAChB,8EAA8E;AAE9E;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,oEAAoE;IACpE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,wEAAwE;IACxE,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC9C,0EAA0E;IAC1E,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,+EAA+E;IAC/E,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,wCAAwC;IACxC,OAAO,EAAE,qBAAqB;IAC9B,iEAAiE;IACjE,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE;IAClC,2DAA2D;IAC3D,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;CACtB,CAAC,CAAA;AAIF,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C;;;;OAIG;IACH,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE,CAAC;IACzD;;;OAGG;IACH,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE;CACpC,CAAC,CAAA"}

package/dist/run-model/run-manifest.d.ts

@@ -0,0 +1,146 @@
+/**
+ * RunManifest — atomic file-backed run state — Story 52-1.
+ *
+ * Provides typed read/write operations with atomic file replacement
+ * so run state survives process crashes without corruption.
+ *
+ * File layout (relative to baseDir):
+ *   {run-id}.json      — primary manifest
+ *   {run-id}.json.bak  — backup written before rename
+ *   {run-id}.json.tmp  — temporary write target (fsync'd before rename)
+ */
+import type { RunManifestData } from './types.js';
+import type { RecoveryEntry } from './recovery-history.js';
+import type { CliFlags } from './cli-flags.js';
+import type { PerStoryState } from './per-story-state.js';
+/**
+ * Minimal interface for Dolt query access needed by the degraded-mode fallback.
+ * Consumers inject a real `DatabaseAdapter` (from @substrate-ai/core) or null.
+ */
+export interface IDoltAdapter {
+    query<T = unknown>(sql: string, params?: unknown[]): Promise<T[]>;
+}
+/**
+ * Typed, atomic file-backed run manifest.
+ *
+ * Each instance is bound to a specific run ID and base directory.
+ * Use `RunManifest.create()` to initialize a new manifest,
+ * or `RunManifest.read()` to load an existing one.
+ */
+export declare class RunManifest {
+    readonly runId: string;
+    readonly baseDir: string;
+    /** Optional Dolt adapter for degraded-mode fallback on read. */
+    private doltAdapter;
+    constructor(runId: string, baseDir?: string, doltAdapter?: IDoltAdapter | null);
+    get primaryPath(): string;
+    get bakPath(): string;
+    get tmpPath(): string;
+    /**
+     * Read this manifest from disk (multi-tier fallback).
+     *
+     * Delegates to `RunManifest.read()` with this instance's runId, baseDir,
+     * and doltAdapter. Primarily used by `SupervisorLock` (and tests that mock it).
+     *
+     * @throws ManifestReadError if all sources fail
+     */
+    read(): Promise<RunManifestData>;
+    /**
+     * Atomically update specific fields in the manifest.
+     *
+     * Reads the current manifest, merges in the provided partial data (shallow
+     * merge), then writes the result atomically. Generation is incremented and
+     * `updated_at` is refreshed by `write()`.
+     *
+     * Callers should pass only the fields they intend to change. Do NOT use this
+     * to change `run_id` or `created_at` — those are immutable after creation.
+     *
+     * @throws ManifestReadError if the current manifest cannot be read
+     */
+    update(partial: Partial<Omit<RunManifestData, 'generation' | 'updated_at'>>): Promise<void>;
+    /**
+     * Atomically write the manifest to disk.
+     *
+     * Sequence:
+     *   1. Auto-increment `generation`, set `updated_at`
+     *   2. Serialize to JSON and validate round-trip
+     *   3. Ensure baseDir exists (mkdir -p)
+     *   4. Write to `.tmp` via open → write → datasync → close (fsync)
+     *   5. If primary exists, copy to `.bak`
+     *   6. Rename `.tmp` → primary path
+     */
+    write(data: Omit<RunManifestData, 'generation' | 'updated_at'>): Promise<void>;
+    /**
+     * Return a bound `RunManifest` instance without performing any file I/O.
+     *
+     * Use `open()` when you want to call instance methods (`read()`, `patchCLIFlags()`)
+     * on an existing run without reading the manifest upfront.
+     *
+     * ```typescript
+     * await RunManifest.open(runId, runsDir).patchCLIFlags(cliFlags)
+     * ```
+     */
+    static open(runId: string, baseDir?: string, doltAdapter?: IDoltAdapter | null): RunManifest;
+    /**
+     * Read the current manifest (or create a minimal default), merge the provided
+     * CLI flags into `cli_flags`, and write the result atomically.
+     *
+     * Non-fatal: callers should wrap in try/catch and log a warning on failure.
+     * The pipeline must not abort if manifest write fails.
+     */
+    patchCLIFlags(flags: CliFlags): Promise<void>;
+    /**
+     * Atomically upsert the per-story lifecycle state for a single story key.
+     *
+     * Reads the current manifest (or creates a minimal default if absent),
+     * shallowly merges `updates` into `per_story_state[storyKey]`, and writes
+     * the result atomically via a single `write()` call.
+     *
+     * Fields not included in `updates` on an existing entry are preserved unchanged.
+     *
+     * Non-fatal: callers MUST wrap in `.catch((err) => logger.warn(...))`.
+     * The pipeline must never abort due to a manifest write failure.
+     *
+     * @param storyKey - Story key (e.g. '52-4')
+     * @param updates  - Partial PerStoryState fields to merge
+     */
+    patchStoryState(storyKey: string, updates: Partial<PerStoryState>): Promise<void>;
+    /**
+     * Atomically append a recovery entry and update cost accumulation.
+     *
+     * Reads the current manifest, appends `entry` to `recovery_history[]`,
+     * increments `cost_accumulation.per_story[entry.story_key]` by `entry.cost_usd`,
+     * increments `cost_accumulation.run_total` by `entry.cost_usd`, then writes
+     * atomically via a single `write()` call.
+     *
+     * Non-fatal: callers MUST wrap in `.catch((err) => logger.warn(...))`.
+     * The pipeline must never abort due to a manifest write failure.
+     *
+     * `entry.cost_usd` is the cost of this single retry attempt only (NOT cumulative).
+     * Cumulative per-story retry cost is tracked in `cost_accumulation.per_story`.
+     *
+     * @param entry - Recovery entry to append (attempt_number is 1-indexed)
+     */
+    appendRecoveryEntry(entry: RecoveryEntry): Promise<void>;
+    /**
+     * Create a new manifest with `generation: 0` and write it.
+     * Returns a bound `RunManifest` instance.
+     */
+    static create(runId: string, initialData: Omit<RunManifestData, 'generation' | 'updated_at' | 'created_at'>, baseDir?: string, doltAdapter?: IDoltAdapter | null): Promise<RunManifest>;
+    /**
+     * Read a manifest from disk with multi-tier fallback.
+     *
+     * Attempts sources in order:
+     *   1. Primary `.json`
+     *   2. Backup `.json.bak`  (preferred over primary if generation is higher)
+     *   3. Temporary `.json.tmp`
+     *   4. Dolt degraded reconstruction (if doltAdapter is provided)
+     *
+     * Generation tiebreak: if `.bak` has a higher `generation` than primary,
+     * `.bak` is preferred (indicates primary was overwritten mid-rename).
+     *
+     * @throws ManifestReadError if all sources fail
+     */
+    static read(runId: string, baseDir?: string, doltAdapter?: IDoltAdapter | null): Promise<RunManifestData>;
+}
+//# sourceMappingURL=run-manifest.d.ts.map

package/dist/run-model/run-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-manifest.d.ts","sourceRoot":"","sources":["../../src/run-model/run-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAY,MAAM,YAAY,CAAA;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAE1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAC9C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAMzD;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAA;CAClE;AA6GD;;;;;;GAMG;AACH,qBAAa,WAAW;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IAExB,gEAAgE;IAChE,OAAO,CAAC,WAAW,CAAqB;gBAE5B,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,MAAyB,EAAE,WAAW,GAAE,YAAY,GAAG,IAAW;IAUtG,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,IAAI,OAAO,IAAI,MAAM,CAEpB;IAMD;;;;;;;OAOG;IACG,IAAI,IAAI,OAAO,CAAC,eAAe,CAAC;IAQtC;;;;;;;;;;;OAWG;IACG,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,eAAe,EAAE,YAAY,GAAG,YAAY,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAajG;;;;;;;;;;OAUG;IACG,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,eAAe,EAAE,YAAY,GAAG,YAAY,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IA+CpF;;;;;;;;;OASG;IACH,MAAM,CAAC,IAAI,CACT,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,MAAyB,EAClC,WAAW,GAAE,YAAY,GAAG,IAAW,GACtC,WAAW;IAQd;;;;;;OAMG;IACG,aAAa,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAmCnD;;;;;;;;;;;;;;OAcG;IACG,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAuDvF;;;;;;;;;;;;;;;OAeG;IACG,mBAAmB,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IA4C9D;;;OAGG;WACU,MAAM,CACjB,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,IAAI,CAAC,eAAe,EAAE,YAAY,GAAG,YAAY,GAAG,YAAY,CAAC,EAC9E,OAAO,GAAE,MAAyB,EAClC,WAAW,GAAE,YAAY,GAAG,IAAW,GACtC,OAAO,CAAC,WAAW,CAAC;IAiBvB;;;;;;;;;;;;;OAaG;WACU,IAAI,CACf,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,MAAyB,EAClC,WAAW,GAAE,YAAY,GAAG,IAAW,GACtC,OAAO,CAAC,eAAe,CAAC;CA0D5B"}