harnery 0.20.0 → 0.22.0

package/src/core/workflow/attempt-context.ts

@@ -0,0 +1,215 @@
+import type {
+  AcceptanceSummary,
+  WorkflowAttemptContext,
+  WorkflowAttemptFailureCause,
+  WorkflowAttemptPriorContext,
+  WorkflowAttemptUnresolvedCriterion,
+} from "./types.ts";
+import { WORKFLOW_ATTEMPT_CONTEXT_SCHEMA_VERSION } from "./types.ts";
+
+const RUN_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/;
+const ACCEPTANCE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const MAX_ATTEMPTS = 100;
+const MAX_ERROR = 2_000;
+const MAX_CRITERIA = 50;
+const MAX_STATEMENT = 500;
+const CONTEXT_FIELDS = new Set(["schema_version", "number", "trigger", "prior"]);
+const PRIOR_FIELDS = new Set(["run_id", "causes", "error", "acceptance", "unresolved"]);
+const SUMMARY_FIELDS = new Set(["satisfied", "unsatisfied", "unknown", "total"]);
+const CRITERION_FIELDS = new Set(["id", "statement", "status"]);
+const CAUSE_ORDER: readonly WorkflowAttemptFailureCause[] = [
+  "workflow_error",
+  "acceptance_unsatisfied",
+  "acceptance_unknown",
+  "lost",
+];
+
+export function normalizeWorkflowAttemptContext(value: unknown): WorkflowAttemptContext {
+  const input = objectValue(value, "workflow attempt context");
+  rejectExtraFields(input, CONTEXT_FIELDS, "workflow attempt context");
+  if (input.schema_version !== WORKFLOW_ATTEMPT_CONTEXT_SCHEMA_VERSION) {
+    throw new Error("workflow attempt context has an unsupported schema");
+  }
+  const number = safeInteger(input.number, "workflow attempt context number", 1, MAX_ATTEMPTS);
+  if (input.trigger !== "initial" && input.trigger !== "retry") {
+    throw new Error('workflow attempt context trigger must be "initial" or "retry"');
+  }
+  if (input.trigger === "initial") {
+    if (input.prior !== undefined) {
+      throw new Error("initial workflow attempt context cannot contain prior evidence");
+    }
+    return {
+      schema_version: WORKFLOW_ATTEMPT_CONTEXT_SCHEMA_VERSION,
+      number,
+      trigger: "initial",
+    };
+  }
+  if (number < 2) throw new Error("retry workflow attempt context number must be at least 2");
+  if (input.prior === undefined) {
+    throw new Error("retry workflow attempt context requires prior evidence");
+  }
+  return {
+    schema_version: WORKFLOW_ATTEMPT_CONTEXT_SCHEMA_VERSION,
+    number,
+    trigger: "retry",
+    prior: normalizePrior(input.prior),
+  };
+}
+
+export function freezeWorkflowAttemptContext(value: unknown): Readonly<WorkflowAttemptContext> {
+  const normalized = normalizeWorkflowAttemptContext(value);
+  if (normalized.prior) {
+    for (const criterion of normalized.prior.unresolved) Object.freeze(criterion);
+    Object.freeze(normalized.prior.causes);
+    Object.freeze(normalized.prior.acceptance);
+    Object.freeze(normalized.prior.unresolved);
+    Object.freeze(normalized.prior);
+  }
+  return Object.freeze(normalized);
+}
+
+export function isCanonicalWorkflowAttemptContext(value: unknown): value is WorkflowAttemptContext {
+  try {
+    const normalized = normalizeWorkflowAttemptContext(value);
+    return JSON.stringify(normalized) === JSON.stringify(value);
+  } catch {
+    return false;
+  }
+}
+
+function normalizePrior(value: unknown): WorkflowAttemptPriorContext {
+  const input = objectValue(value, "workflow attempt prior context");
+  rejectExtraFields(input, PRIOR_FIELDS, "workflow attempt prior context");
+  const runId = requiredString(input.run_id, "workflow attempt prior run id", 200);
+  if (!RUN_ID.test(runId)) {
+    throw new Error(`invalid workflow attempt prior run id ${JSON.stringify(runId)}`);
+  }
+  if (!Array.isArray(input.causes) || input.causes.length === 0) {
+    throw new Error("workflow attempt prior causes must be a non-empty array");
+  }
+  const seen = new Set<WorkflowAttemptFailureCause>();
+  for (const cause of input.causes) {
+    if (!CAUSE_ORDER.includes(cause as WorkflowAttemptFailureCause)) {
+      throw new Error(`unsupported workflow attempt failure cause ${JSON.stringify(cause)}`);
+    }
+    if (seen.has(cause as WorkflowAttemptFailureCause)) {
+      throw new Error(`duplicate workflow attempt failure cause ${JSON.stringify(cause)}`);
+    }
+    seen.add(cause as WorkflowAttemptFailureCause);
+  }
+  const causes = CAUSE_ORDER.filter((cause) => seen.has(cause));
+  if (causes.includes("lost")) {
+    if (causes.length !== 1)
+      throw new Error("lost must be the only workflow attempt failure cause");
+    if (input.error !== undefined || input.acceptance !== undefined) {
+      throw new Error("lost workflow attempt evidence cannot contain proof-derived fields");
+    }
+    const unresolved = normalizeUnresolved(input.unresolved);
+    if (unresolved.length > 0) {
+      throw new Error("lost workflow attempt evidence cannot contain unresolved criteria");
+    }
+    return { run_id: runId, causes, unresolved };
+  }
+
+  const acceptance = normalizeAcceptanceSummary(input.acceptance);
+  const unresolved = normalizeUnresolved(input.unresolved);
+  const unsatisfied = unresolved.filter((criterion) => criterion.status === "unsatisfied").length;
+  const unknown = unresolved.filter((criterion) => criterion.status === "unknown").length;
+  if (
+    unsatisfied !== acceptance.unsatisfied ||
+    unknown !== acceptance.unknown ||
+    causes.includes("acceptance_unsatisfied") !== acceptance.unsatisfied > 0 ||
+    causes.includes("acceptance_unknown") !== acceptance.unknown > 0
+  ) {
+    throw new Error("workflow attempt failure evidence does not match acceptance");
+  }
+  if (!causes.includes("workflow_error") && acceptance.unsatisfied + acceptance.unknown === 0) {
+    throw new Error("workflow attempt prior context does not describe a failure");
+  }
+  const error =
+    input.error === undefined
+      ? undefined
+      : requiredString(input.error, "workflow attempt prior error", MAX_ERROR);
+  return {
+    run_id: runId,
+    causes,
+    ...(error === undefined ? {} : { error }),
+    acceptance,
+    unresolved,
+  };
+}
+
+function normalizeAcceptanceSummary(value: unknown): AcceptanceSummary {
+  const input = objectValue(value, "workflow attempt acceptance summary");
+  rejectExtraFields(input, SUMMARY_FIELDS, "workflow attempt acceptance summary");
+  const satisfied = safeInteger(input.satisfied, "acceptance satisfied", 0, MAX_CRITERIA);
+  const unsatisfied = safeInteger(input.unsatisfied, "acceptance unsatisfied", 0, MAX_CRITERIA);
+  const unknown = safeInteger(input.unknown, "acceptance unknown", 0, MAX_CRITERIA);
+  const total = safeInteger(input.total, "acceptance total", 0, MAX_CRITERIA);
+  if (satisfied + unsatisfied + unknown !== total) {
+    throw new Error("workflow attempt acceptance summary total does not match its counts");
+  }
+  return { satisfied, unsatisfied, unknown, total };
+}
+
+function normalizeUnresolved(value: unknown): WorkflowAttemptUnresolvedCriterion[] {
+  if (!Array.isArray(value) || value.length > MAX_CRITERIA) {
+    throw new Error(
+      `workflow attempt unresolved criteria must contain at most ${MAX_CRITERIA} entries`,
+    );
+  }
+  const ids = new Set<string>();
+  return value.map((candidate, index) => {
+    const input = objectValue(candidate, `workflow attempt unresolved[${index}]`);
+    rejectExtraFields(input, CRITERION_FIELDS, `workflow attempt unresolved[${index}]`);
+    const id = requiredString(input.id, `workflow attempt unresolved[${index}].id`, 64);
+    if (!ACCEPTANCE_ID.test(id)) {
+      throw new Error(`invalid workflow attempt acceptance id ${JSON.stringify(id)}`);
+    }
+    if (ids.has(id))
+      throw new Error(`duplicate workflow attempt acceptance id ${JSON.stringify(id)}`);
+    ids.add(id);
+    if (input.status !== "unsatisfied" && input.status !== "unknown") {
+      throw new Error(`workflow attempt unresolved[${index}].status is invalid`);
+    }
+    return {
+      id,
+      statement: requiredString(
+        input.statement,
+        `workflow attempt unresolved[${index}].statement`,
+        MAX_STATEMENT,
+      ),
+      status: input.status,
+    };
+  });
+}
+
+function objectValue(value: unknown, field: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${field} must be an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function rejectExtraFields(
+  value: Record<string, unknown>,
+  allowed: ReadonlySet<string>,
+  field: string,
+): void {
+  const extra = Object.keys(value).find((key) => !allowed.has(key));
+  if (extra) throw new Error(`${field} has unknown field ${JSON.stringify(extra)}`);
+}
+
+function requiredString(value: unknown, field: string, max: number): string {
+  if (typeof value !== "string" || value.trim() === "") throw new Error(`${field} is required`);
+  const normalized = value.trim();
+  if (normalized.length > max) throw new Error(`${field} exceeds ${max} characters`);
+  return normalized;
+}
+
+function safeInteger(value: unknown, field: string, min: number, max: number): number {
+  if (!Number.isSafeInteger(value) || (value as number) < min || (value as number) > max) {
+    throw new Error(`${field} must be an integer from ${min} to ${max}`);
+  }
+  return value as number;
+}

package/src/core/workflow/engine.ts

@@ -36,6 +36,7 @@ import {
   summarizePolicyRequest,
 } from "../policy/index.ts";
 import { assertWorkflowRunId, createWorkflowApproval } from "./approvals.ts";
+import { freezeWorkflowAttemptContext } from "./attempt-context.ts";
 import { type BillingProbe, probeBilling } from "./billing.ts";
 import {
   buildWorkflowProof,
@@ -60,13 +61,16 @@ import type {
   SpawnResult,
   StageSchema,
   WorkflowAgentProof,
+  WorkflowAttemptContext,
   WorkflowContext,
   WorkflowEvidenceRecord,
   WorkflowModule,
   WorkflowProof,
+  WorkflowWorkContext,
 } from "./types.ts";
 import { WORKFLOW_PROOF_SCHEMA_VERSION } from "./types.ts";
 import { parseStageOutput, validateAgainstSchema } from "./validate.ts";
+import { freezeWorkflowWorkContext } from "./work-context.ts";
 
 const DEFAULT_MAX_AGENTS = 50;
 const DEFAULT_CONCURRENCY = 4;
@@ -110,6 +114,29 @@ export async function runWorkflow(scriptPath: string, opts: EngineOpts): Promise
   if (opts.workItemId && !/^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/.test(opts.workItemId)) {
     throw new Error(`invalid work item id ${JSON.stringify(opts.workItemId)}`);
   }
+  if (opts.resumeRunId && opts.workContext !== undefined) {
+    throw new Error("parked workflow resume uses the frozen manifest work context");
+  }
+  if (opts.resumeRunId && opts.attemptContext !== undefined) {
+    throw new Error("parked workflow resume uses the frozen manifest attempt context");
+  }
+  const requestedWorkContext =
+    opts.workContext === undefined ? undefined : freezeWorkflowWorkContext(opts.workContext);
+  const requestedAttemptContext =
+    opts.attemptContext === undefined
+      ? undefined
+      : freezeWorkflowAttemptContext(opts.attemptContext);
+  if (requestedWorkContext && !opts.workItemId) {
+    throw new Error("workflow work context requires a work item id");
+  }
+  if (requestedWorkContext && requestedWorkContext.id !== opts.workItemId) {
+    throw new Error(
+      `workflow work context ${requestedWorkContext.id} does not match work item ${opts.workItemId}`,
+    );
+  }
+  if (requestedAttemptContext && !requestedWorkContext) {
+    throw new Error("workflow attempt context requires work context");
+  }
   if (opts.resumeRunId && opts.resumeFrom) {
     throw new Error("resumeRunId and resumeFrom are mutually exclusive");
   }
@@ -123,6 +150,12 @@ export async function runWorkflow(scriptPath: string, opts: EngineOpts): Promise
   ) {
     throw new Error(`workflow run ${opts.resumeRunId} belongs to a different work item`);
   }
+  const workContext = resumeState?.manifest.work_context
+    ? freezeWorkflowWorkContext(resumeState.manifest.work_context)
+    : requestedWorkContext;
+  const attemptContext = resumeState?.manifest.attempt_context
+    ? freezeWorkflowAttemptContext(resumeState.manifest.attempt_context)
+    : requestedAttemptContext;
   const absScript = isAbsolute(scriptPath) ? scriptPath : resolve(process.cwd(), scriptPath);
   if (resumeState) {
     if (resolve(resumeState.manifest.script.path) !== resolve(absScript)) {
@@ -139,7 +172,14 @@ export async function runWorkflow(scriptPath: string, opts: EngineOpts): Promise
       // the run between the optimistic read and lease acquisition.
       assertWorkflowRunResumable(opts.coordRoot, resumeState.manifest.run_id);
     }
-    return await executeWorkflow(scriptPath, absScript, opts, resumeState);
+    return await executeWorkflow(
+      scriptPath,
+      absScript,
+      opts,
+      resumeState,
+      workContext,
+      attemptContext,
+    );
   } finally {
     releaseResumeLease?.();
   }
@@ -150,6 +190,8 @@ async function executeWorkflow(
   absScript: string,
   opts: EngineOpts,
   resumeState: ReturnType<typeof assertWorkflowRunResumable> | undefined,
+  workContext: Readonly<WorkflowWorkContext> | undefined,
+  attemptContext: Readonly<WorkflowAttemptContext> | undefined,
 ): Promise<RunReport> {
   const mod = (await import(pathToFileURL(absScript).href)) as WorkflowModule;
   if (typeof mod.default !== "function") {
@@ -198,6 +240,8 @@ async function executeWorkflow(
         schema_version: 1,
         run_id: runId,
         work_item_id: opts.workItemId,
+        work_context: workContext,
+        attempt_context: attemptContext,
         name,
         started_at: startedAt,
         script: { path: absScript, sha256: workflowScriptDigest(absScript) },
@@ -762,7 +806,16 @@ async function executeWorkflow(
     });
   };
 
-  const ctx: WorkflowContext = { agent, parallel, stage, log, evidence, authorize };
+  const ctx: WorkflowContext = {
+    work: workContext,
+    attempt: attemptContext,
+    agent,
+    parallel,
+    stage,
+    log,
+    evidence,
+    authorize,
+  };
   try {
     if (resumeState) {
       journal("run.resume", {
@@ -774,6 +827,8 @@ async function executeWorkflow(
       journal("run.start", {
         name,
         work_item_id: opts.workItemId ?? null,
+        work_context: workContext ?? null,
+        attempt_context: attemptContext ?? null,
         script: absScript,
         objective: meta.objective ?? null,
         acceptance: meta.acceptance,
@@ -800,6 +855,8 @@ async function executeWorkflow(
       proof = buildWorkflowProof({
         runId,
         workItemId: opts.workItemId ?? resumeState?.manifest.work_item_id,
+        workContext,
+        attemptContext,
         meta,
         status: "succeeded",
         startedAt,
@@ -866,6 +923,8 @@ async function executeWorkflow(
       const proof = buildWorkflowProof({
         runId,
         workItemId: opts.workItemId ?? resumeState?.manifest.work_item_id,
+        workContext,
+        attemptContext,
         meta,
         status: "failed",
         startedAt,

package/src/core/workflow/index.ts

@@ -16,6 +16,11 @@ export {
   WORKFLOW_APPROVAL_SCHEMA_VERSION,
   workflowApprovalId,
 } from "./approvals.ts";
+export {
+  freezeWorkflowAttemptContext,
+  isCanonicalWorkflowAttemptContext,
+  normalizeWorkflowAttemptContext,
+} from "./attempt-context.ts";
 export { runWorkflow, WorkflowParkedError, WorkflowRunError } from "./engine.ts";
 export {
   buildWorkflowProof,
@@ -59,6 +64,10 @@ export type {
   StageSchema,
   WorkflowAgentProof,
   WorkflowApprovalMode,
+  WorkflowAttemptContext,
+  WorkflowAttemptFailureCause,
+  WorkflowAttemptPriorContext,
+  WorkflowAttemptUnresolvedCriterion,
   WorkflowContext,
   WorkflowEvidenceInput,
   WorkflowEvidenceRecord,
@@ -71,5 +80,10 @@ export type {
   WorkflowRepoSnapshot,
   WorkflowRunStatus,
   WorkflowSpecialistProfile,
+  WorkflowWorkContext,
+} from "./types.ts";
+export {
+  WORKFLOW_ATTEMPT_CONTEXT_SCHEMA_VERSION,
+  WORKFLOW_PROOF_SCHEMA_VERSION,
+  WORKFLOW_WORK_CONTEXT_SCHEMA_VERSION,
 } from "./types.ts";
-export { WORKFLOW_PROOF_SCHEMA_VERSION } from "./types.ts";

package/src/core/workflow/proof.ts

@@ -18,6 +18,7 @@ import type {
   PolicyNetworkAccess,
 } from "../policy/index.ts";
 import { policyDigest } from "../policy/index.ts";
+import { isCanonicalWorkflowAttemptContext } from "./attempt-context.ts";
 import type {
   AcceptanceCriterion,
   AcceptanceResult,
@@ -26,6 +27,7 @@ import type {
   HarnessEvidenceCoverage,
   ResultDigest,
   WorkflowAgentProof,
+  WorkflowAttemptContext,
   WorkflowEvidenceInput,
   WorkflowEvidenceRecord,
   WorkflowMeta,
@@ -34,8 +36,10 @@ import type {
   WorkflowProofUnknown,
   WorkflowRepoEvidence,
   WorkflowRepoSnapshot,
+  WorkflowWorkContext,
 } from "./types.ts";
 import { WORKFLOW_PROOF_SCHEMA_VERSION } from "./types.ts";
+import { isCanonicalWorkflowWorkContext } from "./work-context.ts";
 
 const MAX_ACCEPTANCE_CRITERIA = 50;
 const MAX_EVIDENCE_RECORDS = 200;
@@ -59,6 +63,8 @@ export interface NormalizedWorkflowMeta {
 export interface BuildWorkflowProofInput {
   runId: string;
   workItemId?: string;
+  workContext?: Readonly<WorkflowWorkContext>;
+  attemptContext?: Readonly<WorkflowAttemptContext>;
   meta: NormalizedWorkflowMeta;
   status: "succeeded" | "failed";
   startedAt: string;
@@ -221,6 +227,8 @@ export function buildWorkflowProof(input: BuildWorkflowProofInput): WorkflowProo
       started_at: input.startedAt,
       ended_at: input.endedAt,
       duration_ms: input.durationMs,
+      work_context: input.workContext,
+      attempt_context: input.attemptContext,
       objective: input.meta.objective,
       error: clippedOptional(input.error, MAX_SUMMARY_CHARS),
       result: input.result === undefined ? undefined : digestResult(input.result),
@@ -303,7 +311,18 @@ export function readWorkflowProof(coordRoot: string, runId: string): WorkflowPro
   } catch (error) {
     throw new Error(`cannot parse workflow proof at ${path}: ${(error as Error).message}`);
   }
-  if (proof.schema_version !== WORKFLOW_PROOF_SCHEMA_VERSION || proof.run?.id !== runId) {
+  if (
+    proof.schema_version !== WORKFLOW_PROOF_SCHEMA_VERSION ||
+    proof.run?.id !== runId ||
+    (proof.run.work_context !== undefined &&
+      (!proof.run.work_item_id ||
+        proof.run.work_context.id !== proof.run.work_item_id ||
+        !isCanonicalWorkflowWorkContext(proof.run.work_context))) ||
+    (proof.run.attempt_context !== undefined &&
+      (!proof.run.work_item_id ||
+        !proof.run.work_context ||
+        !isCanonicalWorkflowAttemptContext(proof.run.attempt_context)))
+  ) {
     throw new Error(`workflow proof at ${path} has an unsupported or mismatched schema`);
   }
   return proof;

package/src/core/workflow/run-state.ts

@@ -22,8 +22,14 @@ import {
   policyDigest,
 } from "../policy/index.ts";
 import { assertWorkflowRunId, readWorkflowApproval } from "./approvals.ts";
+import { isCanonicalWorkflowAttemptContext } from "./attempt-context.ts";
 import { normalizeWorkflowSpecialists } from "./specialists.ts";
-import type { WorkflowSpecialistProfile } from "./types.ts";
+import type {
+  WorkflowAttemptContext,
+  WorkflowSpecialistProfile,
+  WorkflowWorkContext,
+} from "./types.ts";
+import { isCanonicalWorkflowWorkContext } from "./work-context.ts";
 
 export const WORKFLOW_RUN_MANIFEST_SCHEMA_VERSION = 1 as const;
 
@@ -34,6 +40,8 @@ export interface WorkflowRunManifest {
   schema_version: typeof WORKFLOW_RUN_MANIFEST_SCHEMA_VERSION;
   run_id: string;
   work_item_id?: string;
+  work_context?: WorkflowWorkContext;
+  attempt_context?: WorkflowAttemptContext;
   name: string;
   started_at: string;
   script: { path: string; sha256: string };
@@ -103,6 +111,14 @@ export function readWorkflowRunManifest(coordRoot: string, runId: string): Workf
     manifest.run_id !== runId ||
     (manifest.work_item_id !== undefined &&
       !/^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/.test(manifest.work_item_id)) ||
+    (manifest.work_context !== undefined &&
+      (!manifest.work_item_id ||
+        manifest.work_context.id !== manifest.work_item_id ||
+        !isCanonicalWorkflowWorkContext(manifest.work_context))) ||
+    (manifest.attempt_context !== undefined &&
+      (!manifest.work_item_id ||
+        !manifest.work_context ||
+        !isCanonicalWorkflowAttemptContext(manifest.attempt_context))) ||
     typeof manifest.name !== "string" ||
     manifest.name.length === 0 ||
     manifest.name.length > 200 ||

package/src/core/workflow/types.ts

@@ -20,6 +20,8 @@ import type {
 import type { BillingMode, BillingProber } from "./billing.ts";
 
 export const WORKFLOW_PROOF_SCHEMA_VERSION = 1 as const;
+export const WORKFLOW_WORK_CONTEXT_SCHEMA_VERSION = 1 as const;
+export const WORKFLOW_ATTEMPT_CONTEXT_SCHEMA_VERSION = 1 as const;
 
 export type EvidenceKind = "test" | "command" | "artifact" | "change" | "review" | "observation";
 export type EvidenceStatus = "passed" | "failed" | "observed" | "unknown";
@@ -155,6 +157,8 @@ export interface WorkflowProof {
     started_at: string;
     ended_at: string;
     duration_ms: number;
+    work_context?: WorkflowWorkContext;
+    attempt_context?: WorkflowAttemptContext;
     objective?: string;
     error?: string;
     result?: ResultDigest;
@@ -299,6 +303,12 @@ export type Spawner = (req: SpawnRequest) => Promise<SpawnResult>;
 /** The API surface injected into a workflow script's default export. Explicit
  * injection (no ambient globals): keeps scripts portable and unit-testable. */
 export interface WorkflowContext {
+  /** Frozen durable-work assignment for work-linked runs. Standalone and
+   * legacy-resumed workflows have no work context. */
+  work?: Readonly<WorkflowWorkContext>;
+  /** Frozen attempt identity and, on retry, a bounded synopsis of prior
+   * terminal evidence. Absent for standalone and legacy-resumed workflows. */
+  attempt?: Readonly<WorkflowAttemptContext>;
   /** Spawn one subagent; resolves to validated JSON (schema) or reply text. */
   agent: (prompt: string, opts?: AgentOpts) => Promise<unknown>;
   /** Run thunks with bounded concurrency; a rejected thunk resolves to null. */
@@ -326,6 +336,42 @@ export interface WorkflowModule {
   default: (ctx: WorkflowContext) => Promise<unknown>;
 }
 
+/** Minimal immutable durable-work input exposed to reusable workflow code. */
+export interface WorkflowWorkContext {
+  readonly schema_version: typeof WORKFLOW_WORK_CONTEXT_SCHEMA_VERSION;
+  readonly id: string;
+  readonly title: string;
+  readonly objective: string;
+  readonly acceptance: readonly string[];
+}
+
+export type WorkflowAttemptFailureCause =
+  | "workflow_error"
+  | "acceptance_unsatisfied"
+  | "acceptance_unknown"
+  | "lost";
+
+export interface WorkflowAttemptUnresolvedCriterion {
+  readonly id: string;
+  readonly statement: string;
+  readonly status: "unsatisfied" | "unknown";
+}
+
+export interface WorkflowAttemptPriorContext {
+  readonly run_id: string;
+  readonly causes: readonly WorkflowAttemptFailureCause[];
+  readonly error?: string;
+  readonly acceptance?: Readonly<AcceptanceSummary>;
+  readonly unresolved: readonly WorkflowAttemptUnresolvedCriterion[];
+}
+
+export interface WorkflowAttemptContext {
+  readonly schema_version: typeof WORKFLOW_ATTEMPT_CONTEXT_SCHEMA_VERSION;
+  readonly number: number;
+  readonly trigger: "initial" | "retry";
+  readonly prior?: Readonly<WorkflowAttemptPriorContext>;
+}
+
 export interface EngineOpts {
   /** Repo root whose .harnery/ receives the run journal. */
   coordRoot: string;
@@ -348,6 +394,12 @@ export interface EngineOpts {
   runId?: string;
   /** Durable objective this execution attempt belongs to. */
   workItemId?: string;
+  /** Frozen assignment data supplied by a durable-work host. Requires the
+   * matching `workItemId`; parked resume always uses the manifest copy. */
+  workContext?: WorkflowWorkContext;
+  /** Frozen attempt data supplied by a durable-work host. Requires matching
+   * work item and work contexts; parked resume uses the manifest copy. */
+  attemptContext?: WorkflowAttemptContext;
   /** Total-agent ceiling for the run (default 50): the runaway backstop. */
   maxAgents?: number;
   /** Concurrent-subagent cap for parallel() (default 4). */

package/src/core/workflow/work-context.ts

@@ -0,0 +1,66 @@
+import type { WorkflowWorkContext } from "./types.ts";
+import { WORKFLOW_WORK_CONTEXT_SCHEMA_VERSION } from "./types.ts";
+
+const WORK_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+const MAX_TITLE = 200;
+const MAX_OBJECTIVE = 4_000;
+const MAX_ACCEPTANCE = 50;
+const MAX_ACCEPTANCE_ITEM = 500;
+const FIELDS = new Set(["schema_version", "id", "title", "objective", "acceptance"]);
+
+export function normalizeWorkflowWorkContext(value: unknown): WorkflowWorkContext {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("workflow work context must be an object");
+  }
+  const input = value as Record<string, unknown>;
+  const extra = Object.keys(input).filter((key) => !FIELDS.has(key));
+  if (extra.length > 0) {
+    throw new Error(`workflow work context has unknown field ${JSON.stringify(extra[0])}`);
+  }
+  if (input.schema_version !== WORKFLOW_WORK_CONTEXT_SCHEMA_VERSION) {
+    throw new Error("workflow work context has an unsupported schema");
+  }
+  const id = requiredString(input.id, "workflow work context id", 100);
+  if (!WORK_ID.test(id)) {
+    throw new Error(`invalid workflow work context id ${JSON.stringify(id)}`);
+  }
+  if (!Array.isArray(input.acceptance) || input.acceptance.length > MAX_ACCEPTANCE) {
+    throw new Error(
+      `workflow work context acceptance must contain at most ${MAX_ACCEPTANCE} criteria`,
+    );
+  }
+  const acceptance = input.acceptance.map((criterion, index) =>
+    requiredString(criterion, `workflow work context acceptance[${index}]`, MAX_ACCEPTANCE_ITEM),
+  );
+  return {
+    schema_version: WORKFLOW_WORK_CONTEXT_SCHEMA_VERSION,
+    id,
+    title: requiredString(input.title, "workflow work context title", MAX_TITLE),
+    objective: requiredString(input.objective, "workflow work context objective", MAX_OBJECTIVE),
+    acceptance,
+  };
+}
+
+export function freezeWorkflowWorkContext(value: unknown): Readonly<WorkflowWorkContext> {
+  const normalized = normalizeWorkflowWorkContext(value);
+  Object.freeze(normalized.acceptance);
+  return Object.freeze(normalized);
+}
+
+export function isCanonicalWorkflowWorkContext(value: unknown): value is WorkflowWorkContext {
+  try {
+    const normalized = normalizeWorkflowWorkContext(value);
+    return JSON.stringify(normalized) === JSON.stringify(value);
+  } catch {
+    return false;
+  }
+}
+
+function requiredString(value: unknown, field: string, max: number): string {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${field} is required`);
+  }
+  const normalized = value.trim();
+  if (normalized.length > max) throw new Error(`${field} exceeds ${max} characters`);
+  return normalized;
+}