@bevel-software/ael 0.0.0-stage → 0.2.0

package/src/workflow/workflow-file.ts

@@ -0,0 +1,457 @@
+import { createHash } from 'node:crypto';
+import { optionalStr, plainObject, yamlDocumentOf } from '../shared/front-matter.js';
+
+/**
+ * Parses a `.workflow` file into the definition the interpreter runs.
+ *
+ * One `---` fenced YAML document with the access verbs inside it, prose after
+ * the fence. THE INTERPRETER ENCODES NO STEP BEHAVIOUR: everything a step does
+ * comes from this file. Nor does the file say WHO runs it or WHEN: the actor
+ * and the triggers are rows the platform keeps, and a comment in the file may
+ * recommend how to set them up. What used to be the pipeline's `queue:` block
+ * is now the `kb` trigger's settings.
+ *
+ * Two forms. The short form is one `prompt:` (and an optional `agent:`), the
+ * whole of a reminder or a nightly summary; it parses as a one-step workflow.
+ * The full form lists `steps:` with routing, retries and catchers.
+ */
+
+export const WORKFLOW_FILE_EXTENSION = ".workflow";
+
+// The parsed shape and its pure helpers live in definition.ts (no imports, so
+// the interpreter can load them inside Temporal's workflow sandbox); this file
+// only produces them. Re-exported so callers import one module.
+export {
+  ERROR_NAMES,
+  PERSONAL_EXECUTOR_NAME,
+  TERMINAL_TARGETS,
+  evaluate,
+  interpolate,
+  isTerminalTarget,
+  nextAfter,
+  stepByName,
+  stepSlug,
+  stripReservedKeys,
+} from './definition.js';
+export type {
+  CatchRule,
+  ChoiceRule,
+  Comparator,
+  EntryBudget,
+  Environment,
+  ErrorName,
+  ParamSource,
+  ParametersDef,
+  RequiredParam,
+  RetryRule,
+  StepDef,
+  StepKind,
+  SystemPromptSpec,
+  TerminalTarget,
+  WorkflowDefinition,
+} from './definition.js';
+import {
+  ERROR_NAMES,
+  isTerminalTarget,
+  type CatchRule,
+  type Comparator,
+  type Environment,
+  type ErrorName,
+  type ParamSource,
+  type ParametersDef,
+  type RequiredParam,
+  type RetryRule,
+  type StepDef,
+  type StepKind,
+  type SystemPromptSpec,
+  type WorkflowDefinition,
+} from './definition.js';
+
+export class WorkflowParseError extends Error {}
+
+/**
+ * Keys the design moved out of the file. Each is refused with the place it
+ * went, so an author porting a `.pipeline` learns where in one message.
+ */
+const RETIRED_KEYS: Record<string, string> = {
+  queue: 'the `kb` trigger\'s settings (who runs it, which nodes, which fields)',
+  claimAs: 'the trigger\'s owner (the actor)',
+  actor: 'the trigger\'s owner (the actor)',
+  triggers: 'trigger rows on the Triggers screen',
+  trigger: 'trigger rows on the Triggers screen',
+  branch: 'the step prompt (say which branch to write to)',
+  targetNodeTypes: 'the step prompt',
+  image: '`environment: <image reference>`',
+  setup: 'a Dockerfile named by `environment:`',
+  services: 'a Dockerfile named by `environment:` (install the service there, start it in the step)',
+  limits: 'the executor\'s settings',
+  executor: 'the run\'s start or its trigger (`executor` on Run now, `schedule_workflow` or the Triggers screen), so one workflow runs on the deployment or on a person\'s own executor',
+};
+
+/**
+ * Read the `environment` string. `none` is the in-process run; a path whose
+ * last segment is `Dockerfile` (or ends in `.Dockerfile`) is built on the
+ * executor; anything else is an image reference.
+ */
+export function environmentOf(raw: string | undefined): Environment {
+  const value = (raw ?? 'none').trim();
+  if (!value || value.toLowerCase() === 'none') return { kind: 'none' };
+  const last = value.split('/').pop() ?? value;
+  if (last === 'Dockerfile' || /\.Dockerfile$/i.test(last) || /^Dockerfile\./.test(last)) return { kind: 'dockerfile', path: value };
+  if (/\s/.test(value)) throw new WorkflowParseError(`\`environment\` "${value}" is neither \`none\`, an image reference nor a Dockerfile path`);
+  return { kind: 'image', ref: value };
+}
+
+// --- parsing ------------------------------------------------------------------
+
+function obj(value: unknown, what: string): Record<string, unknown> {
+  return plainObject(value, what, (message) => new WorkflowParseError(message));
+}
+
+function str(value: unknown, what: string): string {
+  if (typeof value !== 'string' || !value.trim()) throw new WorkflowParseError(`${what} must be a non-empty string`);
+  return value.trim();
+}
+
+function strArray(value: unknown, what: string): string[] {
+  if (!Array.isArray(value) || !value.every((v) => typeof v === 'string')) {
+    throw new WorkflowParseError(`${what} must be an array of strings`);
+  }
+  return value.map((v) => (v as string).trim()).filter(Boolean);
+}
+
+function errorNames(value: unknown, what: string): ErrorName[] {
+  const names = strArray(value, `${what}.errors`);
+  for (const n of names) {
+    if (!(ERROR_NAMES as readonly string[]).includes(n)) {
+      throw new WorkflowParseError(`${what}.errors names unknown error "${n}" (known: ${ERROR_NAMES.join(', ')})`);
+    }
+  }
+  if (names.length === 0) throw new WorkflowParseError(`${what}.errors must name at least one error`);
+  return names as ErrorName[];
+}
+
+function parseRetry(value: unknown, what: string): RetryRule[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value)) throw new WorkflowParseError(`${what} must be an array`);
+  return value.map((raw, i) => {
+    const r = obj(raw, `${what}[${i}]`);
+    const max = typeof r.max === 'number' ? r.max : NaN;
+    if (!Number.isInteger(max) || max < 0) throw new WorkflowParseError(`${what}[${i}].max must be a non-negative integer`);
+    return { errors: errorNames(r.errors, `${what}[${i}]`), max, ...(typeof r.backoff === 'number' ? { backoff: r.backoff } : {}) };
+  });
+}
+
+function parseCatch(value: unknown, what: string): CatchRule[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value)) throw new WorkflowParseError(`${what} must be an array`);
+  return value.map((raw, i) => {
+    const c = obj(raw, `${what}[${i}]`);
+    const rule: CatchRule = { errors: errorNames(c.errors, `${what}[${i}]`), then: str(c.then, `${what}[${i}].then`) };
+    if (c.max !== undefined) {
+      if (!Number.isInteger(c.max) || (c.max as number) < 1) throw new WorkflowParseError(`${what}[${i}].max must be a positive integer`);
+      rule.max = c.max as number;
+    }
+    if (c.onExhausted !== undefined) rule.onExhausted = str(c.onExhausted, `${what}[${i}].onExhausted`);
+    // The pipeline's `reauthor` budget has no reader here: a file naming it would expect a limit nothing enforces.
+    if (c.reauthor !== undefined) throw new WorkflowParseError(`${what}[${i}].reauthor is not supported; \`max\` bounds how often a catcher fires`);
+    return rule;
+  });
+}
+
+function parseParameters(value: unknown): ParametersDef {
+  if (value === undefined) return { sources: [], require: [], optional: [] };
+  const p = obj(value, '`parameters`');
+  const rawSources = p.sources ?? [];
+  if (!Array.isArray(rawSources)) throw new WorkflowParseError('`parameters.sources` must be an array');
+  const sources: ParamSource[] = rawSources.map((raw, i) => {
+    const s = obj(raw, `\`parameters.sources[${i}]\``);
+    if (s.ticket !== undefined) return { kind: 'ticket', field: str(s.ticket, `sources[${i}].ticket`) };
+    if (s.follow !== undefined) return { kind: 'follow', link: str(s.follow, `sources[${i}].follow`), field: str(s.field, `sources[${i}].field`) };
+    throw new WorkflowParseError(`\`parameters.sources[${i}]\` needs either \`ticket:\` or \`follow:\``);
+  });
+  const rawRequire = p.require ?? [];
+  if (!Array.isArray(rawRequire)) throw new WorkflowParseError('`parameters.require` must be an array');
+  const require: RequiredParam[] = rawRequire.map((raw, i) => {
+    const r = obj(raw, `\`parameters.require[${i}]\``);
+    const param: RequiredParam = { name: str(r.name, `require[${i}].name`) };
+    if (r.from !== undefined) {
+      const f = obj(r.from, `\`parameters.require[${i}].from\``);
+      param.from = { link: str(f.follow, `require[${i}].from.follow`), field: str(f.field, `require[${i}].from.field`) };
+    }
+    return param;
+  });
+  if (require.length > 0 && sources.length === 0) {
+    throw new WorkflowParseError('`parameters.require` names parameters but `parameters.sources` says nowhere to read them from');
+  }
+  return { sources, require, optional: p.optional === undefined ? [] : strArray(p.optional, '`parameters.optional`') };
+}
+
+const COMPARATORS = ['stringEquals', 'numericEquals', 'numericGreaterThan', 'numericLessThan', 'isPresent'] as const;
+
+function parseComparator(value: unknown, what: string): Comparator {
+  const c = obj(value, what);
+  const keys = Object.keys(c);
+  if (keys.length !== 1) throw new WorkflowParseError(`${what} must name exactly one comparator (${COMPARATORS.join(', ')})`);
+  const op = keys[0];
+  if (!(COMPARATORS as readonly string[]).includes(op)) {
+    throw new WorkflowParseError(`${what} names unknown comparator "${op}" (known: ${COMPARATORS.join(', ')})`);
+  }
+  const body = obj(c[op], `${what}.${op}`);
+  return { op: op as Comparator['op'], state: str(body.state, `${what}.${op}.state`), ...(body.value !== undefined ? { value: body.value } : {}) };
+}
+
+function parseThen(value: unknown, name: string): string | Record<string, string> | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value === 'string') return value.trim();
+  const t = obj(value, `step "${name}" \`then\``);
+  const map: Record<string, string> = {};
+  for (const [token, target] of Object.entries(t)) map[token] = str(target, `step "${name}" \`then.${token}\``);
+  return map;
+}
+
+function parseSystemPrompt(value: unknown, name: string): SystemPromptSpec | undefined {
+  if (value === undefined) return undefined;
+  const sp = obj(value, `step "${name}" \`systemPrompt\``);
+  const skill = optionalStr(sp.skill);
+  const extend = optionalStr(sp.extend);
+  return { ...(skill ? { skill } : {}), ...(extend ? { extend } : {}) };
+}
+
+function parseSteps(value: unknown, reservedStateKeys: string[]): StepDef[] {
+  if (!Array.isArray(value) || value.length === 0) throw new WorkflowParseError('`steps` must be a non-empty array');
+  return value.map((raw, i) => {
+    const s = obj(raw, `\`steps[${i}]\``);
+    const name = str(s.name, `\`steps[${i}].name\``);
+    const kindRaw = optionalStr(s.kind) ?? 'agent';
+    if (kindRaw !== 'agent' && kindRaw !== 'tool_chain' && kindRaw !== 'wait' && kindRaw !== 'choice') {
+      throw new WorkflowParseError(`step "${name}" has unknown kind "${kindRaw}" (expected agent | tool_chain | wait | choice)`);
+    }
+    const kind: StepKind = kindRaw;
+    for (const key of ['claimAs', 'actor', 'branch']) {
+      if (s[key] !== undefined) throw new WorkflowParseError(`step "${name}" sets \`${key}\`, which now lives in ${RETIRED_KEYS[key]}`);
+    }
+
+    const instructionsKey = kind === 'tool_chain' ? 'chain' : 'instructions';
+    const instructions =
+      kind === 'choice'
+        ? (optionalStr(s.instructions) ?? '')
+        : str(s[instructionsKey] ?? (kind === 'agent' ? s.prompt : undefined), `step "${name}" \`${instructionsKey}\``);
+
+    const step: StepDef = {
+      name,
+      index: i + 1,
+      offPath: s.offPath === true,
+      kind,
+      instructions,
+      retry: parseRetry(s.retry, `step "${name}" \`retry\``),
+      catch: parseCatch(s.catch, `step "${name}" \`catch\``),
+    };
+
+    if (s.entries !== undefined) {
+      const e = obj(s.entries, `step "${name}" \`entries\``);
+      if (typeof e.max !== 'number' || !Number.isInteger(e.max) || e.max < 1) {
+        throw new WorkflowParseError(`step "${name}" \`entries.max\` must be a positive integer`);
+      }
+      step.entries = { max: e.max, then: optionalStr(e.then) ?? 'blocked' };
+    }
+
+    if (kind === 'agent') {
+      // The configuration is optional now: absent means the deployment's
+      // default (`Agents/default.agent`), resolved by the platform at run time.
+      const agent = optionalStr(s.agent);
+      if (agent) step.agent = agent;
+      step.systemPrompt = parseSystemPrompt(s.systemPrompt, name);
+      if (!step.systemPrompt) delete step.systemPrompt;
+      step.verdict = optionalStr(s.verdict);
+      if (s.outputs !== undefined) {
+        const outputs = strArray(s.outputs, `agent step "${name}" \`outputs\``);
+        const reserved = outputs.filter((k) => reservedStateKeys.includes(k));
+        if (reserved.length > 0) {
+          throw new WorkflowParseError(`agent step "${name}" declares reserved STATE key(s) in \`outputs\`: ${reserved.join(', ')}`);
+        }
+        step.outputs = outputs;
+      }
+      step.then = parseThen(s.then, name);
+    } else if (kind === 'tool_chain') {
+      step.then = parseThen(s.then, name);
+    } else if (kind === 'wait') {
+      const outcomes = obj(s.outcomes, `wait step "${name}" \`outcomes\``);
+      const map: Record<string, string> = {};
+      for (const [token, target] of Object.entries(outcomes)) {
+        if (token === 'wait') {
+          // `wait` is the probe's way of saying "nothing yet". Declaring it as
+          // an outcome would make "keep waiting" routable.
+          throw new WorkflowParseError(`wait step "${name}" may not declare an outcome named "wait" — it is reserved`);
+        }
+        map[token] = str(target, `step "${name}" \`outcomes.${token}\``);
+      }
+      if (Object.keys(map).length === 0) throw new WorkflowParseError(`wait step "${name}" must declare at least one outcome`);
+      step.outcomes = map;
+      step.probe = optionalStr(s.probe);
+    } else {
+      const rawChoices = s.choices;
+      if (!Array.isArray(rawChoices) || rawChoices.length === 0) {
+        throw new WorkflowParseError(`choice step "${name}" must declare a non-empty \`choices\` array`);
+      }
+      step.choices = rawChoices.map((c, j) => {
+        const rule = obj(c, `step "${name}" \`choices[${j}]\``);
+        return { when: parseComparator(rule.when, `step "${name}" \`choices[${j}].when\``), then: str(rule.then, `step "${name}" \`choices[${j}].then\``) };
+      });
+      step.default = optionalStr(s.default);
+    }
+
+    if (step.then === undefined) delete step.then;
+    if (step.verdict === undefined) delete step.verdict;
+    if (step.probe === undefined) delete step.probe;
+    if (step.default === undefined) delete step.default;
+    return step;
+  });
+}
+
+/**
+ * The version a run records, and the structure it is checked against before
+ * every step: every place the
+ * file can send a run — the step order and kinds, every `then`, outcome,
+ * choice and default, every catcher's target and `onExhausted`, every entry
+ * budget's target — and nothing of the prose, since editing prose is the
+ * ordinary way to improve a workflow.
+ */
+function versionOf(steps: StepDef[], defaults: WorkflowDefinition['defaults']): string {
+  const catchers = (rules: CatchRule[] | undefined) => rules?.map((c) => ({ errors: c.errors, then: c.then, onExhausted: c.onExhausted ?? null, max: c.max ?? null })) ?? null;
+  const shape = {
+    defaults: { catch: catchers(defaults.catch) },
+    steps: steps.map((s) => ({
+      name: s.name,
+      kind: s.kind,
+      offPath: s.offPath,
+      then: s.then ?? null,
+      outcomes: s.outcomes ?? null,
+      choices: s.choices?.map((c) => c.then) ?? null,
+      default: s.default ?? null,
+      catch: catchers(s.catch),
+      entries: s.entries ? { max: s.entries.max, then: s.entries.then } : null,
+    })),
+  };
+  return createHash('sha256').update(JSON.stringify(shape)).digest('hex').slice(0, 12);
+}
+
+function idFromPath(path: string | undefined): string | undefined {
+  if (!path) return undefined;
+  const file = path.slice(path.lastIndexOf('/') + 1);
+  const base = file.endsWith(WORKFLOW_FILE_EXTENSION) ? file.slice(0, -WORKFLOW_FILE_EXTENSION.length) : file;
+  const slug = base.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  return slug || undefined;
+}
+
+/**
+ * Parse a `.workflow` file. `path`, when given, supplies the fallback id and
+ * name and appears in error messages.
+ */
+export function parseWorkflowFile(content: string, path?: string): WorkflowDefinition {
+  const where = path ? `\`.workflow\` ${path}` : '`.workflow`';
+  let document: unknown;
+  try {
+    document = yamlDocumentOf(content);
+  } catch (err) {
+    throw new WorkflowParseError(`${where} is not valid YAML: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const root = obj(document, where);
+
+  for (const [key, movedTo] of Object.entries(RETIRED_KEYS)) {
+    if (root[key] !== undefined) throw new WorkflowParseError(`${where} sets \`${key}\`, which now lives in ${movedTo}`);
+  }
+  if (root.do !== undefined && root.steps !== undefined) throw new WorkflowParseError(`${where} has both \`do\` and \`steps\`; keep \`steps\``);
+  if (root.prompt !== undefined && (root.steps !== undefined || root.do !== undefined)) {
+    throw new WorkflowParseError(`${where} has both \`prompt\` (the short form) and \`steps\`; keep one`);
+  }
+
+  const id = optionalStr(root.id) ?? idFromPath(path);
+  if (!id) throw new WorkflowParseError(`${where} needs an \`id\` (or a file name to derive one from)`);
+  const name = optionalStr(root.name) ?? id;
+  const description = optionalStr(root.description);
+  const environment = environmentOf(optionalStr(root.environment));
+  const parameters = parseParameters(root.parameters);
+  const reservedStateKeys = root.state === undefined ? [] : strArray(obj(root.state, '`state`').reserved, '`state.reserved`');
+
+  const shortForm = root.prompt !== undefined;
+  const rawSteps = shortForm
+    ? [
+        {
+          name: 'Run',
+          kind: 'agent',
+          ...(root.agent !== undefined ? { agent: root.agent } : {}),
+          instructions: str(root.prompt, `${where} \`prompt\``),
+          ...(root.verdict !== undefined ? { verdict: root.verdict } : {}),
+          ...(root.systemPrompt !== undefined ? { systemPrompt: root.systemPrompt } : {}),
+          then: 'done',
+        },
+      ]
+    : (root.steps ?? root.do);
+  if (!shortForm && root.agent !== undefined) {
+    throw new WorkflowParseError(`${where} sets a top-level \`agent\` without \`prompt\`; in the full form every agent step names its own`);
+  }
+  const steps = parseSteps(rawSteps, reservedStateKeys);
+
+  const rawDefaults = root.defaults === undefined ? {} : obj(root.defaults, '`defaults`');
+  const defaults = { retry: parseRetry(rawDefaults.retry, '`defaults.retry`') ?? [], catch: parseCatch(rawDefaults.catch, '`defaults.catch`') ?? [] };
+
+  const names = new Set<string>();
+  for (const s of steps) {
+    if (names.has(s.name)) throw new WorkflowParseError(`duplicate step name "${s.name}"`);
+    if (isTerminalTarget(s.name)) throw new WorkflowParseError(`step name "${s.name}" is a reserved terminal target`);
+    names.add(s.name);
+  }
+
+  // Every routing target must exist: a typo in a `then:` surfaces at load
+  // time, not on the one run that takes that branch. `continue` is the step
+  // after the one routing on the happy path, so an off-path step — which has
+  // no place on it — may not say it anywhere in its own routing.
+  const checkTarget = (target: string, at: string, from?: StepDef): void => {
+    if (target === 'continue') {
+      if (from?.offPath) throw new WorkflowParseError(`${at} routes to \`continue\`, which names no step off the happy path — name the step`);
+      return;
+    }
+    if (isTerminalTarget(target) || names.has(target)) return;
+    throw new WorkflowParseError(`${at} routes to unknown step "${target}"`);
+  };
+  for (const s of steps) {
+    if (typeof s.then === 'string') checkTarget(s.then, `step "${s.name}" \`then\``, s);
+    else if (s.then) for (const [t, target] of Object.entries(s.then)) checkTarget(target, `step "${s.name}" \`then.${t}\``, s);
+    for (const [t, target] of Object.entries(s.outcomes ?? {})) checkTarget(target, `step "${s.name}" \`outcomes.${t}\``, s);
+    for (const c of s.choices ?? []) checkTarget(c.then, `step "${s.name}" choice`, s);
+    if (s.default) checkTarget(s.default, `step "${s.name}" \`default\``, s);
+    for (const c of s.catch ?? []) {
+      checkTarget(c.then, `step "${s.name}" catcher`, s);
+      if (c.onExhausted) checkTarget(c.onExhausted, `step "${s.name}" catcher \`onExhausted\``, s);
+    }
+    if (s.entries) {
+      checkTarget(s.entries.then, `step "${s.name}" \`entries.then\``, s);
+      if (s.entries.then === s.name) throw new WorkflowParseError(`step "${s.name}" \`entries.then\` routes back into itself`);
+    }
+    if (s.offPath && (s.kind === 'agent' || s.kind === 'tool_chain') && s.then === undefined) {
+      throw new WorkflowParseError(`off-path step "${s.name}" must declare \`then\` — it has no implicit successor`);
+    }
+  }
+  for (const c of defaults.catch) {
+    checkTarget(c.then, '`defaults.catch`');
+    if (c.onExhausted) checkTarget(c.onExhausted, '`defaults.catch.onExhausted`');
+  }
+
+  const happyPath = steps.filter((s) => !s.offPath).map((s) => s.name);
+  if (happyPath.length === 0) throw new WorkflowParseError('every step is off-path — the happy path is empty');
+
+  return {
+    id,
+    name,
+    ...(description ? { description } : {}),
+    environment,
+    shortForm,
+    parameters,
+    reservedStateKeys,
+    defaults,
+    steps,
+    happyPath,
+    version: versionOf(steps, defaults),
+  };
+}

package/src/workitem/node.ts

@@ -0,0 +1,170 @@
+/**
+ * Reading and editing a work item: a knowledge-base node whose `# Heading`
+ * sections the interpreter keeps up to date (Status, Assignee, Log, Delivery
+ * Progress, STATE, Transcripts). Pure string functions, ported from the
+ * execution layer's board client; the platform's activities and an executor
+ * use them the same way.
+ */
+
+export type WorkItemState = Record<string, unknown>;
+
+export interface FieldNames {
+  statusField: string;
+  ownerField: string;
+  priorityField?: string;
+}
+
+export const DEFAULT_FIELDS: FieldNames = { statusField: 'Status', ownerField: 'Assignee' };
+
+export interface ParsedWorkItem {
+  path: string;
+  name: string;
+  /** The status field's first word, lowercased, backticks removed. */
+  status: string;
+  assignee: string;
+  priority: string;
+  /** The earliest date in the Log, `YYYY-MM-DD`, or empty. */
+  filedAt: string;
+  state: WorkItemState;
+  raw: string;
+}
+
+const SECTION_RE = /^# (.+?)\s*$/gm;
+
+/** `Project (link parent)` → `Project`. */
+export function headingName(heading: string): string {
+  return heading.replace(/\s*\([^)]*\)\s*$/, '').trim();
+}
+
+function sectionBounds(markdown: string, header: string): { start: number; bodyStart: number; bodyEnd: number; heading: string } | null {
+  SECTION_RE.lastIndex = 0;
+  const wanted = headingName(header);
+  let start = -1;
+  let bodyStart = -1;
+  let heading = header;
+  for (let m = SECTION_RE.exec(markdown); m; m = SECTION_RE.exec(markdown)) {
+    if (start !== -1) return { start, bodyStart, bodyEnd: m.index, heading };
+    if (headingName(m[1]) === wanted) {
+      start = m.index;
+      bodyStart = m.index + m[0].length + 1;
+      heading = m[1].trim();
+    }
+  }
+  if (start === -1) return null;
+  return { start, bodyStart: Math.min(bodyStart, markdown.length), bodyEnd: markdown.length, heading };
+}
+
+export function getSection(markdown: string, header: string): string | null {
+  const bounds = sectionBounds(markdown, header);
+  return bounds ? markdown.slice(bounds.bodyStart, bounds.bodyEnd).trim() : null;
+}
+
+export function setSection(markdown: string, header: string, body: string): string {
+  const bounds = sectionBounds(markdown, header);
+  const block = `# ${bounds?.heading ?? header}\n${body.trim()}\n`;
+  if (!bounds) return `${markdown.trimEnd()}\n\n${block}`;
+  return `${markdown.slice(0, bounds.start)}${block}${bounds.bodyEnd < markdown.length ? '\n' + markdown.slice(bounds.bodyEnd) : ''}`;
+}
+
+export function appendToSection(markdown: string, header: string, line: string): string {
+  const existing = getSection(markdown, header);
+  return setSection(markdown, header, existing ? `${existing}\n${line}` : line);
+}
+
+export function filedAtOf(markdown: string): string {
+  const dates = (getSection(markdown, 'Log') ?? '')
+    .split('\n')
+    .map((line) => /^\s*-\s*(\d{4}-\d{2}-\d{2})\b/.exec(line)?.[1])
+    .filter((d): d is string => d !== undefined);
+  return dates.length ? dates.reduce((a, b) => (a < b ? a : b)) : '';
+}
+
+export function parseState(markdown: string): WorkItemState {
+  const raw = getSection(markdown, 'STATE');
+  if (!raw) return {};
+  const m = /\{[\s\S]*\}/.exec(raw);
+  if (!m) return {};
+  try {
+    const parsed = JSON.parse(m[0]) as unknown;
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? (parsed as WorkItemState) : {};
+  } catch {
+    return {};
+  }
+}
+
+export function serializeState(state: WorkItemState): string {
+  return '```json\n' + JSON.stringify(state, null, 2) + '\n```';
+}
+
+export function parseWorkItem(path: string, markdown: string, fields: FieldNames = DEFAULT_FIELDS): ParsedWorkItem {
+  return {
+    path,
+    name: getSection(markdown, 'Name') ?? path.split('/').pop()?.replace(/\.md$/, '') ?? path,
+    status: (getSection(markdown, fields.statusField) ?? '').split(/\s/)[0].replace(/`/g, '').toLowerCase(),
+    assignee: (getSection(markdown, fields.ownerField) ?? '').trim(),
+    priority: fields.priorityField ? (getSection(markdown, fields.priorityField) ?? '').trim() : '',
+    filedAt: filedAtOf(markdown),
+    state: parseState(markdown),
+    raw: markdown,
+  };
+}
+
+/**
+ * The human-readable checklist: one line per happy-path step, the current one
+ * marked, with the failure, the blocker and the links STATE carries.
+ */
+export function renderProgress(happyPath: string[], current: string, state: WorkItemState): string {
+  const attempt = typeof state.attempt === 'number' ? state.attempt : undefined;
+  const lines: string[] = [];
+  const currentIdx = happyPath.indexOf(current);
+  const done = current === 'done';
+  for (let i = 0; i < happyPath.length; i++) {
+    const mark = done || i < currentIdx ? '✅' : i === currentIdx ? '▶️' : '⬜';
+    lines.push(`${mark} ${i + 1}. ${happyPath[i]}`);
+  }
+  const extras: string[] = [];
+  if (current === 'failed') extras.push(`❌ Failed${state.lastError ? ` — ${String(state.lastError)}` : ''}`);
+  if (current === 'blocked') extras.push(`⛔ Blocked${state.blocker ? ` — ${String(state.blocker)}` : ''}`);
+  if (current === 'cancelled') extras.push('🚫 Cancelled');
+  if (attempt !== undefined && attempt > 1) extras.push(`attempt ${attempt}`);
+  // What the run produced that a person opens: every STATE value that is a
+  // link, labelled by its key. The workflow owns the keys; nothing here knows
+  // what a delivery, a review or a release calls its links.
+  for (const [key, value] of Object.entries(state)) {
+    if (typeof value === 'string' && /^https?:\/\/\S+$/.test(value)) extras.push(`[${key}](${value})`);
+  }
+  return lines.join('\n') + (extras.length ? `\n\n${extras.join(' · ')}` : '');
+}
+
+export interface WorkItemUpdate {
+  status?: string;
+  assignee?: string;
+  state?: WorkItemState;
+  progress?: { happyPath: string[]; current: string };
+  logLine?: string;
+  /** Links to add to the Transcripts section, each once. */
+  transcriptLinks?: Array<{ label: string; href: string }>;
+  fields?: FieldNames;
+}
+
+export function applyWorkItemUpdate(markdown: string, update: WorkItemUpdate, now = new Date()): string {
+  const fields = update.fields ?? DEFAULT_FIELDS;
+  let out = markdown;
+  if (update.status !== undefined) out = setSection(out, fields.statusField, update.status);
+  if (update.assignee !== undefined) out = setSection(out, fields.ownerField, update.assignee);
+  if (update.state !== undefined) out = setSection(out, 'STATE', serializeState(update.state));
+  if (update.progress) {
+    const st = update.state ?? parseState(out);
+    out = setSection(out, 'Delivery Progress', renderProgress(update.progress.happyPath, update.progress.current, st));
+  }
+  if (update.logLine) {
+    const stamp = now.toISOString().slice(0, 16).replace('T', ' ');
+    out = appendToSection(out, 'Log', `- ${stamp} — ${update.logLine}`);
+  }
+  for (const link of update.transcriptLinks ?? []) {
+    const line = `- [${link.label}](${link.href})`;
+    const existing = getSection(out, 'Transcripts') ?? '';
+    if (!existing.includes(`](${link.href})`)) out = appendToSection(out, 'Transcripts', line);
+  }
+  return out;
+}