@intentius/chant 0.91.0 → 0.94.0

package/src/op/activities/source-rollback.ts

@@ -0,0 +1,239 @@
+/**
+ * The rollback activities for a release a release Op shipped as a source tree
+ * (#2800): plan the rollback from the release ledger, and record it once the
+ * site serves the earlier release again.
+ *
+ * - {@link releaseRollbackPlan}: pick the release to go back to, read its plan
+ *   from `_plans/` (ws-055), archive the same directory of the same commit
+ *   again and refuse unless it hashes to the digest that plan recorded, then
+ *   write a rollback plan named by its own sha256. The rollback gate binds to
+ *   that digest. The step that restores the Machine reads the archive again,
+ *   checked against the same digest, before the Machine changes.
+ * - {@link releaseRollbackRecord}: append a release record with the restored
+ *   release's digest and commit, `restores` naming that release, the actor who
+ *   ran it and the gate's approver, the way `chant components rollback`
+ *   records one. Nothing is written when the ledger already records it.
+ *
+ * Which release: by default, the one the site served before the latest
+ * release the release Op shipped. A rollback's own record does not count as
+ * a release here, so running the rollback again plans the same rollback, its
+ * approval still holds, the Machine already serves it, and nothing is
+ * recorded twice. `to` names another release by its digest.
+ */
+
+import { execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+import type { ReleaseRecord, ReleaseRef } from "../../lifecycle/release-ledger";
+import { archiveSourceTree } from "../source-archive";
+import { readReleasePlan, releasePlan, releasePlanDigest } from "./source-release";
+
+// ── releaseRollbackPlan ───────────────────────────────────────────────────────
+
+export interface ReleaseRollbackPlanArgs {
+  /** The component the releases are recorded under. */
+  component: string;
+  /** The environment whose ledger records them. */
+  env: string;
+  /** The digest of the release to go back to. Default: the release the site served before the latest one. */
+  to?: string;
+  /**
+   * The directory the release archived, relative to the Op's working
+   * directory, for a plan that does not record `artifact.dir`.
+   */
+  path?: string;
+  /** Where plans are written. Default: `dist/plans`. */
+  dir?: string;
+  cwd?: string;
+}
+
+export interface ReleaseRollbackPlanResult {
+  /** `sha256:` of the rollback plan. The rollback gate binds to it. */
+  digest: string;
+  /** Where the rollback plan was written. */
+  file: string;
+  /** The release it goes back to: that release's plan digest, which the ledger and the Machine's metadata name. */
+  to: string;
+  /** The release it replaces. */
+  from: string;
+  /** The commit the restored release shipped. */
+  gitSha: string;
+  /** The restored release's source tree, archived again from that commit. */
+  archive: string;
+  /** Its sha256, the one the restored release's plan recorded. */
+  archiveDigest: string;
+  /** The directory the archive holds. */
+  dir: string;
+}
+
+/** A record's reference, the way `restores` and `promotedFrom` name one. */
+const refTo = (r: ReleaseRecord): ReleaseRef => ({ env: r.env, runId: r.runId, timestamp: r.timestamp });
+
+/**
+ * The release a rollback goes back to, and the release it replaces. Pure.
+ *
+ * The replaced release is the component's latest record that is not itself a
+ * rollback. By default the target is the latest record before it with another
+ * digest: what the site served before that release. With `to`, the target is
+ * the latest record with that digest.
+ */
+export function pickRollback(
+  records: ReleaseRecord[],
+  component: string,
+  env: string,
+  to?: string,
+): { target: ReleaseRecord; replaced: ReleaseRecord } | { error: string } {
+  // Ledger order, oldest first; a later append wins a tied timestamp.
+  const own = records
+    .map((r, i) => ({ r, i }))
+    .filter(({ r }) => r.component === component)
+    .sort((a, b) => (a.r.timestamp === b.r.timestamp ? a.i - b.i : a.r.timestamp < b.r.timestamp ? -1 : 1))
+    .map(({ r }) => r);
+  if (own.length === 0) return { error: `no release of "${component}" is recorded in "${env}"` };
+  const releasedAt = own.map((r) => !r.restores).lastIndexOf(true);
+  if (releasedAt < 0) return { error: `"${component}" has no release in "${env}" that was not itself a rollback` };
+  const replaced = own[releasedAt];
+  if (to !== undefined) {
+    const target = own.filter((r) => r.digest === to).at(-1);
+    if (!target) return { error: `no release of "${component}" in "${env}" has digest ${to}` };
+    return { target, replaced };
+  }
+  const target = own.slice(0, releasedAt).filter((r) => r.digest !== replaced.digest).at(-1);
+  if (!target) return { error: `"${component}" has no release in "${env}" before ${replaced.digest} to roll back to` };
+  return { target, replaced };
+}
+
+/** Plan a rollback: the earlier release, its plan, and its source tree archived again and checked against the recorded digest. */
+export async function releaseRollbackPlan(args: ReleaseRollbackPlanArgs): Promise<ReleaseRollbackPlanResult> {
+  if (!args.component || !args.env) throw new Error("releaseRollbackPlan: name the component and the environment");
+  const cwd = resolve(args.cwd ?? process.cwd());
+  const opts = { cwd };
+  const { readReleaseLedger } = await import("../../lifecycle/release-ledger");
+  const { readReleasePlan: readPersistedPlan } = await import("../../lifecycle/plan-ledger");
+
+  const picked = pickRollback((await readReleaseLedger(args.env, opts)).records, args.component, args.env, args.to);
+  if ("error" in picked) throw new Error(`releaseRollbackPlan: ${picked.error}`);
+  const { target, replaced } = picked;
+
+  // The restored release's plan, as it was approved: its content still hashes to its name.
+  const plan = await readPersistedPlan(target.digest, opts);
+  if (!plan) throw new Error(`releaseRollbackPlan: no plan is recorded for ${target.digest} (_plans/ on chant/lifecycle), so its source tree is unknown`);
+  const planDigest = releasePlanDigest(plan);
+  if (planDigest !== target.digest) throw new Error(`releaseRollbackPlan: the plan recorded for ${target.digest} hashes to ${planDigest}`);
+  const artifact = plan.artifact as { digest?: unknown; dir?: unknown } | undefined;
+  if (typeof artifact?.digest !== "string") throw new Error(`releaseRollbackPlan: the plan for ${target.digest} records no artifact digest`);
+  const gitSha = (plan.gitSha as string | undefined) ?? target.gitSha;
+
+  // The same directory of the same commit, archived again: git archive gives the same bytes.
+  let dir: string;
+  if (typeof artifact.dir === "string") {
+    const root = realpathSync(execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf-8" }).trim());
+    dir = join(root, artifact.dir);
+  } else if (args.path) {
+    dir = args.path;
+  } else {
+    throw new Error(`releaseRollbackPlan: the plan for ${target.digest} records no artifact.dir; pass path, the directory the release archived`);
+  }
+  const archive = archiveSourceTree({ dir, ref: gitSha, cwd });
+  if (archive.digest !== artifact.digest) {
+    throw new Error(
+      `releaseRollbackPlan: ${archive.dir} at ${gitSha.slice(0, 12)} archives to ${archive.digest}, not the ${artifact.digest} release ${target.digest} recorded; refusing to restore it`,
+    );
+  }
+
+  const written = await releasePlan({
+    component: args.component,
+    env: args.env,
+    gitSha,
+    content: {
+      rollback: { to: target.digest, from: replaced.digest, restores: refTo(target) },
+      artifact: { ...(plan.artifact as Record<string, unknown>), digest: archive.digest, dir: archive.dir },
+    },
+    ...(args.dir ? { dir: args.dir } : {}),
+    cwd,
+  });
+  return {
+    digest: written.digest,
+    file: written.file,
+    to: target.digest,
+    from: replaced.digest,
+    gitSha,
+    archive: archive.archive,
+    archiveDigest: archive.digest,
+    dir: archive.dir,
+  };
+}
+
+// ── releaseRollbackRecord ─────────────────────────────────────────────────────
+
+export interface ReleaseRollbackRecordArgs {
+  /** The rollback plan `releaseRollbackPlan` wrote. */
+  plan: string;
+  /** The digest the gate approved. The plan must be that one. */
+  digest?: string;
+  /** Who approved it: the resolution bound to this digest on this Op's gate is looked up. */
+  approval?: { op: string; gate: string };
+  /** Who ran the rollback. Default: GITHUB_ACTOR, GITLAB_USER_LOGIN, USER. */
+  actor?: string;
+  runId?: string;
+  cwd?: string;
+}
+
+export interface ReleaseRollbackRecordResult {
+  /** False when the ledger already recorded this rollback. */
+  recorded: boolean;
+  /** The restored release's digest, which the record carries. */
+  digest: string;
+  env: string;
+  component: string;
+  approver: string | null;
+}
+
+/** Record a rollback in the release ledger, once. */
+export async function releaseRollbackRecord(args: ReleaseRollbackRecordArgs): Promise<ReleaseRollbackRecordResult> {
+  const cwd = args.cwd;
+  const opts = cwd ? { cwd } : undefined;
+  const plan = readReleasePlan(resolve(cwd ?? process.cwd(), args.plan), args.digest);
+  const rollback = plan.rollback as { to?: string; restores?: ReleaseRef } | undefined;
+  if (!rollback?.to || !rollback.restores) throw new Error(`releaseRollbackRecord: ${args.plan} is not a rollback plan (no rollback.to)`);
+  const component = plan.component as string;
+  const env = plan.env as string;
+  const gitSha = plan.gitSha as string;
+
+  const { readReleaseLedger, latestPerComponent, appendReleaseRecord, resolveRunId } = await import("../../lifecycle/release-ledger");
+  const { pushLifecycle } = await import("../../lifecycle/git");
+
+  let approver: string | null = null;
+  if (args.approval) {
+    const { readGateLedger } = await import("../../lifecycle/gate-ledger");
+    const { resolutions } = await readGateLedger(args.approval.op, opts);
+    const bound = resolutions.filter((r) => r.gate === args.approval!.gate && r.planDigest === plan.digest);
+    approver = bound.length > 0 ? [...new Set(bound.map((r) => r.resolvedBy))].join(", ") : null;
+  }
+
+  const latest = latestPerComponent((await readReleaseLedger(env, opts)).records.filter((r) => r.component === component)).get(component);
+  if (latest?.digest === rollback.to && latest.restores?.runId === rollback.restores.runId && latest.restores.timestamp === rollback.restores.timestamp) {
+    return { recorded: false, digest: rollback.to, env, component, approver };
+  }
+
+  const actor = args.actor || process.env.GITHUB_ACTOR || process.env.GITLAB_USER_LOGIN || process.env.USER;
+  if (!actor) throw new Error("releaseRollbackRecord: no actor: pass one, or set GITHUB_ACTOR, GITLAB_USER_LOGIN or USER");
+  const { runId, runOrigin } = resolveRunId(args.runId);
+  await appendReleaseRecord(
+    {
+      component,
+      env,
+      digest: rollback.to,
+      gitSha,
+      runId,
+      ...(runOrigin ? { runOrigin } : {}),
+      timestamp: new Date().toISOString(),
+      actor,
+      ...(approver ? { approver } : {}),
+      restores: rollback.restores,
+    },
+    opts,
+  );
+  await pushLifecycle(opts);
+  return { recorded: true, digest: rollback.to, env, component, approver };
+}

package/src/op/activities/work-evidence.ts

@@ -0,0 +1,62 @@
+/**
+ * `workEvidence` (#2772): attach one piece of evidence to an acceptance
+ * criterion of the work item the run holds the lease on.
+ *
+ * Meant for an Op that declares `workLease` (#2748), a steward's among them:
+ * the builder passes the run's lease (`workLeaseOutput()`) as `lease`, and the
+ * write goes through only while that lease is still the run's, under its
+ * token. The rules are `attachWorkEvidence`'s (`../../workspace/work-evidence.ts`):
+ * the criterion must be one the record lists, and a `manual` criterion is
+ * refused, since the run holding the lease is the item's implementer.
+ * A refusal fails the step with its code.
+ */
+
+import type { EvidenceResult, WorkAcceptance } from "../../workspace/work";
+
+export interface WorkEvidenceArgs {
+  /** The run's work lease: `workLeaseOutput()`, which the builder passes. */
+  lease: { item: string; holder: string; token: string };
+  /** The criterion the evidence is for, by id. */
+  criterion: string;
+  result: EvidenceResult;
+  title: string;
+  /** A public https:// link, or */
+  url?: string;
+  /** a workspace file, pinned by the hash of its bytes now. */
+  path?: string;
+  /** The work kind file, when the declaration names more than one with the item. */
+  kind?: string;
+  /** Where the workspace is found; the run's directory by default. */
+  cwd?: string;
+}
+
+export interface WorkEvidenceResult {
+  item: string;
+  /** The work record, from the repository root. */
+  path: string;
+  evidence: Record<string, unknown>;
+  acceptance: WorkAcceptance;
+}
+
+export async function workEvidence(args: WorkEvidenceArgs): Promise<WorkEvidenceResult> {
+  const lease = args.lease;
+  if (!lease || typeof lease.item !== "string" || typeof lease.holder !== "string" || typeof lease.token !== "string") {
+    throw new Error("workEvidence runs under a work lease: pass the run's lease as `lease` (workLeaseOutput()) from an Op that declares workLease");
+  }
+  const { attachWorkEvidence } = await import("../../workspace/work-evidence");
+  const out = await attachWorkEvidence({
+    cwd: args.cwd ?? process.cwd(),
+    item: lease.item,
+    holder: lease.holder,
+    token: lease.token,
+    criterion: args.criterion,
+    result: args.result,
+    title: args.title,
+    ...(args.url !== undefined ? { url: args.url } : {}),
+    ...(args.path !== undefined ? { path: args.path } : {}),
+    ...(args.kind !== undefined ? { kind: args.kind } : {}),
+  });
+  if ("error" in out) throw new Error(`workEvidence refused for ${lease.item} ${args.criterion}: ${out.error.code}: ${out.error.message}`);
+  console.log(`workEvidence: ${out.item} ${args.criterion} ${args.result} (${out.acceptance.met}/${out.acceptance.total} met)`);
+  return { item: out.item, path: out.path, evidence: out.evidence, acceptance: out.acceptance };
+}

package/src/op/activity-contract-registry.test.ts

@@ -12,6 +12,8 @@ describe("loadActivityContracts", () => {
     expect(contracts.get("predictBehaviour")?.name).toBe("predictBehaviour");
     expect(contracts.get("behaviourFinding")?.returns).toBeDefined();
     expect(contracts.get("lifecycleDiff")?.name).toBe("lifecycleDiff");
+    // The forward coverage check over an Op's own diff (#2773).
+    expect(contracts.get("changeCoverage")?.returns).toBeDefined();
   });
 
   test("a lexicon's contracts are resolved by the same subpath convention loadActivities uses", async () => {

package/src/op/activity-contract-registry.ts

@@ -36,7 +36,7 @@
 
 import * as coreContracts from "./activities/activity-contracts";
 import { collectActivityContracts, type ActivityContract } from "./activity-contract";
-import { importLexiconModule } from "../lexicon-module";
+import { importLexiconModule, importLexiconPackage } from "../lexicon-module";
 
 /**
  * The shape {@link loadActivityContracts} reads off a plugin: an optional
@@ -89,7 +89,7 @@ export async function loadActivityContracts(
         );
       } else {
         const spec = `@intentius/chant-lexicon-${name}/op/activity-contracts`;
-        collectActivityContracts((await import(spec)) as Record<string, unknown>, contracts);
+        collectActivityContracts((await importLexiconPackage(spec)) as Record<string, unknown>, contracts);
       }
     } catch {
       // Lexicon absent or declares no contracts at the conventional subpath.

package/src/op/activity-contract.test.ts

@@ -67,6 +67,18 @@ function opWith(config: Partial<OpConfig> & Pick<OpConfig, "phases">): Pick<OpCo
   return { name: "test-op", ...config };
 }
 
+describe("validateActivitySteps() — a step's own timeout (#2787)", () => {
+  it("accepts a duration up to six hours, and flags one that is not a duration, is zero, or is longer", () => {
+    const withTimeout = (timeout: string) => opWith({ phases: [phase("Build", [activity("lifecycleDiff", { env: "prod" }, { timeout })])] });
+    const contracts = new Map([["lifecycleDiff", lifecycleDiffContract]]);
+    for (const ok of ["45m", "1h30m", "6h"]) expect(validateActivitySteps(withTimeout(ok), contracts), ok).toEqual([]);
+    for (const [bad, why] of [["forever", /not a duration/], ["45 minutes", /not a duration/], ["0m", /more than zero/], ["7h", /longer than a step may run \(6h\)/]] as const) {
+      const issues = validateActivitySteps(withTimeout(bad), contracts);
+      expect(issues.map((i) => i.message), bad).toEqual([expect.stringMatching(why)]);
+    }
+  });
+});
+
 describe("validateActivitySteps() — passing Ops", () => {
   it("returns no issues for a step matching its contract exactly", () => {
     const config = opWith({ phases: [phase("Diff", [activity("lifecycleDiff", { env: "prod", live: true })])] });

package/src/op/activity-contract.ts

@@ -41,7 +41,7 @@
 import { z } from "zod";
 import { outcomeAttributesOf } from "./types";
 import type { OpConfig, PhaseDefinition, ActivityStep, StepDefinition } from "./types";
-import { ACTIVITY_PROFILE_NAMES } from "./activity-profiles";
+import { ACTIVITY_PROFILE_NAMES, stepTimeoutProblem } from "./activity-profiles";
 
 /**
  * Every literal value {@link ActivityStep.profile} may hold, read off
@@ -237,6 +237,7 @@ export function primitiveKindOf(schema: z.ZodTypeAny): PrimitiveSchemaKind | und
  *
  * Catches the four failure classes chant #1288 names:
  *  - an unrecognized `profile` (checked against {@link KNOWN_ACTIVITY_PROFILES}, independent of whether `fn` has a contract),
+ *  - a step's own `timeout` that is not a duration, or is longer than `MAX_STEP_TIMEOUT` (#2787),
  *  - an args key the declared schema doesn't recognize,
  *  - an args value of the wrong type (including a required key that's missing),
  *  - an `outcomeAttribute.from` path that can't exist on the declared return type.
@@ -258,6 +259,10 @@ export function validateActivitySteps(
           message: `unknown profile "${step.profile}" (known: ${KNOWN_ACTIVITY_PROFILES.join(", ")})`,
         });
       }
+      if (step.timeout !== undefined) {
+        const problem = stepTimeoutProblem(step.timeout);
+        if (problem) issues.push({ opName: config.name, phase: phase.name, fn: step.fn, message: problem });
+      }
 
       const contract = contracts.get(step.fn);
       if (!contract) continue;

package/src/op/activity-profiles.ts

@@ -15,6 +15,8 @@
  * heartbeats to anything.
  */
 
+import { parseDuration } from "./duration";
+
 export interface ActivityProfile {
   /** Maximum time allowed for a single activity execution attempt (e.g. `"20m"`). */
   timeout: string;
@@ -132,3 +134,30 @@ export type ActivityProfileName = keyof typeof ACTIVITY_PROFILES;
 
 /** Every profile name, as a runtime list (`KNOWN_ACTIVITY_PROFILES`'s source). */
 export const ACTIVITY_PROFILE_NAMES = Object.keys(ACTIVITY_PROFILES) as ActivityProfileName[];
+
+/**
+ * The longest timeout one step may declare for itself (#2787): six hours, the
+ * ceiling hosted CI puts on a single job. A step's own `timeout` replaces its
+ * profile's and keeps the profile's retries, so a builder `shell` step can
+ * run 45 minutes on its one attempt. Anything that waits longer is waiting on
+ * someone, which is a gate's job (`humanGate`, 48 hours), not a step's.
+ */
+export const MAX_STEP_TIMEOUT = "6h";
+
+/** {@link MAX_STEP_TIMEOUT} in milliseconds. */
+export const MAX_STEP_TIMEOUT_MS = 6 * 3_600_000;
+
+/**
+ * Why `timeout` can't be a step's own timeout, or null when it can: it must
+ * be a duration such as `45m` or `1h30m`, more than zero, and at most
+ * {@link MAX_STEP_TIMEOUT}.
+ */
+export function stepTimeoutProblem(timeout: unknown): string | null {
+  if (typeof timeout !== "string" || !/^(\d+(ms|s|m|h|d))+$/.test(timeout)) {
+    return `timeout ${JSON.stringify(timeout)} is not a duration such as "45m" or "1h30m"`;
+  }
+  const ms = parseDuration(timeout);
+  if (ms <= 0) return `timeout "${timeout}" must be more than zero`;
+  if (ms > MAX_STEP_TIMEOUT_MS) return `timeout "${timeout}" is longer than a step may run (${MAX_STEP_TIMEOUT}); a longer wait is a gate's`;
+  return null;
+}

package/src/op/activity-registry.test.ts

@@ -26,7 +26,7 @@ describe("loadActivities", () => {
       "shellCmd", "chantBuild", "waitForStack", "lifecycleSnapshot", "lifecycleDiff",
       "httpCheck", "chantTeardown", "envTeardown", "convergeTick", "reconcilePr",
       "guardValidate", "policyGate", "workflowSupplyChainAudit", "pipelineSupplyChainAudit",
-      "lexiconUpgrade", "nativeApply",
+      "lexiconUpgrade", "nativeApply", "changeCoverage",
     ]) {
       expect(typeof a.get(fn), `${fn} should resolve from the base library`).toBe("function");
     }

package/src/op/activity-registry.ts

@@ -12,7 +12,7 @@
 
 import * as baseActivities from "./activities";
 import { ACTIVITY_PROFILES, type ActivityProfile } from "./activity-profiles";
-import { importLexiconModule } from "../lexicon-module";
+import { importLexiconModule, importLexiconPackage } from "../lexicon-module";
 
 export type { ActivityProfile } from "./activity-profiles";
 
@@ -64,7 +64,7 @@ export async function loadActivities(lexicons: string[] = []): Promise<Map<strin
         continue;
       }
       const spec = `@intentius/chant-lexicon-${name}/op/activities`;
-      collectActivities((await import(spec)) as Record<string, unknown>, activities);
+      collectActivities((await importLexiconPackage(spec)) as Record<string, unknown>, activities);
     } catch {
       // Lexicon absent or contributes no activities — fine.
     }

package/src/op/builders.ts

@@ -1,10 +1,10 @@
 import { OpResource } from "./resource";
 import { workLeaseProblems } from "./work-lease-decl";
-import type { OpConfig, PhaseDefinition, StepDefinition, ActivityStep, GateStep, EffectStep } from "./types";
+import { WORK_LEASE_STEP_ID, type OpConfig, type PhaseDefinition, type StepDefinition, type ActivityStep, type GateStep, type EffectStep } from "./types";
 import { isEffectReceipt, type EffectReceiptDeclaration } from "../effect-receipt";
 import { receiptCheckInput } from "./receipt-store";
 import { gateApprovalProblems } from "./gate-approval";
-import { makeOutProxy, type StepOutputRef, type WithStepRefs } from "./step-output-ref";
+import { makeOutProxy, stepOutput, type StepOutputRef, type WithStepRefs } from "./step-output-ref";
 import type { ChantBuildArgs } from "./activities/build";
 import type { ShellCmdArgs } from "./activities/shell";
 import type { WaitForStackArgs } from "./activities/wait";
@@ -12,8 +12,12 @@ import type { LifecycleSnapshotArgs } from "./activities/lifecycle";
 import type { ChantTeardownArgs } from "./activities/teardown";
 import type { EnvTeardownArgs } from "./activities/env-teardown";
 import type { HttpCheckArgs } from "./activities/http-check";
+import type { SourceArchiveArgs, ReleasePlanArgs, ReleaseRecordArgs } from "./activities/source-release";
+import type { ReleaseRollbackPlanArgs, ReleaseRollbackRecordArgs } from "./activities/source-rollback";
 import type { PolicyGateArgs } from "./activities/policy";
 import type { GuardValidateArgs } from "./activities/guard-validate";
+import type { WorkEvidenceArgs } from "./activities/work-evidence";
+import type { DecideArgs } from "./activities/decide";
 import { isValidCronExpression, cronSyntaxMessage } from "./cron";
 
 /** An `activity()` result — the plain `ActivityStep` shape plus the `.out` reference sugar (#1290). */
@@ -82,16 +86,18 @@ export function phase(
 export function activity(
   fn: string,
   args?: Record<string, unknown>,
-  opts?: ActivityStep["profile"] | { profile?: ActivityStep["profile"]; id?: string },
+  opts?: ActivityStep["profile"] | { profile?: ActivityStep["profile"]; id?: string; timeout?: string },
 ): NamedActivityStep {
   const profile = typeof opts === "string" ? opts : opts?.profile;
   const id = typeof opts === "string" ? undefined : opts?.id;
+  const timeout = typeof opts === "string" ? undefined : opts?.timeout;
   const step = {
     kind: "activity",
     fn,
     ...(args && Object.keys(args).length > 0 ? { args } : {}),
     ...(profile ? { profile } : {}),
     ...(id ? { id } : {}),
+    ...(timeout !== undefined ? { timeout } : {}),
   } as NamedActivityStep;
   Object.defineProperty(step, "out", {
     enumerable: false,
@@ -337,6 +343,20 @@ export const lifecycleSnapshot = (env: string, opts?: { id?: string }): NamedAct
  * shell("./smoke.sh", { env: { HOST: host.out.stdout } });
  * ```
  *
+ * With `json: true`, stdout is parsed as JSON and published as `json`
+ * (#2787), so a list or an object reaches the next step or the Op's work
+ * lease as itself. A pick step that prints `["W-3","W-7"]` hands
+ * `workLease.item` its candidates:
+ *
+ * ```ts
+ * const pick = shell("node pick.mjs", { id: "pick", json: true });
+ * Op({ workLease: { item: pick.out.json }, ... });
+ * ```
+ *
+ * `timeout` sets how long the one attempt may run, in place of the profile's
+ * twenty minutes, and keeps the profile's retries: `shell("./build.sh", {
+ * timeout: "45m" })`. At most six hours (`MAX_STEP_TIMEOUT`).
+ *
  * `cmd` stays a plain `string` and takes no references. A value spliced into
  * a command line is a quoting decision chant would then be making on the
  * author's behalf, and `env` carries the same value into the same command
@@ -344,10 +364,88 @@ export const lifecycleSnapshot = (env: string, opts?: { id?: string }): NamedAct
  */
 export const shell = (
   cmd: string,
-  opts?: WithStepRefs<Omit<ShellCmdArgs, "cmd">> & StepOpts,
+  opts?: WithStepRefs<Omit<ShellCmdArgs, "cmd">> & StepOpts & { timeout?: string },
+): NamedActivityStep => {
+  const { timeout, ...rest } = (opts ?? {}) as Record<string, unknown> & { timeout?: string };
+  const { args, profile, id } = takeProfileAndId(rest);
+  return activity("shellCmd", { cmd, ...args }, { profile: profile ?? "atMostOnce", ...(id ? { id } : {}), ...(timeout !== undefined ? { timeout } : {}) });
+};
+
+/**
+ * Archive one directory of HEAD as a release artifact (#2782): a tar written by
+ * `git archive`, named by its sha256, the same bytes for the same commit.
+ * Defaults to the `fastIdempotent` profile.
+ *
+ * ```ts
+ * const archive = sourceArchive("../app", { id: "archive" });
+ * ```
+ */
+export const sourceArchive = (
+  path: string,
+  opts?: WithStepRefs<Omit<SourceArchiveArgs, "path">> & StepOpts,
 ): NamedActivityStep => {
   const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
-  return activity("shellCmd", { cmd, ...args }, { profile: profile ?? "atMostOnce", ...(id ? { id } : {}) });
+  return activity("sourceArchive", { path, ...args }, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });
+};
+
+/**
+ * Plan a release (#2782): a JSON object named by the sha256 of its canonical
+ * form, which the ship gate binds to (`gate("ship", { plan: plan.out.digest })`)
+ * and the release ledger records. Defaults to the `fastIdempotent` profile.
+ */
+export const releasePlan = (args: WithStepRefs<ReleasePlanArgs> & StepOpts): NamedActivityStep => {
+  const { args: rest, profile, id } = takeProfileAndId(args as Record<string, unknown>);
+  return activity("releasePlan", rest, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });
+};
+
+/**
+ * Record a release in the release ledger with its plan (#2782, ws-055), once:
+ * a retry whose release the ledger already names records nothing. Defaults to
+ * the `fastIdempotent` profile.
+ */
+export const releaseRecord = (args: WithStepRefs<ReleaseRecordArgs> & StepOpts): NamedActivityStep => {
+  const { args: rest, profile, id } = takeProfileAndId(args as Record<string, unknown>);
+  return activity("releaseRecord", rest, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });
+};
+
+/**
+ * Ask a decision point and record its answer (ws-058, #2740): the `decide`
+ * activity, core's since #2828. `opts` is the activity's own
+ * {@link DecideArgs}, minus the positional `point`, so the builder and the
+ * activity cannot drift. Defaults to the `fastIdempotent` profile: asking
+ * again with the same point, declaration and inputs returns the record
+ * already written. An open question stops the run `waiting`.
+ *
+ * ```ts
+ * decide("slice-tier", { read: { "work-item": "W-002" }, subject: "W-002" })
+ * ```
+ */
+export const decide = (point: string, opts?: WithStepRefs<Omit<DecideArgs, "point">> & StepOpts): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
+  return activity("decide", { point, ...args }, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });
+};
+
+/**
+ * Plan a rollback of a source release (#2800): the release the site served
+ * before the latest one (or `to`), its plan read back from the ledger, and its
+ * source tree archived again from its commit and refused unless it hashes to
+ * the digest that plan recorded. Writes a rollback plan named by its own
+ * sha256, which the rollback gate binds to (`gate("rollback", { plan:
+ * plan.out.digest })`). Defaults to the `fastIdempotent` profile.
+ */
+export const releaseRollbackPlan = (args: WithStepRefs<ReleaseRollbackPlanArgs> & StepOpts): NamedActivityStep => {
+  const { args: rest, profile, id } = takeProfileAndId(args as Record<string, unknown>);
+  return activity("releaseRollbackPlan", rest, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });
+};
+
+/**
+ * Record a rollback in the release ledger (#2800): the restored release's
+ * digest and commit, `restores` naming that release, the actor and the gate's
+ * approver, once. Defaults to the `fastIdempotent` profile.
+ */
+export const releaseRollbackRecord = (args: WithStepRefs<ReleaseRollbackRecordArgs> & StepOpts): NamedActivityStep => {
+  const { args: rest, profile, id } = takeProfileAndId(args as Record<string, unknown>);
+  return activity("releaseRollbackRecord", rest, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });
 };
 
 /**
@@ -924,6 +1022,22 @@ export const policyGate = (opts?: WithStepRefs<PolicyGateArgs> & { id?: string }
   );
 };
 
+/**
+ * Attach evidence to an acceptance criterion of the work item the run holds
+ * the lease on (#2772), for an Op that declares `workLease`. The run's lease
+ * is passed for it, so the write happens only while the lease is still the
+ * run's. `opts` takes the `result` (pass or fail), a `title`, and a `url` or a
+ * workspace `path` to pin by hash. A `manual` criterion is refused: the run
+ * is the item's implementer. The `atMostOnce` profile: each attempt appends.
+ */
+export const workEvidence = (
+  criterion: string,
+  opts: WithStepRefs<Omit<WorkEvidenceArgs, "criterion" | "lease">> & { id?: string },
+): NamedActivityStep => {
+  const { id, ...rest } = opts as Omit<WorkEvidenceArgs, "criterion" | "lease"> & { id?: string };
+  return activity("workEvidence", { criterion, lease: stepOutput(WORK_LEASE_STEP_ID), ...rest }, { profile: "atMostOnce", ...(id ? { id } : {}) });
+};
+
 /**
  * Run an external CloudFormation Guard rules pack against the project's built
  * CloudFormation template (chant #522). `opts` is {@link GuardValidateArgs}