open-multi-agent-kit 0.96.0 → 0.96.2

package/dist/core/workload-shard-executor.js

@@ -0,0 +1,156 @@
+import { planShardResume, reduceShardRecords, validateWorkloadShardPlan, } from "./workload-shard-plan.js";
+import { applyTransition, runOneShard, shardById } from "./workload-shard-runner.js";
+import { WorkloadShardJournalError } from "./workload-shard-store.js";
+export async function executeWorkloadShardPlan(input) {
+    const now = input.now ?? (() => new Date());
+    const planErrors = validateWorkloadShardPlan(input.plan);
+    if (planErrors.length > 0) {
+        return blockedEvidence(input, now, ["plan.invalid", ...planErrors.slice(0, 3)]);
+    }
+    let journal;
+    try {
+        journal = input.store.load();
+    }
+    catch (error) {
+        // §21 fail closed: corrupt evidence is quarantined, never silently rebuilt.
+        if (error instanceof WorkloadShardJournalError) {
+            input.store.quarantine();
+            return blockedEvidence(input, now, [`journal.${error.code}`]);
+        }
+        throw error;
+    }
+    if (journal.plan === null) {
+        input.store.appendPlan(input.plan);
+    }
+    else if (journal.plan.planId !== input.plan.planId || journal.plan.commandDigest !== input.plan.commandDigest) {
+        return blockedEvidence(input, now, ["plan.mismatch"]);
+    }
+    const projections = new Map(journal.projections ?? reduceShardRecords(input.plan, []));
+    const effectiveConcurrency = Math.max(1, Math.min(input.plan.maxConcurrency, input.decision.maxHeavyProcesses));
+    // §13.5 steps 2-4: re-arm recoverable shards through explicit pending records.
+    const resume = planShardResume(input.plan, projections);
+    const rearm = [
+        ...resume.interrupted,
+        ...(input.retryFailed ? resume.retryable : []),
+        ...((input.resumeAborted ?? true) ? resume.resumable : []),
+    ];
+    for (const shardId of rearm) {
+        // §13.5 step 2: a crash-orphaned `running` shard is first projected as
+        // interrupted (running -> pending is illegal in §13.4), then re-armed.
+        if (projections.get(shardId)?.state === "running") {
+            applyTransition(input, projections, shardId, "interrupted", { reasonCode: "recovery.orphaned", now });
+        }
+        applyTransition(input, projections, shardId, "pending", { reasonCode: "recovery.rearm", now });
+    }
+    // Dependency-wave scheduler: launch ready shards up to the recomputed width.
+    const remaining = new Set(input.plan.shards.map((shard) => shard.shardId).filter((id) => projections.get(id)?.state !== "passed"));
+    let active = 0;
+    let wake;
+    const waitTurn = () => new Promise((resolve) => {
+        wake = resolve;
+    });
+    const running = new Map();
+    while (remaining.size > 0 && !input.signal?.aborted) {
+        const ready = [...remaining].filter((id) => {
+            const projection = projections.get(id);
+            if (projection?.state !== "pending")
+                return false;
+            const spec = shardById(input.plan, id);
+            return spec.dependencyIds.every((dep) => projections.get(dep)?.state === "passed");
+        });
+        const launchable = ready.slice(0, Math.max(0, effectiveConcurrency - active));
+        if (launchable.length === 0) {
+            if (running.size === 0)
+                break; // deadlock = blocked dependents; aggregate reports them
+            await Promise.race([...running.values(), waitTurn()]);
+            continue;
+        }
+        for (const shardId of launchable) {
+            remaining.delete(shardId);
+            active += 1;
+            const task = runOneShard(input, projections, shardId, now).finally(() => {
+                active -= 1;
+                running.delete(shardId);
+                wake?.();
+            });
+            running.set(shardId, task);
+        }
+    }
+    await Promise.all(running.values());
+    return aggregate(input, projections, effectiveConcurrency, now, input.signal?.aborted ? ["run.aborted"] : []);
+}
+function aggregate(input, projections, effectiveConcurrency, now, extraReasons) {
+    const counts = {
+        pending: 0,
+        running: 0,
+        passed: 0,
+        failed: 0,
+        aborted: 0,
+        interrupted: 0,
+    };
+    const shards = input.plan.shards.map((shard) => {
+        const projection = projections.get(shard.shardId);
+        const state = projection?.state ?? "pending";
+        counts[state] += 1;
+        return {
+            shardId: shard.shardId,
+            state,
+            attempt: projection?.attempt ?? 0,
+            evidenceRefs: projection?.evidenceRefs ?? [],
+            ...(projection?.reasonCode !== undefined ? { reasonCode: projection.reasonCode } : {}),
+        };
+    });
+    const verdict = aggregateVerdict(counts, input.plan.shards.length, extraReasons);
+    return {
+        kind: "workload_shard_result.v1",
+        planId: input.plan.planId,
+        promptRunId: input.plan.promptRunId,
+        commandDigest: input.plan.commandDigest,
+        strategy: input.plan.strategy,
+        verdict,
+        reasonCodes: extraReasons,
+        shardCount: input.plan.shards.length,
+        counts,
+        shards,
+        effectiveConcurrency,
+        completedAt: now().toISOString(),
+    };
+}
+function blockedEvidence(input, now, reasonCodes) {
+    const counts = {
+        pending: input.plan.shards.length,
+        running: 0,
+        passed: 0,
+        failed: 0,
+        aborted: 0,
+        interrupted: 0,
+    };
+    return {
+        kind: "workload_shard_result.v1",
+        planId: input.plan.planId,
+        promptRunId: input.plan.promptRunId,
+        commandDigest: input.plan.commandDigest,
+        strategy: input.plan.strategy,
+        verdict: "blocked",
+        reasonCodes,
+        shardCount: input.plan.shards.length,
+        counts,
+        shards: input.plan.shards.map((shard) => ({
+            shardId: shard.shardId,
+            state: "pending",
+            attempt: 0,
+            evidenceRefs: [],
+        })),
+        effectiveConcurrency: 0,
+        completedAt: now().toISOString(),
+    };
+}
+/** §13.6: "passed" requires EVERY shard to hold terminal passed evidence. */
+function aggregateVerdict(counts, shardCount, extraReasons) {
+    if (counts.passed === shardCount)
+        return "passed";
+    if (counts.aborted > 0 || extraReasons.includes("run.aborted"))
+        return "aborted";
+    return "failed";
+}
+//# sourceMappingURL=workload-shard-executor.js.map

package/dist/core/workload-shard-executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workload-shard-executor.js","sourceRoot":"","sources":["../../src/core/workload-shard-executor.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ResourceAdmissionDecision } from \"./resource-admission.ts\";\nimport type { WorkloadPermitPool } from \"./workload-permit-pool.ts\";\nimport {\n\tplanShardResume,\n\treduceShardRecords,\n\tvalidateWorkloadShardPlan,\n\ttype WorkloadShardPlan,\n\ttype WorkloadShardProjection,\n\ttype WorkloadShardSpec,\n\ttype WorkloadShardState,\n} from \"./workload-shard-plan.ts\";\nimport { applyTransition, runOneShard, shardById } from \"./workload-shard-runner.ts\";\nimport { WorkloadShardJournalError, type WorkloadShardStore } from \"./workload-shard-store.ts\";\n\n/**\n * Workload shard executor (OMK v0.97.x roadmap §13, M5 completion slice).\n *\n * Drives a validated `WorkloadShardPlan` through the journalled §13.4 state\n * machine: passed shards are terminal and never re-run (§13.5 step 3),\n * crash-orphaned `running` shards are recovered through `pending` re-arm\n * records, concurrency is recomputed from the CURRENT admission decision\n * (§13.5 step 6) plus the shared permit pool, and completion produces an\n * aggregate evidence receipt (§13.6) — an observation input for\n * `evaluateTask()`, never a task verdict by itself.\n *\n * Fail-closed rules (§21): a corrupt journal is quarantined and the run is\n * `blocked`; a journal written for a different plan is `blocked`; an invalid\n * plan never starts. The executor never rewrites shard commands (§12.3) —\n * it only runs what the plan's descriptors already describe via the\n * injected runner.\n */\n\nexport interface ShardRunContext {\n\treadonly shard: WorkloadShardSpec;\n\treadonly attempt: number;\n\treadonly signal?: AbortSignal;\n}\n\nexport type ShardRunner = (\n\tcontext: ShardRunContext,\n) => Promise<{ readonly exitCode: number; readonly evidenceRefs?: readonly string[] }>;\n\nexport interface ExecuteWorkloadShardPlanInput {\n\treadonly plan: WorkloadShardPlan;\n\treadonly store: WorkloadShardStore;\n\treadonly runner: ShardRunner;\n\treadonly decision: ResourceAdmissionDecision;\n\treadonly permitPool?: WorkloadPermitPool;\n\treadonly signal?: AbortSignal;\n\t/** §13.5 step 4 retry policy: re-arm previously failed shards. Default false. */\n\treadonly retryFailed?: boolean;\n\t/** §13.4: aborted -> pending needs an explicit resume; this call is that act. Default true. */\n\treadonly resumeAborted?: boolean;\n\treadonly permitWaitTimeoutMs?: number;\n\treadonly now?: () => Date;\n}\n\nexport interface ShardResultSummary {\n\treadonly shardId: string;\n\treadonly state: WorkloadShardState;\n\treadonly attempt: number;\n\treadonly evidenceRefs: readonly string[];\n\treadonly reasonCode?: string;\n}\n\n/** §13.6 aggregate evidence receipt; §15.1 observation kind. */\nexport interface WorkloadShardAggregateEvidence {\n\treadonly kind: \"workload_shard_result.v1\";\n\treadonly planId: string;\n\treadonly promptRunId: string;\n\treadonly commandDigest: string;\n\treadonly strategy: string;\n\treadonly verdict: \"passed\" | \"failed\" | \"aborted\" | \"blocked\";\n\treadonly reasonCodes: readonly string[];\n\treadonly shardCount: number;\n\treadonly counts: Readonly<Record<WorkloadShardState, number>>;\n\treadonly shards: readonly ShardResultSummary[];\n\treadonly effectiveConcurrency: number;\n\treadonly completedAt: string;\n}\n\nexport async function executeWorkloadShardPlan(\n\tinput: ExecuteWorkloadShardPlanInput,\n): Promise<WorkloadShardAggregateEvidence> {\n\tconst now = input.now ?? (() => new Date());\n\tconst planErrors = validateWorkloadShardPlan(input.plan);\n\tif (planErrors.length > 0) {\n\t\treturn blockedEvidence(input, now, [\"plan.invalid\", ...planErrors.slice(0, 3)]);\n\t}\n\n\tlet journal: ReturnType<WorkloadShardStore[\"load\"]>;\n\ttry {\n\t\tjournal = input.store.load();\n\t} catch (error) {\n\t\t// §21 fail closed: corrupt evidence is quarantined, never silently rebuilt.\n\t\tif (error instanceof WorkloadShardJournalError) {\n\t\t\tinput.store.quarantine();\n\t\t\treturn blockedEvidence(input, now, [`journal.${error.code}`]);\n\t\t}\n\t\tthrow error;\n\t}\n\tif (journal.plan === null) {\n\t\tinput.store.appendPlan(input.plan);\n\t} else if (journal.plan.planId !== input.plan.planId || journal.plan.commandDigest !== input.plan.commandDigest) {\n\t\treturn blockedEvidence(input, now, [\"plan.mismatch\"]);\n\t}\n\n\tconst projections = new Map<string, WorkloadShardProjection>(\n\t\tjournal.projections ?? reduceShardRecords(input.plan, []),\n\t);\n\tconst effectiveConcurrency = Math.max(1, Math.min(input.plan.maxConcurrency, input.decision.maxHeavyProcesses));\n\n\t// §13.5 steps 2-4: re-arm recoverable shards through explicit pending records.\n\tconst resume = planShardResume(input.plan, projections);\n\tconst rearm = [\n\t\t...resume.interrupted,\n\t\t...(input.retryFailed ? resume.retryable : []),\n\t\t...((input.resumeAborted ?? true) ? resume.resumable : []),\n\t];\n\tfor (const shardId of rearm) {\n\t\t// §13.5 step 2: a crash-orphaned `running` shard is first projected as\n\t\t// interrupted (running -> pending is illegal in §13.4), then re-armed.\n\t\tif (projections.get(shardId)?.state === \"running\") {\n\t\t\tapplyTransition(input, projections, shardId, \"interrupted\", { reasonCode: \"recovery.orphaned\", now });\n\t\t}\n\t\tapplyTransition(input, projections, shardId, \"pending\", { reasonCode: \"recovery.rearm\", now });\n\t}\n\n\t// Dependency-wave scheduler: launch ready shards up to the recomputed width.\n\tconst remaining = new Set(\n\t\tinput.plan.shards.map((shard) => shard.shardId).filter((id) => projections.get(id)?.state !== \"passed\"),\n\t);\n\tlet active = 0;\n\tlet wake: (() => void) | undefined;\n\tconst waitTurn = () =>\n\t\tnew Promise<void>((resolve) => {\n\t\t\twake = resolve;\n\t\t});\n\tconst running = new Map<string, Promise<void>>();\n\n\twhile (remaining.size > 0 && !input.signal?.aborted) {\n\t\tconst ready = [...remaining].filter((id) => {\n\t\t\tconst projection = projections.get(id);\n\t\t\tif (projection?.state !== \"pending\") return false;\n\t\t\tconst spec = shardById(input.plan, id);\n\t\t\treturn spec.dependencyIds.every((dep) => projections.get(dep)?.state === \"passed\");\n\t\t});\n\t\tconst launchable = ready.slice(0, Math.max(0, effectiveConcurrency - active));\n\t\tif (launchable.length === 0) {\n\t\t\tif (running.size === 0) break; // deadlock = blocked dependents; aggregate reports them\n\t\t\tawait Promise.race([...running.values(), waitTurn()]);\n\t\t\tcontinue;\n\t\t}\n\t\tfor (const shardId of launchable) {\n\t\t\tremaining.delete(shardId);\n\t\t\tactive += 1;\n\t\t\tconst task = runOneShard(input, projections, shardId, now).finally(() => {\n\t\t\t\tactive -= 1;\n\t\t\t\trunning.delete(shardId);\n\t\t\t\twake?.();\n\t\t\t});\n\t\t\trunning.set(shardId, task);\n\t\t}\n\t}\n\tawait Promise.all(running.values());\n\n\treturn aggregate(input, projections, effectiveConcurrency, now, input.signal?.aborted ? [\"run.aborted\"] : []);\n}\n\nfunction aggregate(\n\tinput: ExecuteWorkloadShardPlanInput,\n\tprojections: ReadonlyMap<string, WorkloadShardProjection>,\n\teffectiveConcurrency: number,\n\tnow: () => Date,\n\textraReasons: readonly string[],\n): WorkloadShardAggregateEvidence {\n\tconst counts: Record<WorkloadShardState, number> = {\n\t\tpending: 0,\n\t\trunning: 0,\n\t\tpassed: 0,\n\t\tfailed: 0,\n\t\taborted: 0,\n\t\tinterrupted: 0,\n\t};\n\tconst shards: ShardResultSummary[] = input.plan.shards.map((shard) => {\n\t\tconst projection = projections.get(shard.shardId);\n\t\tconst state = projection?.state ?? \"pending\";\n\t\tcounts[state] += 1;\n\t\treturn {\n\t\t\tshardId: shard.shardId,\n\t\t\tstate,\n\t\t\tattempt: projection?.attempt ?? 0,\n\t\t\tevidenceRefs: projection?.evidenceRefs ?? [],\n\t\t\t...(projection?.reasonCode !== undefined ? { reasonCode: projection.reasonCode } : {}),\n\t\t};\n\t});\n\tconst verdict = aggregateVerdict(counts, input.plan.shards.length, extraReasons);\n\treturn {\n\t\tkind: \"workload_shard_result.v1\",\n\t\tplanId: input.plan.planId,\n\t\tpromptRunId: input.plan.promptRunId,\n\t\tcommandDigest: input.plan.commandDigest,\n\t\tstrategy: input.plan.strategy,\n\t\tverdict,\n\t\treasonCodes: extraReasons,\n\t\tshardCount: input.plan.shards.length,\n\t\tcounts,\n\t\tshards,\n\t\teffectiveConcurrency,\n\t\tcompletedAt: now().toISOString(),\n\t};\n}\n\nfunction blockedEvidence(\n\tinput: ExecuteWorkloadShardPlanInput,\n\tnow: () => Date,\n\treasonCodes: readonly string[],\n): WorkloadShardAggregateEvidence {\n\tconst counts: Record<WorkloadShardState, number> = {\n\t\tpending: input.plan.shards.length,\n\t\trunning: 0,\n\t\tpassed: 0,\n\t\tfailed: 0,\n\t\taborted: 0,\n\t\tinterrupted: 0,\n\t};\n\treturn {\n\t\tkind: \"workload_shard_result.v1\",\n\t\tplanId: input.plan.planId,\n\t\tpromptRunId: input.plan.promptRunId,\n\t\tcommandDigest: input.plan.commandDigest,\n\t\tstrategy: input.plan.strategy,\n\t\tverdict: \"blocked\",\n\t\treasonCodes,\n\t\tshardCount: input.plan.shards.length,\n\t\tcounts,\n\t\tshards: input.plan.shards.map((shard) => ({\n\t\t\tshardId: shard.shardId,\n\t\t\tstate: \"pending\" as const,\n\t\t\tattempt: 0,\n\t\t\tevidenceRefs: [],\n\t\t})),\n\t\teffectiveConcurrency: 0,\n\t\tcompletedAt: now().toISOString(),\n\t};\n}\n\n/** §13.6: \"passed\" requires EVERY shard to hold terminal passed evidence. */\nfunction aggregateVerdict(\n\tcounts: Readonly<Record<WorkloadShardState, number>>,\n\tshardCount: number,\n\textraReasons: readonly string[],\n): WorkloadShardAggregateEvidence[\"verdict\"] {\n\tif (counts.passed === shardCount) return \"passed\";\n\tif (counts.aborted > 0 || extraReasons.includes(\"run.aborted\")) return \"aborted\";\n\treturn \"failed\";\n}\n"]}

package/dist/core/workload-shard-plan.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Workload shard plan and state contracts (OMK v0.97.x roadmap §13, M5/PR8).
+ *
+ * Pure layer: plan validation, the §13.4 state machine, deterministic
+ * journal replay (reduce), and the §13.5 resume projection. No I/O here —
+ * the journal store persists lines and the M5 executor consumes the
+ * projections. §13.6: shard completion is an evidence source, never a task
+ * verdict; nothing in this module declares a task passed.
+ */
+export declare const WORKLOAD_SHARD_PLAN_VERSION: 1;
+export interface WorkloadShardPlan {
+    readonly schemaVersion: typeof WORKLOAD_SHARD_PLAN_VERSION;
+    readonly planId: string;
+    readonly promptRunId: string;
+    readonly commandDigest: string;
+    readonly strategy: string;
+    readonly createdAt: string;
+    readonly maxConcurrency: number;
+    readonly shards: readonly WorkloadShardSpec[];
+}
+export interface WorkloadShardSpec {
+    readonly shardId: string;
+    readonly dependencyIds: readonly string[];
+    readonly commandDescriptor: {
+        readonly executable: string;
+        readonly argvDigest: string;
+        readonly redactedArgv: readonly string[];
+    };
+    readonly expectedEvidence: readonly string[];
+}
+export type WorkloadShardState = "pending" | "running" | "passed" | "failed" | "aborted" | "interrupted";
+export interface WorkloadShardRecord {
+    readonly schemaVersion: 1;
+    readonly planId: string;
+    readonly shardId: string;
+    readonly attempt: number;
+    readonly state: WorkloadShardState;
+    readonly startedAt?: string;
+    readonly finishedAt?: string;
+    readonly evidenceRefs: readonly string[];
+    readonly reasonCode?: string;
+}
+export declare function canTransitionShardState(from: WorkloadShardState, to: WorkloadShardState): boolean;
+/** §22.1: journals carry only the digest and a redacted descriptor, never raw argv. */
+export declare function buildShardCommandDescriptor(argv: readonly string[]): WorkloadShardSpec["commandDescriptor"];
+/** Structural plan validation: ids unique, dependencies resolvable and acyclic. */
+export declare function validateWorkloadShardPlan(plan: WorkloadShardPlan): readonly string[];
+export interface WorkloadShardProjection {
+    readonly shardId: string;
+    readonly state: WorkloadShardState;
+    readonly attempt: number;
+    readonly evidenceRefs: readonly string[];
+    readonly reasonCode?: string;
+}
+export declare class WorkloadShardTransitionError extends Error {
+    readonly shardId: string;
+    constructor(shardId: string, message: string);
+}
+/**
+ * Deterministic replay of transition records into per-shard projections
+ * (§23.2 property 10). Fail closed (§21): unknown shards, illegal §13.4
+ * transitions, or non-monotonic attempts throw instead of guessing.
+ */
+export declare function reduceShardRecords(plan: WorkloadShardPlan, records: readonly WorkloadShardRecord[]): ReadonlyMap<string, WorkloadShardProjection>;
+export interface WorkloadShardResumePlan {
+    /** §13.5 step 3 / §23.2 property 9: passed shards are never re-run. */
+    readonly skip: readonly string[];
+    /** Pending shards whose dependencies all passed (§13.5 step 5). */
+    readonly ready: readonly string[];
+    /** Pending shards still blocked on dependencies. */
+    readonly blocked: readonly string[];
+    /** Failed shards awaiting the caller's retry policy (§13.5 step 4). */
+    readonly retryable: readonly string[];
+    /** Aborted shards that need an explicit resume decision (§13.4). */
+    readonly resumable: readonly string[];
+    /** Shards projected interrupted: `running` with no terminal record (§13.5 step 2). */
+    readonly interrupted: readonly string[];
+}
+/** §13.5 resume projection. Pure; ordering follows plan order for determinism. */
+export declare function planShardResume(plan: WorkloadShardPlan, projections: ReadonlyMap<string, WorkloadShardProjection>): WorkloadShardResumePlan;
+//# sourceMappingURL=workload-shard-plan.d.ts.map

package/dist/core/workload-shard-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workload-shard-plan.d.ts","sourceRoot":"","sources":["../../src/core/workload-shard-plan.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from \"node:crypto\";\n\n/**\n * Workload shard plan and state contracts (OMK v0.97.x roadmap §13, M5/PR8).\n *\n * Pure layer: plan validation, the §13.4 state machine, deterministic\n * journal replay (reduce), and the §13.5 resume projection. No I/O here —\n * the journal store persists lines and the M5 executor consumes the\n * projections. §13.6: shard completion is an evidence source, never a task\n * verdict; nothing in this module declares a task passed.\n */\n\nexport const WORKLOAD_SHARD_PLAN_VERSION = 1 as const;\n\nexport interface WorkloadShardPlan {\n\treadonly schemaVersion: typeof WORKLOAD_SHARD_PLAN_VERSION;\n\treadonly planId: string;\n\treadonly promptRunId: string;\n\treadonly commandDigest: string;\n\treadonly strategy: string;\n\treadonly createdAt: string;\n\treadonly maxConcurrency: number;\n\treadonly shards: readonly WorkloadShardSpec[];\n}\n\nexport interface WorkloadShardSpec {\n\treadonly shardId: string;\n\treadonly dependencyIds: readonly string[];\n\treadonly commandDescriptor: {\n\t\treadonly executable: string;\n\t\treadonly argvDigest: string;\n\t\treadonly redactedArgv: readonly string[];\n\t};\n\treadonly expectedEvidence: readonly string[];\n}\n\nexport type WorkloadShardState = \"pending\" | \"running\" | \"passed\" | \"failed\" | \"aborted\" | \"interrupted\";\n\nexport interface WorkloadShardRecord {\n\treadonly schemaVersion: 1;\n\treadonly planId: string;\n\treadonly shardId: string;\n\treadonly attempt: number;\n\treadonly state: WorkloadShardState;\n\treadonly startedAt?: string;\n\treadonly finishedAt?: string;\n\treadonly evidenceRefs: readonly string[];\n\treadonly reasonCode?: string;\n}\n\n/** §13.4 legal transitions. `pending` re-arms come from failed/aborted/interrupted only. */\nconst LEGAL_TRANSITIONS: Readonly<Record<WorkloadShardState, readonly WorkloadShardState[]>> = {\n\tpending: [\"running\"],\n\trunning: [\"passed\", \"failed\", \"aborted\", \"interrupted\"],\n\tfailed: [\"pending\"],\n\taborted: [\"pending\"],\n\tinterrupted: [\"pending\"],\n\tpassed: [],\n};\n\nexport function canTransitionShardState(from: WorkloadShardState, to: WorkloadShardState): boolean {\n\treturn LEGAL_TRANSITIONS[from].includes(to);\n}\n\n/** §22.1: journals carry only the digest and a redacted descriptor, never raw argv. */\nexport function buildShardCommandDescriptor(argv: readonly string[]): WorkloadShardSpec[\"commandDescriptor\"] {\n\tconst executable = basename(argv[0] ?? \"\");\n\tconst redactedArgv = argv.map((token, index) => {\n\t\tif (index === 0) {\n\t\t\treturn executable;\n\t\t}\n\t\tif (/^-{1,2}[A-Za-z0-9][A-Za-z0-9=/:.,_-]*$/.test(token)) {\n\t\t\treturn token; // flags (with inline values) stay readable\n\t\t}\n\t\tif (/^[A-Za-z0-9_.:-]{1,32}$/.test(token) && !token.includes(\"..\")) {\n\t\t\treturn token; // short bare words (subcommands, shard specs)\n\t\t}\n\t\treturn \"<redacted>\"; // paths, globs, and anything possibly sensitive\n\t});\n\treturn {\n\t\texecutable,\n\t\targvDigest: createHash(\"sha256\").update(JSON.stringify(argv), \"utf8\").digest(\"hex\"),\n\t\tredactedArgv,\n\t};\n}\n\n/** Structural plan validation: ids unique, dependencies resolvable and acyclic. */\nexport function validateWorkloadShardPlan(plan: WorkloadShardPlan): readonly string[] {\n\tconst errors: string[] = [];\n\tif (plan.schemaVersion !== WORKLOAD_SHARD_PLAN_VERSION) {\n\t\terrors.push(`plan.schemaVersion: expected ${WORKLOAD_SHARD_PLAN_VERSION}`);\n\t}\n\tif (!Number.isSafeInteger(plan.maxConcurrency) || plan.maxConcurrency < 1) {\n\t\terrors.push(\"plan.maxConcurrency: must be a positive integer\");\n\t}\n\tif (plan.shards.length === 0) {\n\t\terrors.push(\"plan.shards: must not be empty\");\n\t}\n\tconst ids = new Set<string>();\n\tfor (const shard of plan.shards) {\n\t\tif (ids.has(shard.shardId)) {\n\t\t\terrors.push(`plan.shards: duplicate shardId ${shard.shardId}`);\n\t\t}\n\t\tids.add(shard.shardId);\n\t}\n\tfor (const shard of plan.shards) {\n\t\tfor (const dependency of shard.dependencyIds) {\n\t\t\tif (!ids.has(dependency)) {\n\t\t\t\terrors.push(`plan.shards: ${shard.shardId} depends on unknown ${dependency}`);\n\t\t\t}\n\t\t}\n\t}\n\tif (errors.length === 0 && hasDependencyCycle(plan.shards)) {\n\t\terrors.push(\"plan.shards: dependency cycle detected\");\n\t}\n\treturn errors;\n}\n\nfunction hasDependencyCycle(shards: readonly WorkloadShardSpec[]): boolean {\n\tconst visiting = new Set<string>();\n\tconst done = new Set<string>();\n\tconst byId = new Map(shards.map((shard) => [shard.shardId, shard]));\n\tconst visit = (id: string): boolean => {\n\t\tif (done.has(id)) return false;\n\t\tif (visiting.has(id)) return true;\n\t\tvisiting.add(id);\n\t\tfor (const dependency of byId.get(id)?.dependencyIds ?? []) {\n\t\t\tif (visit(dependency)) return true;\n\t\t}\n\t\tvisiting.delete(id);\n\t\tdone.add(id);\n\t\treturn false;\n\t};\n\treturn shards.some((shard) => visit(shard.shardId));\n}\n\nexport interface WorkloadShardProjection {\n\treadonly shardId: string;\n\treadonly state: WorkloadShardState;\n\treadonly attempt: number;\n\treadonly evidenceRefs: readonly string[];\n\treadonly reasonCode?: string;\n}\n\nexport class WorkloadShardTransitionError extends Error {\n\treadonly shardId: string;\n\tconstructor(shardId: string, message: string) {\n\t\tsuper(`shard ${shardId}: ${message}`);\n\t\tthis.name = \"WorkloadShardTransitionError\";\n\t\tthis.shardId = shardId;\n\t}\n}\n\n/**\n * Deterministic replay of transition records into per-shard projections\n * (§23.2 property 10). Fail closed (§21): unknown shards, illegal §13.4\n * transitions, or non-monotonic attempts throw instead of guessing.\n */\nexport function reduceShardRecords(\n\tplan: WorkloadShardPlan,\n\trecords: readonly WorkloadShardRecord[],\n): ReadonlyMap<string, WorkloadShardProjection> {\n\tconst projections = new Map<string, WorkloadShardProjection>();\n\tfor (const shard of plan.shards) {\n\t\tprojections.set(shard.shardId, { shardId: shard.shardId, state: \"pending\", attempt: 0, evidenceRefs: [] });\n\t}\n\tfor (const record of records) {\n\t\tconst current = projections.get(record.shardId);\n\t\tif (current === undefined) {\n\t\t\tthrow new WorkloadShardTransitionError(record.shardId, \"transition for shard not in plan\");\n\t\t}\n\t\tif (record.planId !== plan.planId) {\n\t\t\tthrow new WorkloadShardTransitionError(record.shardId, `record planId ${record.planId} != ${plan.planId}`);\n\t\t}\n\t\tif (!canTransitionShardState(current.state, record.state)) {\n\t\t\tthrow new WorkloadShardTransitionError(\n\t\t\t\trecord.shardId,\n\t\t\t\t`illegal transition ${current.state} -> ${record.state}`,\n\t\t\t);\n\t\t}\n\t\tconst expectedAttempt = record.state === \"running\" ? current.attempt + 1 : current.attempt;\n\t\tif (record.attempt !== expectedAttempt) {\n\t\t\tthrow new WorkloadShardTransitionError(\n\t\t\t\trecord.shardId,\n\t\t\t\t`attempt ${record.attempt} != expected ${expectedAttempt} for ${record.state}`,\n\t\t\t);\n\t\t}\n\t\tprojections.set(record.shardId, {\n\t\t\tshardId: record.shardId,\n\t\t\tstate: record.state,\n\t\t\tattempt: expectedAttempt,\n\t\t\tevidenceRefs: record.evidenceRefs.length > 0 ? record.evidenceRefs : current.evidenceRefs,\n\t\t\treasonCode: record.reasonCode ?? (record.state === \"pending\" ? undefined : current.reasonCode),\n\t\t});\n\t}\n\treturn projections;\n}\n\nexport interface WorkloadShardResumePlan {\n\t/** §13.5 step 3 / §23.2 property 9: passed shards are never re-run. */\n\treadonly skip: readonly string[];\n\t/** Pending shards whose dependencies all passed (§13.5 step 5). */\n\treadonly ready: readonly string[];\n\t/** Pending shards still blocked on dependencies. */\n\treadonly blocked: readonly string[];\n\t/** Failed shards awaiting the caller's retry policy (§13.5 step 4). */\n\treadonly retryable: readonly string[];\n\t/** Aborted shards that need an explicit resume decision (§13.4). */\n\treadonly resumable: readonly string[];\n\t/** Shards projected interrupted: `running` with no terminal record (§13.5 step 2). */\n\treadonly interrupted: readonly string[];\n}\n\n/** §13.5 resume projection. Pure; ordering follows plan order for determinism. */\nexport function planShardResume(\n\tplan: WorkloadShardPlan,\n\tprojections: ReadonlyMap<string, WorkloadShardProjection>,\n): WorkloadShardResumePlan {\n\tconst skip: string[] = [];\n\tconst ready: string[] = [];\n\tconst blocked: string[] = [];\n\tconst retryable: string[] = [];\n\tconst resumable: string[] = [];\n\tconst interrupted: string[] = [];\n\tconst stateOf = (id: string): WorkloadShardState => projections.get(id)?.state ?? \"pending\";\n\tfor (const shard of plan.shards) {\n\t\tswitch (stateOf(shard.shardId)) {\n\t\t\tcase \"passed\":\n\t\t\t\tskip.push(shard.shardId);\n\t\t\t\tbreak;\n\t\t\tcase \"failed\":\n\t\t\t\tretryable.push(shard.shardId);\n\t\t\t\tbreak;\n\t\t\tcase \"aborted\":\n\t\t\t\tresumable.push(shard.shardId);\n\t\t\t\tbreak;\n\t\t\t// A crash can leave `running` with no terminal record; recovery\n\t\t\t// projects it as interrupted work needing a fresh attempt.\n\t\t\tcase \"running\":\n\t\t\tcase \"interrupted\":\n\t\t\t\tinterrupted.push(shard.shardId);\n\t\t\t\tbreak;\n\t\t\tcase \"pending\":\n\t\t\t\tif (shard.dependencyIds.every((dependency) => stateOf(dependency) === \"passed\")) {\n\t\t\t\t\tready.push(shard.shardId);\n\t\t\t\t} else {\n\t\t\t\t\tblocked.push(shard.shardId);\n\t\t\t\t}\n\t\t\t\tbreak;\n\t\t\tdefault:\n\t\t\t\tbreak;\n\t\t}\n\t}\n\treturn { skip, ready, blocked, retryable, resumable, interrupted };\n}\n\nfunction basename(token: string): string {\n\tconst slash = token.lastIndexOf(\"/\");\n\treturn slash === -1 ? token : token.slice(slash + 1);\n}\n"]}

package/dist/core/workload-shard-plan.js

@@ -0,0 +1,183 @@
+import { createHash } from "node:crypto";
+/**
+ * Workload shard plan and state contracts (OMK v0.97.x roadmap §13, M5/PR8).
+ *
+ * Pure layer: plan validation, the §13.4 state machine, deterministic
+ * journal replay (reduce), and the §13.5 resume projection. No I/O here —
+ * the journal store persists lines and the M5 executor consumes the
+ * projections. §13.6: shard completion is an evidence source, never a task
+ * verdict; nothing in this module declares a task passed.
+ */
+export const WORKLOAD_SHARD_PLAN_VERSION = 1;
+/** §13.4 legal transitions. `pending` re-arms come from failed/aborted/interrupted only. */
+const LEGAL_TRANSITIONS = {
+    pending: ["running"],
+    running: ["passed", "failed", "aborted", "interrupted"],
+    failed: ["pending"],
+    aborted: ["pending"],
+    interrupted: ["pending"],
+    passed: [],
+};
+export function canTransitionShardState(from, to) {
+    return LEGAL_TRANSITIONS[from].includes(to);
+}
+/** §22.1: journals carry only the digest and a redacted descriptor, never raw argv. */
+export function buildShardCommandDescriptor(argv) {
+    const executable = basename(argv[0] ?? "");
+    const redactedArgv = argv.map((token, index) => {
+        if (index === 0) {
+            return executable;
+        }
+        if (/^-{1,2}[A-Za-z0-9][A-Za-z0-9=/:.,_-]*$/.test(token)) {
+            return token; // flags (with inline values) stay readable
+        }
+        if (/^[A-Za-z0-9_.:-]{1,32}$/.test(token) && !token.includes("..")) {
+            return token; // short bare words (subcommands, shard specs)
+        }
+        return "<redacted>"; // paths, globs, and anything possibly sensitive
+    });
+    return {
+        executable,
+        argvDigest: createHash("sha256").update(JSON.stringify(argv), "utf8").digest("hex"),
+        redactedArgv,
+    };
+}
+/** Structural plan validation: ids unique, dependencies resolvable and acyclic. */
+export function validateWorkloadShardPlan(plan) {
+    const errors = [];
+    if (plan.schemaVersion !== WORKLOAD_SHARD_PLAN_VERSION) {
+        errors.push(`plan.schemaVersion: expected ${WORKLOAD_SHARD_PLAN_VERSION}`);
+    }
+    if (!Number.isSafeInteger(plan.maxConcurrency) || plan.maxConcurrency < 1) {
+        errors.push("plan.maxConcurrency: must be a positive integer");
+    }
+    if (plan.shards.length === 0) {
+        errors.push("plan.shards: must not be empty");
+    }
+    const ids = new Set();
+    for (const shard of plan.shards) {
+        if (ids.has(shard.shardId)) {
+            errors.push(`plan.shards: duplicate shardId ${shard.shardId}`);
+        }
+        ids.add(shard.shardId);
+    }
+    for (const shard of plan.shards) {
+        for (const dependency of shard.dependencyIds) {
+            if (!ids.has(dependency)) {
+                errors.push(`plan.shards: ${shard.shardId} depends on unknown ${dependency}`);
+            }
+        }
+    }
+    if (errors.length === 0 && hasDependencyCycle(plan.shards)) {
+        errors.push("plan.shards: dependency cycle detected");
+    }
+    return errors;
+}
+function hasDependencyCycle(shards) {
+    const visiting = new Set();
+    const done = new Set();
+    const byId = new Map(shards.map((shard) => [shard.shardId, shard]));
+    const visit = (id) => {
+        if (done.has(id))
+            return false;
+        if (visiting.has(id))
+            return true;
+        visiting.add(id);
+        for (const dependency of byId.get(id)?.dependencyIds ?? []) {
+            if (visit(dependency))
+                return true;
+        }
+        visiting.delete(id);
+        done.add(id);
+        return false;
+    };
+    return shards.some((shard) => visit(shard.shardId));
+}
+export class WorkloadShardTransitionError extends Error {
+    shardId;
+    constructor(shardId, message) {
+        super(`shard ${shardId}: ${message}`);
+        this.name = "WorkloadShardTransitionError";
+        this.shardId = shardId;
+    }
+}
+/**
+ * Deterministic replay of transition records into per-shard projections
+ * (§23.2 property 10). Fail closed (§21): unknown shards, illegal §13.4
+ * transitions, or non-monotonic attempts throw instead of guessing.
+ */
+export function reduceShardRecords(plan, records) {
+    const projections = new Map();
+    for (const shard of plan.shards) {
+        projections.set(shard.shardId, { shardId: shard.shardId, state: "pending", attempt: 0, evidenceRefs: [] });
+    }
+    for (const record of records) {
+        const current = projections.get(record.shardId);
+        if (current === undefined) {
+            throw new WorkloadShardTransitionError(record.shardId, "transition for shard not in plan");
+        }
+        if (record.planId !== plan.planId) {
+            throw new WorkloadShardTransitionError(record.shardId, `record planId ${record.planId} != ${plan.planId}`);
+        }
+        if (!canTransitionShardState(current.state, record.state)) {
+            throw new WorkloadShardTransitionError(record.shardId, `illegal transition ${current.state} -> ${record.state}`);
+        }
+        const expectedAttempt = record.state === "running" ? current.attempt + 1 : current.attempt;
+        if (record.attempt !== expectedAttempt) {
+            throw new WorkloadShardTransitionError(record.shardId, `attempt ${record.attempt} != expected ${expectedAttempt} for ${record.state}`);
+        }
+        projections.set(record.shardId, {
+            shardId: record.shardId,
+            state: record.state,
+            attempt: expectedAttempt,
+            evidenceRefs: record.evidenceRefs.length > 0 ? record.evidenceRefs : current.evidenceRefs,
+            reasonCode: record.reasonCode ?? (record.state === "pending" ? undefined : current.reasonCode),
+        });
+    }
+    return projections;
+}
+/** §13.5 resume projection. Pure; ordering follows plan order for determinism. */
+export function planShardResume(plan, projections) {
+    const skip = [];
+    const ready = [];
+    const blocked = [];
+    const retryable = [];
+    const resumable = [];
+    const interrupted = [];
+    const stateOf = (id) => projections.get(id)?.state ?? "pending";
+    for (const shard of plan.shards) {
+        switch (stateOf(shard.shardId)) {
+            case "passed":
+                skip.push(shard.shardId);
+                break;
+            case "failed":
+                retryable.push(shard.shardId);
+                break;
+            case "aborted":
+                resumable.push(shard.shardId);
+                break;
+            // A crash can leave `running` with no terminal record; recovery
+            // projects it as interrupted work needing a fresh attempt.
+            case "running":
+            case "interrupted":
+                interrupted.push(shard.shardId);
+                break;
+            case "pending":
+                if (shard.dependencyIds.every((dependency) => stateOf(dependency) === "passed")) {
+                    ready.push(shard.shardId);
+                }
+                else {
+                    blocked.push(shard.shardId);
+                }
+                break;
+            default:
+                break;
+        }
+    }
+    return { skip, ready, blocked, retryable, resumable, interrupted };
+}
+function basename(token) {
+    const slash = token.lastIndexOf("/");
+    return slash === -1 ? token : token.slice(slash + 1);
+}
+//# sourceMappingURL=workload-shard-plan.js.map

package/dist/core/workload-shard-plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workload-shard-plan.js","sourceRoot":"","sources":["../../src/core/workload-shard-plan.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;;;;GAQG;AAEH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAU,CAAC;AAsCtD,6FAA4F;AAC5F,MAAM,iBAAiB,GAAwE;IAC9F,OAAO,EAAE,CAAC,SAAS,CAAC;IACpB,OAAO,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,CAAC;IACvD,MAAM,EAAE,CAAC,SAAS,CAAC;IACnB,OAAO,EAAE,CAAC,SAAS,CAAC;IACpB,WAAW,EAAE,CAAC,SAAS,CAAC;IACxB,MAAM,EAAE,EAAE;CACV,CAAC;AAEF,MAAM,UAAU,uBAAuB,CAAC,IAAwB,EAAE,EAAsB,EAAW;IAClG,OAAO,iBAAiB,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AAAA,CAC5C;AAED,wFAAuF;AACvF,MAAM,UAAU,2BAA2B,CAAC,IAAuB,EAA0C;IAC5G,MAAM,UAAU,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAC3C,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC;QAC/C,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;YACjB,OAAO,UAAU,CAAC;QACnB,CAAC;QACD,IAAI,wCAAwC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1D,OAAO,KAAK,CAAC,CAAC,2CAA2C;QAC1D,CAAC;QACD,IAAI,yBAAyB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACpE,OAAO,KAAK,CAAC,CAAC,8CAA8C;QAC7D,CAAC;QACD,OAAO,YAAY,CAAC,CAAC,gDAAgD;IAAjD,CACpB,CAAC,CAAC;IACH,OAAO;QACN,UAAU;QACV,UAAU,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;QACnF,YAAY;KACZ,CAAC;AAAA,CACF;AAED,mFAAmF;AACnF,MAAM,UAAU,yBAAyB,CAAC,IAAuB,EAAqB;IACrF,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,IAAI,CAAC,aAAa,KAAK,2BAA2B,EAAE,CAAC;QACxD,MAAM,CAAC,IAAI,CAAC,gCAAgC,2BAA2B,EAAE,CAAC,CAAC;IAC5E,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,IAAI,CAAC,cAAc,GAAG,CAAC,EAAE,CAAC;QAC3E,MAAM,CAAC,IAAI,CAAC,iDAAiD,CAAC,CAAC;IAChE,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9B,MAAM,CAAC,IAAI,CAAC,gCAAgC,CAAC,CAAC;IAC/C,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QACjC,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;YAC5B,MAAM,CAAC,IAAI,CAAC,kCAAkC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QAChE,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACxB,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QACjC,KAAK,MAAM,UAAU,IAAI,KAAK,CAAC,aAAa,EAAE,CAAC;YAC9C,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;gBAC1B,MAAM,CAAC,IAAI,CAAC,gBAAgB,KAAK,CAAC,OAAO,uBAAuB,UAAU,EAAE,CAAC,CAAC;YAC/E,CAAC;QACF,CAAC;IACF,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5D,MAAM,CAAC,IAAI,CAAC,wCAAwC,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,MAAM,CAAC;AAAA,CACd;AAED,SAAS,kBAAkB,CAAC,MAAoC,EAAW;IAC1E,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IACnC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IACpE,MAAM,KAAK,GAAG,CAAC,EAAU,EAAW,EAAE,CAAC;QACtC,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,OAAO,KAAK,CAAC;QAC/B,IAAI,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAAE,OAAO,IAAI,CAAC;QAClC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACjB,KAAK,MAAM,UAAU,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,aAAa,IAAI,EAAE,EAAE,CAAC;YAC5D,IAAI,KAAK,CAAC,UAAU,CAAC;gBAAE,OAAO,IAAI,CAAC;QACpC,CAAC;QACD,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACpB,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACb,OAAO,KAAK,CAAC;IAAA,CACb,CAAC;IACF,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;AAAA,CACpD;AAUD,MAAM,OAAO,4BAA6B,SAAQ,KAAK;IAC7C,OAAO,CAAS;IACzB,YAAY,OAAe,EAAE,OAAe,EAAE;QAC7C,KAAK,CAAC,SAAS,OAAO,KAAK,OAAO,EAAE,CAAC,CAAC;QACtC,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;QAC3C,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IAAA,CACvB;CACD;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CACjC,IAAuB,EACvB,OAAuC,EACQ;IAC/C,MAAM,WAAW,GAAG,IAAI,GAAG,EAAmC,CAAC;IAC/D,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QACjC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,EAAE,YAAY,EAAE,EAAE,EAAE,CAAC,CAAC;IAC5G,CAAC;IACD,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC9B,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAChD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC3B,MAAM,IAAI,4BAA4B,CAAC,MAAM,CAAC,OAAO,EAAE,kCAAkC,CAAC,CAAC;QAC5F,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC;YACnC,MAAM,IAAI,4BAA4B,CAAC,MAAM,CAAC,OAAO,EAAE,iBAAiB,MAAM,CAAC,MAAM,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QAC5G,CAAC;QACD,IAAI,CAAC,uBAAuB,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3D,MAAM,IAAI,4BAA4B,CACrC,MAAM,CAAC,OAAO,EACd,sBAAsB,OAAO,CAAC,KAAK,OAAO,MAAM,CAAC,KAAK,EAAE,CACxD,CAAC;QACH,CAAC;QACD,MAAM,eAAe,GAAG,MAAM,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;QAC3F,IAAI,MAAM,CAAC,OAAO,KAAK,eAAe,EAAE,CAAC;YACxC,MAAM,IAAI,4BAA4B,CACrC,MAAM,CAAC,OAAO,EACd,WAAW,MAAM,CAAC,OAAO,gBAAgB,eAAe,QAAQ,MAAM,CAAC,KAAK,EAAE,CAC9E,CAAC;QACH,CAAC;QACD,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE;YAC/B,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,OAAO,EAAE,eAAe;YACxB,YAAY,EAAE,MAAM,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC,YAAY;YACzF,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,CAAC,MAAM,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC;SAC9F,CAAC,CAAC;IACJ,CAAC;IACD,OAAO,WAAW,CAAC;AAAA,CACnB;AAiBD,mFAAkF;AAClF,MAAM,UAAU,eAAe,CAC9B,IAAuB,EACvB,WAAyD,EAC/B;IAC1B,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,MAAM,WAAW,GAAa,EAAE,CAAC;IACjC,MAAM,OAAO,GAAG,CAAC,EAAU,EAAsB,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,KAAK,IAAI,SAAS,CAAC;IAC5F,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QACjC,QAAQ,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;YAChC,KAAK,QAAQ;gBACZ,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;gBACzB,MAAM;YACP,KAAK,QAAQ;gBACZ,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;gBAC9B,MAAM;YACP,KAAK,SAAS;gBACb,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;gBAC9B,MAAM;YACP,gEAAgE;YAChE,2DAA2D;YAC3D,KAAK,SAAS,CAAC;YACf,KAAK,aAAa;gBACjB,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;gBAChC,MAAM;YACP,KAAK,SAAS;gBACb,IAAI,KAAK,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,QAAQ,CAAC,EAAE,CAAC;oBACjF,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;gBAC3B,CAAC;qBAAM,CAAC;oBACP,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;gBAC7B,CAAC;gBACD,MAAM;YACP;gBACC,MAAM;QACR,CAAC;IACF,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC;AAAA,CACnE;AAED,SAAS,QAAQ,CAAC,KAAa,EAAU;IACxC,MAAM,KAAK,GAAG,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACrC,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;AAAA,CACrD","sourcesContent":["import { createHash } from \"node:crypto\";\n\n/**\n * Workload shard plan and state contracts (OMK v0.97.x roadmap §13, M5/PR8).\n *\n * Pure layer: plan validation, the §13.4 state machine, deterministic\n * journal replay (reduce), and the §13.5 resume projection. No I/O here —\n * the journal store persists lines and the M5 executor consumes the\n * projections. §13.6: shard completion is an evidence source, never a task\n * verdict; nothing in this module declares a task passed.\n */\n\nexport const WORKLOAD_SHARD_PLAN_VERSION = 1 as const;\n\nexport interface WorkloadShardPlan {\n\treadonly schemaVersion: typeof WORKLOAD_SHARD_PLAN_VERSION;\n\treadonly planId: string;\n\treadonly promptRunId: string;\n\treadonly commandDigest: string;\n\treadonly strategy: string;\n\treadonly createdAt: string;\n\treadonly maxConcurrency: number;\n\treadonly shards: readonly WorkloadShardSpec[];\n}\n\nexport interface WorkloadShardSpec {\n\treadonly shardId: string;\n\treadonly dependencyIds: readonly string[];\n\treadonly commandDescriptor: {\n\t\treadonly executable: string;\n\t\treadonly argvDigest: string;\n\t\treadonly redactedArgv: readonly string[];\n\t};\n\treadonly expectedEvidence: readonly string[];\n}\n\nexport type WorkloadShardState = \"pending\" | \"running\" | \"passed\" | \"failed\" | \"aborted\" | \"interrupted\";\n\nexport interface WorkloadShardRecord {\n\treadonly schemaVersion: 1;\n\treadonly planId: string;\n\treadonly shardId: string;\n\treadonly attempt: number;\n\treadonly state: WorkloadShardState;\n\treadonly startedAt?: string;\n\treadonly finishedAt?: string;\n\treadonly evidenceRefs: readonly string[];\n\treadonly reasonCode?: string;\n}\n\n/** §13.4 legal transitions. `pending` re-arms come from failed/aborted/interrupted only. */\nconst LEGAL_TRANSITIONS: Readonly<Record<WorkloadShardState, readonly WorkloadShardState[]>> = {\n\tpending: [\"running\"],\n\trunning: [\"passed\", \"failed\", \"aborted\", \"interrupted\"],\n\tfailed: [\"pending\"],\n\taborted: [\"pending\"],\n\tinterrupted: [\"pending\"],\n\tpassed: [],\n};\n\nexport function canTransitionShardState(from: WorkloadShardState, to: WorkloadShardState): boolean {\n\treturn LEGAL_TRANSITIONS[from].includes(to);\n}\n\n/** §22.1: journals carry only the digest and a redacted descriptor, never raw argv. */\nexport function buildShardCommandDescriptor(argv: readonly string[]): WorkloadShardSpec[\"commandDescriptor\"] {\n\tconst executable = basename(argv[0] ?? \"\");\n\tconst redactedArgv = argv.map((token, index) => {\n\t\tif (index === 0) {\n\t\t\treturn executable;\n\t\t}\n\t\tif (/^-{1,2}[A-Za-z0-9][A-Za-z0-9=/:.,_-]*$/.test(token)) {\n\t\t\treturn token; // flags (with inline values) stay readable\n\t\t}\n\t\tif (/^[A-Za-z0-9_.:-]{1,32}$/.test(token) && !token.includes(\"..\")) {\n\t\t\treturn token; // short bare words (subcommands, shard specs)\n\t\t}\n\t\treturn \"<redacted>\"; // paths, globs, and anything possibly sensitive\n\t});\n\treturn {\n\t\texecutable,\n\t\targvDigest: createHash(\"sha256\").update(JSON.stringify(argv), \"utf8\").digest(\"hex\"),\n\t\tredactedArgv,\n\t};\n}\n\n/** Structural plan validation: ids unique, dependencies resolvable and acyclic. */\nexport function validateWorkloadShardPlan(plan: WorkloadShardPlan): readonly string[] {\n\tconst errors: string[] = [];\n\tif (plan.schemaVersion !== WORKLOAD_SHARD_PLAN_VERSION) {\n\t\terrors.push(`plan.schemaVersion: expected ${WORKLOAD_SHARD_PLAN_VERSION}`);\n\t}\n\tif (!Number.isSafeInteger(plan.maxConcurrency) || plan.maxConcurrency < 1) {\n\t\terrors.push(\"plan.maxConcurrency: must be a positive integer\");\n\t}\n\tif (plan.shards.length === 0) {\n\t\terrors.push(\"plan.shards: must not be empty\");\n\t}\n\tconst ids = new Set<string>();\n\tfor (const shard of plan.shards) {\n\t\tif (ids.has(shard.shardId)) {\n\t\t\terrors.push(`plan.shards: duplicate shardId ${shard.shardId}`);\n\t\t}\n\t\tids.add(shard.shardId);\n\t}\n\tfor (const shard of plan.shards) {\n\t\tfor (const dependency of shard.dependencyIds) {\n\t\t\tif (!ids.has(dependency)) {\n\t\t\t\terrors.push(`plan.shards: ${shard.shardId} depends on unknown ${dependency}`);\n\t\t\t}\n\t\t}\n\t}\n\tif (errors.length === 0 && hasDependencyCycle(plan.shards)) {\n\t\terrors.push(\"plan.shards: dependency cycle detected\");\n\t}\n\treturn errors;\n}\n\nfunction hasDependencyCycle(shards: readonly WorkloadShardSpec[]): boolean {\n\tconst visiting = new Set<string>();\n\tconst done = new Set<string>();\n\tconst byId = new Map(shards.map((shard) => [shard.shardId, shard]));\n\tconst visit = (id: string): boolean => {\n\t\tif (done.has(id)) return false;\n\t\tif (visiting.has(id)) return true;\n\t\tvisiting.add(id);\n\t\tfor (const dependency of byId.get(id)?.dependencyIds ?? []) {\n\t\t\tif (visit(dependency)) return true;\n\t\t}\n\t\tvisiting.delete(id);\n\t\tdone.add(id);\n\t\treturn false;\n\t};\n\treturn shards.some((shard) => visit(shard.shardId));\n}\n\nexport interface WorkloadShardProjection {\n\treadonly shardId: string;\n\treadonly state: WorkloadShardState;\n\treadonly attempt: number;\n\treadonly evidenceRefs: readonly string[];\n\treadonly reasonCode?: string;\n}\n\nexport class WorkloadShardTransitionError extends Error {\n\treadonly shardId: string;\n\tconstructor(shardId: string, message: string) {\n\t\tsuper(`shard ${shardId}: ${message}`);\n\t\tthis.name = \"WorkloadShardTransitionError\";\n\t\tthis.shardId = shardId;\n\t}\n}\n\n/**\n * Deterministic replay of transition records into per-shard projections\n * (§23.2 property 10). Fail closed (§21): unknown shards, illegal §13.4\n * transitions, or non-monotonic attempts throw instead of guessing.\n */\nexport function reduceShardRecords(\n\tplan: WorkloadShardPlan,\n\trecords: readonly WorkloadShardRecord[],\n): ReadonlyMap<string, WorkloadShardProjection> {\n\tconst projections = new Map<string, WorkloadShardProjection>();\n\tfor (const shard of plan.shards) {\n\t\tprojections.set(shard.shardId, { shardId: shard.shardId, state: \"pending\", attempt: 0, evidenceRefs: [] });\n\t}\n\tfor (const record of records) {\n\t\tconst current = projections.get(record.shardId);\n\t\tif (current === undefined) {\n\t\t\tthrow new WorkloadShardTransitionError(record.shardId, \"transition for shard not in plan\");\n\t\t}\n\t\tif (record.planId !== plan.planId) {\n\t\t\tthrow new WorkloadShardTransitionError(record.shardId, `record planId ${record.planId} != ${plan.planId}`);\n\t\t}\n\t\tif (!canTransitionShardState(current.state, record.state)) {\n\t\t\tthrow new WorkloadShardTransitionError(\n\t\t\t\trecord.shardId,\n\t\t\t\t`illegal transition ${current.state} -> ${record.state}`,\n\t\t\t);\n\t\t}\n\t\tconst expectedAttempt = record.state === \"running\" ? current.attempt + 1 : current.attempt;\n\t\tif (record.attempt !== expectedAttempt) {\n\t\t\tthrow new WorkloadShardTransitionError(\n\t\t\t\trecord.shardId,\n\t\t\t\t`attempt ${record.attempt} != expected ${expectedAttempt} for ${record.state}`,\n\t\t\t);\n\t\t}\n\t\tprojections.set(record.shardId, {\n\t\t\tshardId: record.shardId,\n\t\t\tstate: record.state,\n\t\t\tattempt: expectedAttempt,\n\t\t\tevidenceRefs: record.evidenceRefs.length > 0 ? record.evidenceRefs : current.evidenceRefs,\n\t\t\treasonCode: record.reasonCode ?? (record.state === \"pending\" ? undefined : current.reasonCode),\n\t\t});\n\t}\n\treturn projections;\n}\n\nexport interface WorkloadShardResumePlan {\n\t/** §13.5 step 3 / §23.2 property 9: passed shards are never re-run. */\n\treadonly skip: readonly string[];\n\t/** Pending shards whose dependencies all passed (§13.5 step 5). */\n\treadonly ready: readonly string[];\n\t/** Pending shards still blocked on dependencies. */\n\treadonly blocked: readonly string[];\n\t/** Failed shards awaiting the caller's retry policy (§13.5 step 4). */\n\treadonly retryable: readonly string[];\n\t/** Aborted shards that need an explicit resume decision (§13.4). */\n\treadonly resumable: readonly string[];\n\t/** Shards projected interrupted: `running` with no terminal record (§13.5 step 2). */\n\treadonly interrupted: readonly string[];\n}\n\n/** §13.5 resume projection. Pure; ordering follows plan order for determinism. */\nexport function planShardResume(\n\tplan: WorkloadShardPlan,\n\tprojections: ReadonlyMap<string, WorkloadShardProjection>,\n): WorkloadShardResumePlan {\n\tconst skip: string[] = [];\n\tconst ready: string[] = [];\n\tconst blocked: string[] = [];\n\tconst retryable: string[] = [];\n\tconst resumable: string[] = [];\n\tconst interrupted: string[] = [];\n\tconst stateOf = (id: string): WorkloadShardState => projections.get(id)?.state ?? \"pending\";\n\tfor (const shard of plan.shards) {\n\t\tswitch (stateOf(shard.shardId)) {\n\t\t\tcase \"passed\":\n\t\t\t\tskip.push(shard.shardId);\n\t\t\t\tbreak;\n\t\t\tcase \"failed\":\n\t\t\t\tretryable.push(shard.shardId);\n\t\t\t\tbreak;\n\t\t\tcase \"aborted\":\n\t\t\t\tresumable.push(shard.shardId);\n\t\t\t\tbreak;\n\t\t\t// A crash can leave `running` with no terminal record; recovery\n\t\t\t// projects it as interrupted work needing a fresh attempt.\n\t\t\tcase \"running\":\n\t\t\tcase \"interrupted\":\n\t\t\t\tinterrupted.push(shard.shardId);\n\t\t\t\tbreak;\n\t\t\tcase \"pending\":\n\t\t\t\tif (shard.dependencyIds.every((dependency) => stateOf(dependency) === \"passed\")) {\n\t\t\t\t\tready.push(shard.shardId);\n\t\t\t\t} else {\n\t\t\t\t\tblocked.push(shard.shardId);\n\t\t\t\t}\n\t\t\t\tbreak;\n\t\t\tdefault:\n\t\t\t\tbreak;\n\t\t}\n\t}\n\treturn { skip, ready, blocked, retryable, resumable, interrupted };\n}\n\nfunction basename(token: string): string {\n\tconst slash = token.lastIndexOf(\"/\");\n\treturn slash === -1 ? token : token.slice(slash + 1);\n}\n"]}

package/dist/core/workload-shard-runner.d.ts

@@ -0,0 +1,11 @@
+import type { ExecuteWorkloadShardPlanInput } from "./workload-shard-executor.ts";
+import type { WorkloadShardPlan, WorkloadShardProjection, WorkloadShardSpec, WorkloadShardState } from "./workload-shard-plan.ts";
+export declare function runOneShard(input: ExecuteWorkloadShardPlanInput, projections: Map<string, WorkloadShardProjection>, shardId: string, now: () => Date): Promise<void>;
+export declare function applyTransition(input: ExecuteWorkloadShardPlanInput, projections: Map<string, WorkloadShardProjection>, shardId: string, state: WorkloadShardState, options: {
+    readonly now: () => Date;
+    readonly startedAt?: string;
+    readonly evidenceRefs?: readonly string[];
+    readonly reasonCode?: string;
+}): void;
+export declare function shardById(plan: WorkloadShardPlan, shardId: string): WorkloadShardSpec;
+//# sourceMappingURL=workload-shard-runner.d.ts.map

package/dist/core/workload-shard-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workload-shard-runner.d.ts","sourceRoot":"","sources":["../../src/core/workload-shard-runner.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,8BAA8B,CAAC;AAClF,OAAO,KAAK,EACX,iBAAiB,EACjB,uBAAuB,EACvB,iBAAiB,EACjB,kBAAkB,EAClB,MAAM,0BAA0B,CAAC;AAElC,wBAAsB,WAAW,CAChC,KAAK,EAAE,6BAA6B,EACpC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,uBAAuB,CAAC,EACjD,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,IAAI,GACb,OAAO,CAAC,IAAI,CAAC,CAkDf;AAED,wBAAgB,eAAe,CAC9B,KAAK,EAAE,6BAA6B,EACpC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,uBAAuB,CAAC,EACjD,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,kBAAkB,EACzB,OAAO,EAAE;IACR,QAAQ,CAAC,GAAG,EAAE,MAAM,IAAI,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC7B,GACC,IAAI,CAuBN;AAYD,wBAAgB,SAAS,CAAC,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,GAAG,iBAAiB,CAMrF","sourcesContent":["import { WorkloadPermitError } from \"./workload-permit-pool.ts\";\nimport type { ExecuteWorkloadShardPlanInput } from \"./workload-shard-executor.ts\";\nimport type {\n\tWorkloadShardPlan,\n\tWorkloadShardProjection,\n\tWorkloadShardSpec,\n\tWorkloadShardState,\n} from \"./workload-shard-plan.ts\";\n\nexport async function runOneShard(\n\tinput: ExecuteWorkloadShardPlanInput,\n\tprojections: Map<string, WorkloadShardProjection>,\n\tshardId: string,\n\tnow: () => Date,\n): Promise<void> {\n\tconst shard = shardById(input.plan, shardId);\n\tlet releasePermit: (() => void) | undefined;\n\tif (input.permitPool) {\n\t\ttry {\n\t\t\tconst permit = await input.permitPool.acquire({\n\t\t\t\trequestId: `shard-${input.plan.planId}-${shardId}`,\n\t\t\t\tpromptRunId: input.plan.promptRunId,\n\t\t\t\tworkloadClass: \"heavy\",\n\t\t\t\tweight: 1,\n\t\t\t\tsignal: input.signal,\n\t\t\t\ttimeoutMs: input.permitWaitTimeoutMs ?? 120_000,\n\t\t\t});\n\t\t\treleasePermit = () => permit.release();\n\t\t} catch (error) {\n\t\t\tconst aborted = error instanceof WorkloadPermitError && error.code === \"aborted\";\n\t\t\t// Never ran: stays pending; an aborted wait is not a shard failure.\n\t\t\tif (!aborted) {\n\t\t\t\tapplyTransition(input, projections, shardId, \"running\", { now });\n\t\t\t\tapplyTransition(input, projections, shardId, \"failed\", { reasonCode: \"permit.unavailable\", now });\n\t\t\t}\n\t\t\treturn;\n\t\t}\n\t}\n\tconst startedAt = now().toISOString();\n\tapplyTransition(input, projections, shardId, \"running\", { now, startedAt });\n\ttry {\n\t\tconst result = await input.runner({\n\t\t\tshard,\n\t\t\tattempt: projections.get(shardId)?.attempt ?? 1,\n\t\t\tsignal: input.signal,\n\t\t});\n\t\tconst state = terminalStateFor(input.signal, result.exitCode);\n\t\tapplyTransition(input, projections, shardId, state, {\n\t\t\tnow,\n\t\t\tstartedAt,\n\t\t\tevidenceRefs: [`exit-code:${result.exitCode}`, ...(result.evidenceRefs ?? [])],\n\t\t\treasonCode: terminalReasonFor(state, result.exitCode),\n\t\t});\n\t} catch (error) {\n\t\tconst state: WorkloadShardState = input.signal?.aborted ? \"aborted\" : \"failed\";\n\t\tapplyTransition(input, projections, shardId, state, {\n\t\t\tnow,\n\t\t\tstartedAt,\n\t\t\treasonCode: state === \"aborted\" ? \"run.aborted\" : \"runner.error\",\n\t\t\tevidenceRefs: [`error:${String(error).slice(0, 120)}`],\n\t\t});\n\t} finally {\n\t\treleasePermit?.();\n\t}\n}\n\nexport function applyTransition(\n\tinput: ExecuteWorkloadShardPlanInput,\n\tprojections: Map<string, WorkloadShardProjection>,\n\tshardId: string,\n\tstate: WorkloadShardState,\n\toptions: {\n\t\treadonly now: () => Date;\n\t\treadonly startedAt?: string;\n\t\treadonly evidenceRefs?: readonly string[];\n\t\treadonly reasonCode?: string;\n\t},\n): void {\n\tconst current = projections.get(shardId);\n\tif (current === undefined) return;\n\tconst attempt = state === \"running\" ? current.attempt + 1 : current.attempt;\n\tconst terminal = state !== \"pending\" && state !== \"running\";\n\tinput.store.appendTransition({\n\t\tschemaVersion: 1,\n\t\tplanId: input.plan.planId,\n\t\tshardId,\n\t\tattempt,\n\t\tstate,\n\t\t...(options.startedAt !== undefined && state === \"running\" ? { startedAt: options.startedAt } : {}),\n\t\t...(terminal ? { finishedAt: options.now().toISOString() } : {}),\n\t\tevidenceRefs: options.evidenceRefs ?? [],\n\t\t...(options.reasonCode !== undefined ? { reasonCode: options.reasonCode } : {}),\n\t});\n\tprojections.set(shardId, {\n\t\tshardId,\n\t\tstate,\n\t\tattempt,\n\t\tevidenceRefs: options.evidenceRefs?.length ? options.evidenceRefs : current.evidenceRefs,\n\t\treasonCode: options.reasonCode ?? (state === \"pending\" ? undefined : current.reasonCode),\n\t});\n}\n\nfunction terminalStateFor(signal: AbortSignal | undefined, exitCode: number): WorkloadShardState {\n\tif (signal?.aborted) return \"aborted\";\n\treturn exitCode === 0 ? \"passed\" : \"failed\";\n}\n\nfunction terminalReasonFor(state: WorkloadShardState, exitCode: number): string | undefined {\n\tif (state === \"failed\") return `exit.${exitCode}`;\n\treturn state === \"aborted\" ? \"run.aborted\" : undefined;\n}\n\nexport function shardById(plan: WorkloadShardPlan, shardId: string): WorkloadShardSpec {\n\tconst shard = plan.shards.find((candidate) => candidate.shardId === shardId);\n\tif (shard === undefined) {\n\t\tthrow new Error(`shard ${shardId} not in plan ${plan.planId}`);\n\t}\n\treturn shard;\n}\n"]}

package/dist/core/workload-shard-runner.js

@@ -0,0 +1,98 @@
+import { WorkloadPermitError } from "./workload-permit-pool.js";
+export async function runOneShard(input, projections, shardId, now) {
+    const shard = shardById(input.plan, shardId);
+    let releasePermit;
+    if (input.permitPool) {
+        try {
+            const permit = await input.permitPool.acquire({
+                requestId: `shard-${input.plan.planId}-${shardId}`,
+                promptRunId: input.plan.promptRunId,
+                workloadClass: "heavy",
+                weight: 1,
+                signal: input.signal,
+                timeoutMs: input.permitWaitTimeoutMs ?? 120_000,
+            });
+            releasePermit = () => permit.release();
+        }
+        catch (error) {
+            const aborted = error instanceof WorkloadPermitError && error.code === "aborted";
+            // Never ran: stays pending; an aborted wait is not a shard failure.
+            if (!aborted) {
+                applyTransition(input, projections, shardId, "running", { now });
+                applyTransition(input, projections, shardId, "failed", { reasonCode: "permit.unavailable", now });
+            }
+            return;
+        }
+    }
+    const startedAt = now().toISOString();
+    applyTransition(input, projections, shardId, "running", { now, startedAt });
+    try {
+        const result = await input.runner({
+            shard,
+            attempt: projections.get(shardId)?.attempt ?? 1,
+            signal: input.signal,
+        });
+        const state = terminalStateFor(input.signal, result.exitCode);
+        applyTransition(input, projections, shardId, state, {
+            now,
+            startedAt,
+            evidenceRefs: [`exit-code:${result.exitCode}`, ...(result.evidenceRefs ?? [])],
+            reasonCode: terminalReasonFor(state, result.exitCode),
+        });
+    }
+    catch (error) {
+        const state = input.signal?.aborted ? "aborted" : "failed";
+        applyTransition(input, projections, shardId, state, {
+            now,
+            startedAt,
+            reasonCode: state === "aborted" ? "run.aborted" : "runner.error",
+            evidenceRefs: [`error:${String(error).slice(0, 120)}`],
+        });
+    }
+    finally {
+        releasePermit?.();
+    }
+}
+export function applyTransition(input, projections, shardId, state, options) {
+    const current = projections.get(shardId);
+    if (current === undefined)
+        return;
+    const attempt = state === "running" ? current.attempt + 1 : current.attempt;
+    const terminal = state !== "pending" && state !== "running";
+    input.store.appendTransition({
+        schemaVersion: 1,
+        planId: input.plan.planId,
+        shardId,
+        attempt,
+        state,
+        ...(options.startedAt !== undefined && state === "running" ? { startedAt: options.startedAt } : {}),
+        ...(terminal ? { finishedAt: options.now().toISOString() } : {}),
+        evidenceRefs: options.evidenceRefs ?? [],
+        ...(options.reasonCode !== undefined ? { reasonCode: options.reasonCode } : {}),
+    });
+    projections.set(shardId, {
+        shardId,
+        state,
+        attempt,
+        evidenceRefs: options.evidenceRefs?.length ? options.evidenceRefs : current.evidenceRefs,
+        reasonCode: options.reasonCode ?? (state === "pending" ? undefined : current.reasonCode),
+    });
+}
+function terminalStateFor(signal, exitCode) {
+    if (signal?.aborted)
+        return "aborted";
+    return exitCode === 0 ? "passed" : "failed";
+}
+function terminalReasonFor(state, exitCode) {
+    if (state === "failed")
+        return `exit.${exitCode}`;
+    return state === "aborted" ? "run.aborted" : undefined;
+}
+export function shardById(plan, shardId) {
+    const shard = plan.shards.find((candidate) => candidate.shardId === shardId);
+    if (shard === undefined) {
+        throw new Error(`shard ${shardId} not in plan ${plan.planId}`);
+    }
+    return shard;
+}
+//# sourceMappingURL=workload-shard-runner.js.map