@schnick371/devsteps-shared 1.1.0-next.4 → 2.0.0-next.1

package/dist/runtime/run-catalog.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Run catalog
+ * Reads the runs index (`.devsteps/runs/index.json`) and validated runs per definition without
+ * changing store files; falls back to bounded directory discovery when the index is missing.
+ */
+import { type ProcessEventRepair } from './event-log.js';
+import { type ProcessEvent, ProcessRun } from './index.js';
+export type StoredRunEvidence = Readonly<{
+    run: ProcessRun;
+    events: readonly ProcessEvent[];
+}>;
+export type RunEvidenceDiagnostic = Readonly<{
+    kind: 'run-index-missing' | 'run-index-truncated' | 'inaccessible-run' | 'malformed-snapshot' | 'malformed-events' | 'contradictory-run';
+    message: string;
+    run_id?: string;
+    definition_id?: string;
+}>;
+export type RunEvidenceResult = Readonly<{
+    runs: readonly StoredRunEvidence[];
+    diagnostics: readonly RunEvidenceDiagnostic[];
+    candidates_read: number;
+}>;
+export type RunCatalogEntry = Readonly<{
+    run_id: string;
+    process_type: string;
+    definition_id: string;
+    updated_at: string;
+    state: string;
+    terminal: boolean;
+    path: string;
+    /** Present on entries written since the v2 runtime: definition schema, run version, verdict. */
+    schema_version?: string;
+    version?: number;
+    verdict?: string | null;
+}>;
+export type RunCatalog = Readonly<{
+    version: 1;
+    runs: readonly RunCatalogEntry[];
+}>;
+/** Read validated runs for definitions without creating or changing store files. */
+export declare function readRunsByDefinition(rootPath: string, definitionIds: ReadonlySet<string>, limit?: number, candidateLimit?: number): Promise<RunEvidenceResult>;
+export declare function catalogEntry(rootPath: string, run: ProcessRun, runPath: string): RunCatalogEntry;
+export declare function parseRunCatalog(value: unknown): RunCatalog;
+/** Every catalog entry, newest first; an absent index is an empty catalog. */
+export declare function readRunCatalog(rootPath: string): Promise<RunCatalogEntry[]>;
+export type LocatedRun = Readonly<{
+    entry?: RunCatalogEntry;
+    path: string;
+    run: ProcessRun;
+    events: readonly ProcessEvent[];
+}>;
+/** Find one run by id through the catalog, or by scanning process directories when it is absent. */
+export declare function readRunById(rootPath: string, runId: string): Promise<LocatedRun>;
+export type LoadedRunDir = Readonly<{
+    path: string;
+    run: ProcessRun;
+    events: readonly ProcessEvent[];
+    repairs: readonly ProcessEventRepair[];
+}>;
+/** Load one catalog entry's run and events, keeping what the event log had to repair. */
+export declare function loadRunDir(rootPath: string, entry: RunCatalogEntry): Promise<LoadedRunDir>;
+//# sourceMappingURL=run-catalog.d.ts.map

package/dist/runtime/run-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-catalog.d.ts","sourceRoot":"","sources":["../../src/runtime/run-catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,OAAO,EAEL,KAAK,kBAAkB,EAGxB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,KAAK,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE3D,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,GAAG,EAAE,UAAU,CAAC;IAChB,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;CACjC,CAAC,CAAC;AAEH,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,IAAI,EACA,mBAAmB,GACnB,qBAAqB,GACrB,kBAAkB,GAClB,oBAAoB,GACpB,kBAAkB,GAClB,mBAAmB,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,IAAI,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACnC,WAAW,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC9C,eAAe,EAAE,MAAM,CAAC;CACzB,CAAC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,gGAAgG;IAChG,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB,CAAC,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC;IAAE,OAAO,EAAE,CAAC,CAAC;IAAC,IAAI,EAAE,SAAS,eAAe,EAAE,CAAA;CAAE,CAAC,CAAC;AAoDpF,oFAAoF;AACpF,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,WAAW,CAAC,MAAM,CAAC,EAClC,KAAK,SAAK,EACV,cAAc,SAA6B,GAC1C,OAAO,CAAC,iBAAiB,CAAC,CAsC5B;AA8CD,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,eAAe,CAahG;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,CAkB1D;AAED,8EAA8E;AAC9E,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAUjF;AAED,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC;IAChC,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,UAAU,CAAC;IAChB,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;CACjC,CAAC,CAAC;AAEH,oGAAoG;AACpG,wBAAsB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAoBtF;AAED,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,UAAU,CAAC;IAChB,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;IAChC,OAAO,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACxC,CAAC,CAAC;AAEH,yFAAyF;AACzF,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,YAAY,CAAC,CAUhG"}

package/dist/runtime/run-catalog.js

@@ -0,0 +1,218 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Run catalog
+ * Reads the runs index (`.devsteps/runs/index.json`) and validated runs per definition without
+ * changing store files; falls back to bounded directory discovery when the index is missing.
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative, resolve } from 'node:path';
+import { isInsideRoot } from '../core/path-guard.js';
+import { stripBom } from '../utils/text-file.js';
+import { checkProcessRunRecovery, readProcessEventLog, readProcessEvents, } from './event-log.js';
+import { ProcessRun } from './index.js';
+async function loadCandidate(rootPath, candidate, diagnostics) {
+    const resolvedRoot = resolve(rootPath);
+    const runPath = resolve(resolvedRoot, candidate.path);
+    if (!isInsideRoot(resolvedRoot, runPath)) {
+        diagnostics.push({
+            kind: 'inaccessible-run',
+            run_id: candidate.run_id,
+            definition_id: candidate.definition_id,
+            message: `Run ${candidate.run_id} resolves outside the run store`,
+        });
+        return undefined;
+    }
+    let run;
+    try {
+        run = ProcessRun.parse(JSON.parse(stripBom(await readFile(join(runPath, 'run.json'), 'utf8'))));
+    }
+    catch (error) {
+        diagnostics.push({
+            kind: 'malformed-snapshot',
+            run_id: candidate.run_id,
+            definition_id: candidate.definition_id,
+            message: `Run ${candidate.run_id} snapshot could not be validated: ${error instanceof Error ? error.message : String(error)}`,
+        });
+        return undefined;
+    }
+    try {
+        const events = await readProcessEvents(join(runPath, 'events.jsonl'));
+        if (!checkProcessRunRecovery(run, events).consistent) {
+            diagnostics.push({
+                kind: 'contradictory-run',
+                run_id: run.run_id,
+                definition_id: run.definition_id,
+                message: `Run ${run.run_id} snapshot and events contradict`,
+            });
+        }
+        return { run, events };
+    }
+    catch (error) {
+        diagnostics.push({
+            kind: 'malformed-events',
+            run_id: candidate.run_id,
+            definition_id: run.definition_id,
+            message: `Run ${candidate.run_id} events could not be validated: ${error instanceof Error ? error.message : String(error)}`,
+        });
+        return undefined;
+    }
+}
+/** Read validated runs for definitions without creating or changing store files. */
+export async function readRunsByDefinition(rootPath, definitionIds, limit = 50, candidateLimit = Math.max(limit * 4, limit)) {
+    if (limit < 1 || candidateLimit < 1)
+        return { runs: [], diagnostics: [], candidates_read: 0 };
+    const diagnostics = [];
+    let candidates = [];
+    try {
+        const catalog = parseRunCatalog(JSON.parse(stripBom(await readFile(join(rootPath, 'index.json'), 'utf8'))));
+        candidates = [...catalog.runs]
+            .sort((left, right) => right.updated_at.localeCompare(left.updated_at))
+            .filter((entry) => definitionIds.has(entry.definition_id));
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        diagnostics.push({
+            kind: 'run-index-missing',
+            message: 'Run catalog is unavailable; bounded legacy discovery was used',
+        });
+        candidates = await discoverRunCandidates(rootPath, definitionIds, candidateLimit);
+    }
+    if (candidates.length > candidateLimit) {
+        diagnostics.push({
+            kind: 'run-index-truncated',
+            message: `Run candidate limit of ${candidateLimit} reached`,
+        });
+        candidates = candidates.slice(0, candidateLimit);
+    }
+    const results = [];
+    for (const candidate of candidates) {
+        const loaded = await loadCandidate(rootPath, candidate, diagnostics);
+        if (loaded)
+            results.push(loaded);
+    }
+    return {
+        runs: results
+            .sort((left, right) => right.run.updated_at.localeCompare(left.run.updated_at))
+            .slice(0, limit),
+        diagnostics,
+        candidates_read: candidates.length,
+    };
+}
+async function discoverRunCandidates(rootPath, definitionIds, limit) {
+    const candidates = [];
+    let processDirectories;
+    try {
+        processDirectories = await readdir(rootPath, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    for (const processDirectory of processDirectories.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (!processDirectory.isDirectory() || candidates.length >= limit)
+            continue;
+        const processPath = join(rootPath, processDirectory.name);
+        for (const runDirectory of (await readdir(processPath, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+            if (!runDirectory.isDirectory() || candidates.length >= limit)
+                continue;
+            try {
+                const run = ProcessRun.parse(JSON.parse(stripBom(await readFile(join(processPath, runDirectory.name, 'run.json'), 'utf8'))));
+                if (definitionIds.has(run.definition_id))
+                    candidates.push(catalogEntry(rootPath, run, join(processPath, runDirectory.name)));
+            }
+            catch {
+                candidates.push({
+                    run_id: runDirectory.name,
+                    process_type: processDirectory.name,
+                    definition_id: '',
+                    updated_at: '',
+                    state: '',
+                    terminal: false,
+                    path: relative(rootPath, join(processPath, runDirectory.name)),
+                });
+            }
+        }
+    }
+    return candidates;
+}
+export function catalogEntry(rootPath, run, runPath) {
+    return {
+        run_id: run.run_id,
+        process_type: run.process_type,
+        definition_id: run.definition_id,
+        updated_at: run.updated_at,
+        state: run.state,
+        terminal: run.terminal,
+        path: relative(rootPath, runPath),
+        schema_version: run.definition_schema_version ?? run.schema_version,
+        version: run.version,
+        verdict: run.verdict ?? null,
+    };
+}
+export function parseRunCatalog(value) {
+    if (typeof value !== 'object' || value === null)
+        throw new Error('Invalid run catalog');
+    const record = value;
+    if (record.version !== 1 || !Array.isArray(record.runs))
+        throw new Error('Invalid run catalog');
+    const runs = record.runs.map((candidate) => {
+        if (typeof candidate !== 'object' || candidate === null)
+            throw new Error('Invalid run catalog entry');
+        const entry = candidate;
+        if (!['run_id', 'process_type', 'definition_id', 'updated_at', 'state', 'path'].every((key) => typeof entry[key] === 'string') ||
+            typeof entry.terminal !== 'boolean')
+            throw new Error('Invalid run catalog entry');
+        return entry;
+    });
+    return { version: 1, runs };
+}
+/** Every catalog entry, newest first; an absent index is an empty catalog. */
+export async function readRunCatalog(rootPath) {
+    try {
+        const catalog = parseRunCatalog(JSON.parse(stripBom(await readFile(join(rootPath, 'index.json'), 'utf8'))));
+        return [...catalog.runs].sort((left, right) => right.updated_at.localeCompare(left.updated_at));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+}
+/** Find one run by id through the catalog, or by scanning process directories when it is absent. */
+export async function readRunById(rootPath, runId) {
+    if (!/^[a-zA-Z0-9_-]+$/.test(runId))
+        throw new RangeError(`Invalid run identifier: ${runId}`);
+    const entry = (await readRunCatalog(rootPath)).find((candidate) => candidate.run_id === runId);
+    let runPath = entry ? resolve(rootPath, entry.path) : undefined;
+    if (!runPath) {
+        const processes = await readdir(rootPath, { withFileTypes: true }).catch(() => []);
+        for (const directory of processes) {
+            if (!directory.isDirectory())
+                continue;
+            const candidate = join(rootPath, directory.name, runId);
+            if ((await readdir(candidate).catch(() => undefined)) !== undefined)
+                runPath = candidate;
+        }
+    }
+    if (!runPath || runPath === resolve(rootPath) || !isInsideRoot(rootPath, runPath)) {
+        throw new Error(`Workflow run ${runId} was not found under ${rootPath}`);
+    }
+    const run = ProcessRun.parse(JSON.parse(stripBom(await readFile(join(runPath, 'run.json'), 'utf8'))));
+    const events = await readProcessEvents(join(runPath, 'events.jsonl'));
+    return { entry, path: runPath, run, events };
+}
+/** Load one catalog entry's run and events, keeping what the event log had to repair. */
+export async function loadRunDir(rootPath, entry) {
+    const resolvedRoot = resolve(rootPath);
+    const path = resolve(resolvedRoot, entry.path);
+    if (path === resolvedRoot || !isInsideRoot(resolvedRoot, path))
+        throw new Error(`Run ${entry.run_id} resolves outside the run store`);
+    const run = ProcessRun.parse(JSON.parse(stripBom(await readFile(join(path, 'run.json'), 'utf8'))));
+    const { events, repairs } = await readProcessEventLog(join(path, 'events.jsonl'));
+    return { path, run, events, repairs };
+}
+//# sourceMappingURL=run-catalog.js.map

package/dist/runtime/run-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-catalog.js","sourceRoot":"","sources":["../../src/runtime/run-catalog.ts"],"names":[],"mappings":"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"}

package/dist/runtime/run-event-payload.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Recognised payload vocabulary of v1 workflow events.
+ * The report renders these keys; other keys are stored unchanged (guards may read them) and are
+ * listed under `extra` in the report.
+ */
+import { z } from 'zod';
+export declare const RunEventPayload: z.ZodObject<{
+    summary: z.ZodOptional<z.ZodString>;
+    outcome: z.ZodOptional<z.ZodEnum<{
+        blocked: "blocked";
+        failed: "failed";
+        inconclusive: "inconclusive";
+        recorded: "recorded";
+    }>>;
+    artifact_path: z.ZodOptional<z.ZodString>;
+    artifacts: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    artifact_digests: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    error_code: z.ZodOptional<z.ZodString>;
+    tool_name: z.ZodOptional<z.ZodString>;
+    arguments: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    parameters: z.ZodOptional<z.ZodUnknown>;
+    result: z.ZodOptional<z.ZodUnknown>;
+    human_answer: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    stdout_preview: z.ZodOptional<z.ZodString>;
+    stderr_preview: z.ZodOptional<z.ZodString>;
+    stdout: z.ZodOptional<z.ZodString>;
+    stderr: z.ZodOptional<z.ZodString>;
+    provenance: z.ZodOptional<z.ZodEnum<{
+        complete: "complete";
+        "not-recorded": "not-recorded";
+        reduced: "reduced";
+    }>>;
+    warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    checkpoint: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$loose>;
+export type RunEventPayload = z.infer<typeof RunEventPayload>;
+export declare const RUN_EVENT_PAYLOAD_KEYS: readonly string[];
+export declare class RunEventPayloadError extends Error {
+    readonly code = "INPUT_INVALID";
+    constructor(message: string);
+}
+/** Validate the recognised keys of a v1 payload and name the keys outside the vocabulary. */
+export declare function validateRunEventPayload(payload: Readonly<Record<string, unknown>> | undefined): {
+    payload: Readonly<Record<string, unknown>> | undefined;
+    unrecognized: string[];
+};
+/** The payload keys outside the recognised vocabulary. */
+export declare function extraPayloadKeys(payload: Readonly<Record<string, unknown>>): Record<string, unknown>;
+//# sourceMappingURL=run-event-payload.d.ts.map

package/dist/runtime/run-event-payload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-event-payload.d.ts","sourceRoot":"","sources":["../../src/runtime/run-event-payload.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAqBZ,CAAC;AACjB,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAAuC,CAAC;AAE5F,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,SAAgB,IAAI,mBAAmB;IAEvC,YAAmB,OAAO,EAAE,MAAM,EAGjC;CACF;AAED,6FAA6F;AAC7F,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,GAAG;IAC/F,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IACvD,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB,CAeA;AAED,0DAA0D;AAC1D,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACzC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAIzB"}

package/dist/runtime/run-event-payload.js

@@ -0,0 +1,60 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Recognised payload vocabulary of v1 workflow events.
+ * The report renders these keys; other keys are stored unchanged (guards may read them) and are
+ * listed under `extra` in the report.
+ */
+import { z } from 'zod';
+export const RunEventPayload = z
+    .object({
+    summary: z.string().max(4000).optional(),
+    outcome: z.enum(['recorded', 'failed', 'blocked', 'inconclusive']).optional(),
+    artifact_path: z.string().max(500).optional(),
+    artifacts: z.array(z.string().max(500)).max(100).optional(),
+    artifact_digests: z.array(z.string().max(200)).max(100).optional(),
+    error_code: z.string().max(100).optional(),
+    tool_name: z.string().max(200).optional(),
+    arguments: z.record(z.string(), z.unknown()).optional(),
+    parameters: z.unknown().optional(),
+    result: z.unknown().optional(),
+    human_answer: z.union([z.string().max(2000), z.record(z.string(), z.unknown())]).optional(),
+    stdout_preview: z.string().max(2000).optional(),
+    stderr_preview: z.string().max(2000).optional(),
+    stdout: z.string().optional(),
+    stderr: z.string().optional(),
+    provenance: z.enum(['complete', 'reduced', 'not-recorded']).optional(),
+    warnings: z.array(z.string().max(1000)).max(100).optional(),
+    checkpoint: z.record(z.string(), z.unknown()).optional(),
+})
+    .passthrough();
+export const RUN_EVENT_PAYLOAD_KEYS = Object.keys(RunEventPayload.shape);
+export class RunEventPayloadError extends Error {
+    code = 'INPUT_INVALID';
+    constructor(message) {
+        super(`INPUT_INVALID: ${message}`);
+        this.name = 'RunEventPayloadError';
+    }
+}
+/** Validate the recognised keys of a v1 payload and name the keys outside the vocabulary. */
+export function validateRunEventPayload(payload) {
+    if (payload === undefined)
+        return { payload, unrecognized: [] };
+    const parsed = RunEventPayload.safeParse(payload);
+    if (!parsed.success) {
+        const issues = parsed.error.issues
+            .map((issue) => `${issue.path.join('.') || 'payload'}: ${issue.message}`)
+            .join('; ');
+        throw new RunEventPayloadError(`payload does not match the recognised keys (${issues}); recognised: ${RUN_EVENT_PAYLOAD_KEYS.join(', ')}`);
+    }
+    return {
+        payload,
+        unrecognized: Object.keys(payload).filter((key) => !RUN_EVENT_PAYLOAD_KEYS.includes(key)),
+    };
+}
+/** The payload keys outside the recognised vocabulary. */
+export function extraPayloadKeys(payload) {
+    return Object.fromEntries(Object.entries(payload).filter(([key]) => !RUN_EVENT_PAYLOAD_KEYS.includes(key)));
+}
+//# sourceMappingURL=run-event-payload.js.map

package/dist/runtime/run-event-payload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-event-payload.js","sourceRoot":"","sources":["../../src/runtime/run-event-payload.ts"],"names":[],"mappings":"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"}

package/dist/runtime/run-history.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Run history
+ * Summarizes the runs of one guide for a history list and loads one run for replay. The list is
+ * driven by the runs index and reads only the page it returns; a replay refuses a run whose log
+ * needs repair, so no half-truth is shown.
+ * @see STORY-454 STORY-444 STORY-366
+ */
+import type { ProcessEvent, ProcessRun } from './index.js';
+import { type RunEvidenceDiagnostic } from './run-catalog.js';
+import { type RunTrail } from './run-trail.js';
+import { type WorkflowV2Report } from './workflow-v2-report.js';
+import type { WorkflowRunMode } from './workflow-v2-types.js';
+export type RunLifecycle = 'open' | 'awaiting-finalize' | 'finished';
+export type RunIntegrity = 'ok' | 'needs-repair' | 'unreadable';
+export type RunSummary = Readonly<{
+    run_id: string;
+    short_id: string;
+    definition_id: string;
+    /** Relative to the runs root. */
+    path: string;
+    lifecycle: RunLifecycle;
+    verdict: string | null;
+    pending_verdict: string | null;
+    reason?: string;
+    started_at: string;
+    ended_at?: string;
+    updated_at: string;
+    last_event_at?: string;
+    /** For an open run, `now - started_at`. */
+    elapsed_ms: number;
+    mode: WorkflowRunMode;
+    host_profile?: string;
+    /** Distinct names of human events; `operator` when none is named. */
+    operator: string[];
+    /** Distinct names of agent events: recorded activity, not live presence. */
+    agents: string[];
+    tally: Readonly<{
+        completed: number;
+        skipped: number;
+        failed: number;
+        bypassed: number;
+        remaining: number;
+        total: number;
+    }>;
+    open_notes: number;
+    integrity: RunIntegrity;
+}>;
+/** One history card from a run and its events; pure, `now` is injected. */
+export declare function summarizeRun(run: ProcessRun, events: readonly ProcessEvent[], now: Date, integrity?: RunIntegrity): RunSummary;
+export type RunSummaryPage = Readonly<{
+    runs: readonly RunSummary[];
+    /** Pass as `before` to get the next, older page. */
+    next_before?: string;
+    diagnostics: readonly RunEvidenceDiagnostic[];
+}>;
+/**
+ * The runs of one guide, newest first, from the runs index; only `limit` runs (default 20) are
+ * loaded and no directory is scanned. `before` is the `next_before` cursor (`updated_at|run_id`);
+ * ties on `updated_at` are ordered by run id so no run is lost across a page boundary.
+ */
+export declare function readRunSummaries(runsRoot: string, definitionId: string, options?: {
+    limit?: number;
+    before?: string;
+    now?: Date;
+}): Promise<RunSummaryPage>;
+export type RunReplay = Readonly<{
+    summary: RunSummary;
+    report: WorkflowV2Report;
+    trail: RunTrail;
+}> | Readonly<{
+    summary: RunSummary;
+    problem: 'needs-repair' | 'unreadable';
+    message: string;
+}>;
+/** Load one run for replay; a run that needs repair or cannot be read yields the problem arm. */
+export declare function readRunReplay(runsRoot: string, runId: string, now?: Date): Promise<RunReplay>;
+//# sourceMappingURL=run-history.d.ts.map

package/dist/runtime/run-history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-history.d.ts","sourceRoot":"","sources":["../../src/runtime/run-history.ts"],"names":[],"mappings":"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"}