@intentius/chant 0.53.1 → 0.54.1

package/src/cli/commands/carve-status.ts

@@ -0,0 +1,163 @@
+/**
+ * `chant carve status` — the read over a tree of carve manifests (#2038).
+ *
+ * emit → bridge → apply each persist their step into `<target>.carve.json`
+ * (./../../terraform/manifest.ts), but until now nothing read that state back
+ * over more than one output dir at a time: a renderer wanting "what carves
+ * exist under this project, and how far along is each" had to walk the tree
+ * itself and guess at depth. This makes the walk a contract: recurse from
+ * `--from` (default: cwd), read every manifest the way bridge/apply's own
+ * `resolveCarveManifest` reads one, and answer with each manifest's target,
+ * stage, and path. Read-only — it writes nothing and touches no live resource.
+ */
+
+import { existsSync, readdirSync, statSync } from "fs";
+import { join, relative, resolve } from "path";
+import {
+  CARVE_MANIFEST_SUFFIX,
+  readCarveManifest,
+  type CarveManifest,
+} from "../../terraform/manifest";
+
+/**
+ * How far along a carve is — the highest recorded step. `planned` is a
+ * manifest holding only the boundary classification (written, but `carve
+ * emit` recorded no emit section — e.g. a hand-seeded or partially-run
+ * carve).
+ */
+export type CarveStage = "planned" | "emitted" | "bridged" | "applied";
+
+export interface CarveStatusRow {
+  /** Manifest path, relative to the walk root. */
+  path: string;
+  /** Terraform address of the carved resource. */
+  target: string;
+  /** Terraform resource type, when the manifest recorded one. */
+  tfType?: string;
+  /** The highest recorded step. */
+  stage: CarveStage;
+  /** ISO-8601 timestamp of each recorded step. */
+  at: { emit?: string; bridge?: string; apply?: string };
+  /** Emitted chant source file path(s), exactly as the manifest records them. */
+  emittedFiles?: string[];
+}
+
+export interface CarveStatusOptions {
+  /** Root of the walk (`--from`). Default: the current directory. */
+  from?: string;
+}
+
+export interface CarveStatusResult {
+  ok: boolean;
+  error?: string;
+  /** The resolved walk root. */
+  from?: string;
+  /** One row per readable manifest, sorted by path. */
+  carves?: CarveStatusRow[];
+  /** Manifest-suffixed files that did not read as a manifest (wrong version, malformed). */
+  unreadable?: string[];
+}
+
+/**
+ * Directories that never hold a carve output dir and make the walk expensive
+ * or wrong: dependency trees, VCS internals, build output.
+ */
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", ".chant"]);
+
+/** Every `*.carve.json` under `root`, found by a bounded recursive walk. */
+function findManifests(root: string): string[] {
+  const found: string[] = [];
+  const walk = (dir: string): void => {
+    let entries: string[];
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return; // unreadable dir — skip rather than fail the whole status
+    }
+    for (const entry of entries.sort()) {
+      if (SKIP_DIRS.has(entry)) continue;
+      const path = join(dir, entry);
+      let stat;
+      try {
+        stat = statSync(path);
+      } catch {
+        continue; // dangling symlink
+      }
+      if (stat.isDirectory()) walk(path);
+      else if (entry.endsWith(CARVE_MANIFEST_SUFFIX)) found.push(path);
+    }
+  };
+  walk(root);
+  return found;
+}
+
+function stageOf(manifest: CarveManifest): CarveStage {
+  if (manifest.apply) return "applied";
+  if (manifest.bridge) return "bridged";
+  if (manifest.emit) return "emitted";
+  return "planned";
+}
+
+export function carveStatus(opts: CarveStatusOptions = {}): CarveStatusResult {
+  const root = resolve(opts.from ?? process.cwd());
+  if (!existsSync(root) || !statSync(root).isDirectory()) {
+    return { ok: false, error: `Not a directory: ${root}` };
+  }
+
+  const carves: CarveStatusRow[] = [];
+  const unreadable: string[] = [];
+  for (const path of findManifests(root)) {
+    const rel = relative(root, path);
+    const manifest = readCarveManifest(path);
+    if (!manifest) {
+      unreadable.push(rel);
+      continue;
+    }
+    carves.push({
+      path: rel,
+      target: manifest.target,
+      ...(manifest.tfType ? { tfType: manifest.tfType } : {}),
+      stage: stageOf(manifest),
+      at: {
+        ...(manifest.emit?.at ? { emit: manifest.emit.at } : {}),
+        ...(manifest.bridge?.at ? { bridge: manifest.bridge.at } : {}),
+        ...(manifest.apply?.at ? { apply: manifest.apply.at } : {}),
+      },
+      ...(manifest.emit ? { emittedFiles: manifest.emit.files } : {}),
+    });
+  }
+
+  return { ok: true, from: root, carves, ...(unreadable.length > 0 ? { unreadable } : {}) };
+}
+
+/** The JSON payload `--json` emits — everything but `ok`. */
+export function carveStatusJson(result: CarveStatusResult): Record<string, unknown> {
+  return {
+    from: result.from,
+    carves: result.carves ?? [],
+    ...(result.unreadable ? { unreadable: result.unreadable } : {}),
+  };
+}
+
+export function formatCarveStatus(result: CarveStatusResult): string {
+  const carves = result.carves ?? [];
+  if (carves.length === 0) {
+    return `No carve manifests under ${result.from} — run \`chant carve emit\` first.`;
+  }
+  const L: string[] = [];
+  L.push(`${carves.length} carve${carves.length === 1 ? "" : "s"} under ${result.from}`);
+  L.push("");
+  for (const row of carves) {
+    const when = row.at.apply ?? row.at.bridge ?? row.at.emit;
+    L.push(`  ${row.target}  [${row.stage}${when ? ` @ ${when}` : ""}]`);
+    L.push(`    manifest: ${row.path}`);
+    if (row.emittedFiles && row.emittedFiles.length > 0) {
+      L.push(`    emitted:  ${row.emittedFiles.join(", ")}`);
+    }
+  }
+  if (result.unreadable && result.unreadable.length > 0) {
+    L.push("");
+    L.push(`  Unreadable (malformed or unknown version): ${result.unreadable.join(", ")}`);
+  }
+  return L.join("\n");
+}

package/src/cli/handlers/carve-status.ts

@@ -0,0 +1,30 @@
+import { carveStatus, carveStatusJson, formatCarveStatus } from "../commands/carve-status";
+import { formatError } from "../format";
+import type { CommandContext } from "../registry";
+
+/**
+ * `chant carve status [--from <dir>] [--json]` — the read-only status read
+ * over a tree of carve manifests (#2038). Walks from `--from` (default: cwd),
+ * reports every manifest's target, stage (planned/emitted/bridged/applied)
+ * and path. No plugins, no project, no cloud call.
+ */
+export async function runCarveStatus(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+
+  const result = carveStatus({ from: args.migrateFrom /* `--from <dir>` */ });
+
+  if (!result.ok) {
+    console.error(formatError({
+      message: result.error ?? "carve status failed",
+      hint: "chant carve status --from ./tf --json",
+    }));
+    return 1;
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify(carveStatusJson(result), null, 2));
+  } else {
+    console.log(formatCarveStatus(result));
+  }
+  return 0;
+}

package/src/cli/handlers/components.ts

@@ -34,6 +34,7 @@ import {
   readReleaseLedger,
   listReleaseEnvironments,
   latestPerComponent,
+  resolveRunId,
   InvalidReleaseRecordError,
 } from "../../lifecycle/release-ledger";
 import { reconcileStatus, liveEvidenceFromChangeSet, compareAcrossEnvironments, mergeLiveEvidence, type LiveComponentEvidence } from "../../lifecycle/status";
@@ -94,7 +95,9 @@ export async function runComponentsReleaseRecord(ctx: CommandContext): Promise<n
   }
 
   const gitSha = args.gitSha ?? (await getHeadCommit().catch(() => undefined));
-  const runId = args.runId ?? process.env.GITHUB_RUN_ID ?? process.env.CI_PIPELINE_ID ?? `local-${Date.now()}`;
+  // Id + origin resolved together from the same environment (#2045), so the
+  // recorded runId always says which id space it lives in and how to reach it.
+  const { runId, runOrigin } = resolveRunId(args.runId);
   const actor = args.actor ?? process.env.GITHUB_ACTOR ?? process.env.GITLAB_USER_LOGIN ?? process.env.USER;
   // Who approved a gated change (#1035). Optional — omitted for an ungated
   // change, and never defaulted to `actor`, since recording the approver as the
@@ -122,6 +125,7 @@ export async function runComponentsReleaseRecord(ctx: CommandContext): Promise<n
       digest,
       gitSha,
       runId,
+      ...(runOrigin ? { runOrigin } : {}),
       timestamp,
       actor,
       ...(approver ? { approver } : {}),

package/src/cli/handlers/graph.ts

@@ -635,6 +635,9 @@ async function buildPipelineProjection(
     success: true,
     pipeline: {
       provider: lexicon,
+      // The environment the projected pipeline deploys (#2046) — the
+      // generator's own resolution, carried rather than re-derived.
+      ...(result.env ? { env: result.env } : {}),
       stages: result.stages ?? [],
       nodes: jobs.map((j) => ({ id: j.jobName, kind: "CIJob" as const, component: j.component, stage: j.stage })),
       edges: jobs.flatMap((j) => j.needs.map((dep) => ({ from: j.jobName, to: dep, kind: "needs" as const }))),

package/src/cli/handlers/run.ts

@@ -655,6 +655,8 @@ async function recordAutoReleasesForRun(
         success: true,
         records: componentResult.records,
         runId,
+        // A local-executor id resolves nowhere — say so in a field (#2045).
+        runOrigin: { forge: "local" },
       },
       { disabled },
     );
@@ -1030,7 +1032,8 @@ async function runComponentTemporal(
     const disabled = resolveAutoReleaseDisabled(config, ctx.args.noReleaseRecord);
     const env = ctx.args.env ?? "local";
     const outcome = await maybeRecordAutoRelease(
-      { component: component.name, env, success: true, digest, runId: finalDesc.runId },
+      // A Temporal workflow run id lives in the orchestrator's id space (#2045).
+      { component: component.name, env, success: true, digest, runId: finalDesc.runId, runOrigin: { forge: "op" } },
       { disabled },
     );
     if (!outcome.recorded && outcome.reason === "error") {

package/src/cli/main.ts

@@ -23,6 +23,7 @@ import { runCarveAdvise, runCarveUnknown } from "./handlers/carve";
 import { runCarveEmit } from "./handlers/carve-emit";
 import { runCarveBridge } from "./handlers/carve-bridge";
 import { runCarveApply } from "./handlers/carve-apply";
+import { runCarveStatus } from "./handlers/carve-status";
 import { runLifecycleSnapshot, runLifecycleShow, runLifecycleDiff, runLifecycleRollback, runLifecyclePlan, runLifecycleAffected, runLifecycleLog, runLifecycleTeardown, runLifecycleWhoami, runLifecycleUnknown } from "./handlers/lifecycle";
 import { runComponentsStatus, runComponentsReleaseRecord, runComponentsExport, runComponentsUnknown } from "./handlers/components";
 import { runScenarioCheck, runScenarioUnknown } from "./handlers/scenario";
@@ -498,6 +499,10 @@ Commands:
                         --env <env>       is optional with a carve manifest present.
                                           --write-source stamps the ownership marker
                                           into the emitted chant source.
+  carve status          Status read over a tree of carve manifests: every
+                        [--from <dir>]    *.carve.json under --from (default: cwd) with
+                        (--json)          its target, stage (planned/emitted/bridged/
+                                          applied) and path. Read-only.
 
 Ops:
   run <name>            Start an Op workflow (spawns worker + submits to Temporal)
@@ -872,6 +877,9 @@ const registry: CommandDef[] = [
   // Apply graduation (#197): ownership marker + finalized apply runbook.
   // BYOL-honest — no cloud call; --write saves the graduation doc.
   { name: "carve apply", handler: runCarveApply },
+  // Status read over a tree of carve manifests (#2038): the contract a
+  // renderer replaces its own walk-and-guess discovery with. Read-only.
+  { name: "carve status", handler: runCarveStatus },
   { name: "init", handler: runInit },
   { name: "init lexicon", handler: runInitLexicon },
 { name: "update", handler: runUpdate },

package/src/components/auto-release.ts

@@ -30,7 +30,7 @@
  * env vars, timestamp is a real `new Date()` taken at record time).
  */
 import { getHeadCommit, pushLifecycle, StaleLifecycleBranchError } from "../lifecycle/git";
-import { appendReleaseRecord, InvalidReleaseRecordError, type ReleaseRecord } from "../lifecycle/release-ledger";
+import { appendReleaseRecord, InvalidReleaseRecordError, type ReleaseRecord, type RunOrigin } from "../lifecycle/release-ledger";
 import type { DriverStepRecord } from "./driver";
 
 /**
@@ -117,6 +117,8 @@ export interface AutoReleaseRunInfo {
   digest?: string;
   /** Orchestrator run identifier — a Temporal `runId`, or a locally generated id for the local executor (mirrors `runComponentsReleaseRecord`'s `--run-id` default). */
   runId: string;
+  /** The id space `runId` lives in (#2045) — `{ forge: "op" }` for a Temporal run, `{ forge: "local" }` for a local-executor mint. Recorded verbatim as the release record's `runOrigin`. */
+  runOrigin?: RunOrigin;
   /** The bypassed capability-profile divergences, when the caller deliberately overrode a deploy-time profile assertion (chant #1244) — recorded verbatim as the release record's `profileOverride`. */
   profileOverride?: string;
   /** The deploy's input-side digest, when `digest` is a rendered-content identity (a pinned helm deploy, chant #1242) — recorded as the release record's `inputDigest` so ledger queries can still join on inputs across clusters whose bytes legitimately differ. */
@@ -204,6 +206,7 @@ export async function maybeRecordAutoRelease(
         digest,
         gitSha,
         runId: run.runId,
+        ...(run.runOrigin ? { runOrigin: run.runOrigin } : {}),
         timestamp,
         actor,
         ...(run.profileOverride ? { profileOverride: run.profileOverride } : {}),

package/src/components/cli-support.ts

@@ -218,6 +218,8 @@ export interface GenerateComponentsResult {
   stages?: string[];
   /** Every generated job, for a machine-readable view (`--format json`). */
   jobs?: Array<{ jobName: string; component: string; stage: string; needs: string[] }>;
+  /** The environment the pipeline deploys — the generator's own resolution (`ComponentPipelineResult.env`, #2046). */
+  env?: string;
   error?: string;
   /** This invocation's resolved build-time parameters (chant #1108) — the generate-mode counterpart of `../cli/commands/build.ts`'s `BuildResult.buildParams`. Empty when the project declares/supplies none. */
   buildParams?: BuildParamProvenance[];
@@ -287,8 +289,8 @@ export async function generateComponentsPipeline(
   }));
 
   try {
-    const { yaml, stages, jobs } = plugin.generateComponentPipeline(driverComponents, options);
-    return { success: true, yaml, stages, jobs, buildParams };
+    const { yaml, stages, jobs, env } = plugin.generateComponentPipeline(driverComponents, options);
+    return { success: true, yaml, stages, jobs, ...(env ? { env } : {}), buildParams };
   } catch (err) {
     if (err instanceof UnknownDependencyError || err instanceof DependencyCycleError) {
       return { success: false, error: err.message };

package/src/graph-ir.ts

@@ -190,6 +190,13 @@ export interface IRPipelineEdge {
 export interface IRPipeline {
   /** The CI-provider lexicon that produced this projection (e.g. "gitlab"). */
   provider: string;
+  /**
+   * The environment the projected pipeline deploys (#2046) — copied from the
+   * generator's own resolution (`ComponentPipelineResult.env`), so the IR
+   * carries the identity instead of leaving a consumer to lex it out of a
+   * job's run line.
+   */
+  env?: string;
   /** Wave-ordered stage names — 1:1 with the component graph's `groups.byWave` keys. */
   stages: string[];
   nodes: IRPipelineNode[];

package/src/lexicon.ts

@@ -461,6 +461,14 @@ export interface ComponentPipelineResult {
   stages: string[];
   /** Every generated job, in emit order. */
   jobs: ComponentPipelineJob[];
+  /**
+   * The environment this pipeline deploys — `options.env` with the
+   * generator's default applied (#2046). Generators set it so a consumer
+   * (the graph IR's `pipeline` projection, behold) can join a pipeline to
+   * its environment without lexing a job's `run:`/`script:` line, where the
+   * value otherwise survives only as a shell argument.
+   */
+  env?: string;
 }
 
 /**

package/src/lifecycle/release-ledger.test.ts

@@ -11,6 +11,7 @@ import {
   InvalidReleaseRecordError,
   latestPerComponent,
   recordsForDigest,
+  resolveRunId,
   type ReleaseRecord,
   type ReleaseRecordInput,
 } from "./release-ledger";
@@ -234,4 +235,67 @@ describe("release-ledger", () => {
       expect(found.every((r) => r.digest === "sha256:shared")).toBe(true);
     });
   });
+
+  describe("resolveRunId (#2045)", () => {
+    test("GitHub Actions env resolves id + origin together, with repo and run url", () => {
+      const env = {
+        GITHUB_RUN_ID: "18234771902",
+        GITHUB_REPOSITORY: "INTENTIUS/chant",
+        GITHUB_SERVER_URL: "https://github.com",
+      };
+      expect(resolveRunId(undefined, env)).toEqual({
+        runId: "18234771902",
+        runOrigin: {
+          forge: "github",
+          repo: "INTENTIUS/chant",
+          url: "https://github.com/INTENTIUS/chant/actions/runs/18234771902",
+        },
+      });
+    });
+
+    test("a Forgejo instance resolves through the same env contract to its own host", () => {
+      const env = {
+        GITHUB_RUN_ID: "42",
+        GITHUB_REPOSITORY: "intentius/loomster",
+        GITHUB_SERVER_URL: "https://forge.example.dev",
+      };
+      expect(resolveRunId(undefined, env).runOrigin!.url).toBe("https://forge.example.dev/intentius/loomster/actions/runs/42");
+    });
+
+    test("GitLab CI env records the project path and takes CI_PIPELINE_URL verbatim", () => {
+      const env = {
+        CI_PIPELINE_ID: "991",
+        CI_PROJECT_PATH: "group/app",
+        CI_PIPELINE_URL: "https://gitlab.com/group/app/-/pipelines/991",
+      };
+      expect(resolveRunId(undefined, env)).toEqual({
+        runId: "991",
+        runOrigin: { forge: "gitlab", repo: "group/app", url: "https://gitlab.com/group/app/-/pipelines/991" },
+      });
+    });
+
+    test("outside CI the mint says local in a field, not only in the id's spelling", () => {
+      const { runId, runOrigin } = resolveRunId(undefined, {});
+      expect(runId).toMatch(/^local-\d+$/);
+      expect(runOrigin).toEqual({ forge: "local" });
+    });
+
+    test("an explicit id gets an origin only when it matches what the environment advertises", () => {
+      const env = { GITHUB_RUN_ID: "42", GITHUB_REPOSITORY: "o/r", GITHUB_SERVER_URL: "https://github.com" };
+      expect(resolveRunId("42", env).runOrigin?.forge).toBe("github");
+      expect(resolveRunId("something-else", env).runOrigin).toBeUndefined();
+    });
+
+    test("a record carrying runOrigin round-trips through the ledger", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const input = makeInput({
+          runOrigin: { forge: "github", repo: "o/r", url: "https://github.com/o/r/actions/runs/1" },
+        });
+        await appendReleaseRecord(input, { cwd: dir });
+        const { records } = await readReleaseLedger("prod", { cwd: dir });
+        expect(records[0].runOrigin).toEqual(input.runOrigin);
+      });
+    });
+  });
 });

package/src/lifecycle/release-ledger.ts

@@ -31,6 +31,25 @@
 import { sortedJsonReplacer } from "../utils";
 import { appendReleaseRecordLine, readReleaseLedgerLines, listLedgerEnvironments as gitListLedgerEnvironments } from "./git";
 
+/**
+ * The id space a `ReleaseRecord.runId` lives in, and how to reach the run
+ * (#2045).
+ */
+export interface RunOrigin {
+  /**
+   * Which id space minted `runId`: `github` (a GitHub Actions run id — also
+   * the spelling Forgejo Actions uses, since it implements the same env
+   * contract; `url` disambiguates the actual host), `gitlab` (a CI pipeline
+   * id), `op` (an orchestrator/Op run id), or `local` (minted on the machine
+   * that ran the deploy, resolvable nowhere).
+   */
+  forge: "github" | "gitlab" | "op" | "local";
+  /** Repo/project slug on the forge (`GITHUB_REPOSITORY` / `CI_PROJECT_PATH`), when the environment named one. */
+  repo?: string;
+  /** Resolved link to the run, when the environment provided enough to build one. */
+  url?: string;
+}
+
 /**
  * One immutable deploy record: `(component, env, artifact digest, git sha,
  * run id, timestamp, actor)`, referencing the build archive by digest — the
@@ -54,8 +73,19 @@ export interface ReleaseRecord {
   digest: string;
   /** Git commit SHA the deploy was built from. */
   gitSha: string;
-  /** Orchestrator run identifier (a `DriverRunResult`/Op run id, or a CI run id in generate mode) — the pointer back into the deploy event log. */
+  /** Orchestrator run identifier (a `DriverRunResult`/Op run id, or a CI run id in generate mode) — the pointer back into the deploy event log. Which id space it lives in, and how to follow it, is `runOrigin`'s job (#2045). */
   runId: string;
+  /**
+   * Where `runId` can be resolved (#2045). A bare `runId` names a run in one
+   * of several mutually incompatible id spaces — a GitHub Actions run id, a
+   * GitLab pipeline id, an Op run id, a locally minted id — and without this
+   * a reader can tell them apart only by inference from whoever wrote the
+   * record. Written at record time from the same environment the id came
+   * from, so the two cannot skew. Optional: records written before this
+   * field existed, and callers passing an id whose origin they did not
+   * declare, simply have none.
+   */
+  runOrigin?: RunOrigin;
   /**
    * When this record was written. The caller supplies this — the session
    * cannot call `Date.now()` reliably in every context, so the CLI resolves
@@ -132,6 +162,54 @@ export function validateReleaseRecord(record: Partial<ReleaseRecord>): string[]
 /** Input a caller supplies to record one deploy — `version` is filled in, everything else is required (see `ReleaseRecord`). */
 export type ReleaseRecordInput = Omit<ReleaseRecord, "version">;
 
+/**
+ * Resolve a run id and its origin from the same environment, in one step, so
+ * the two cannot skew (#2045). Resolution order mirrors what
+ * `chant components release` always did — explicit id, then
+ * `GITHUB_RUN_ID`, then `CI_PIPELINE_ID`, then a locally minted
+ * `local-<ms>` — but now each source also names its id space:
+ *
+ *  - the GitHub path records `repo` (`GITHUB_REPOSITORY`) and builds the run
+ *    `url` from `GITHUB_SERVER_URL` — which also makes a Forgejo instance's
+ *    runs resolvable, since Forgejo Actions implements the same env contract;
+ *  - the GitLab path records `repo` (`CI_PROJECT_PATH`) and takes
+ *    `CI_PIPELINE_URL` verbatim;
+ *  - the local mint says `local` in a field instead of only in the id's
+ *    spelling.
+ *
+ * An explicit id still gets an origin when it matches the id the environment
+ * itself is advertising (a CI job passing `--run-id $GITHUB_RUN_ID`);
+ * otherwise the caller's id is recorded without one — guessing an origin the
+ * caller did not state would be exactly the inference this field exists to
+ * remove.
+ */
+export function resolveRunId(
+  explicit?: string,
+  env: NodeJS.ProcessEnv = process.env,
+): { runId: string; runOrigin?: RunOrigin } {
+  const githubOrigin = (id: string): RunOrigin => ({
+    forge: "github",
+    ...(env.GITHUB_REPOSITORY ? { repo: env.GITHUB_REPOSITORY } : {}),
+    ...(env.GITHUB_SERVER_URL && env.GITHUB_REPOSITORY
+      ? { url: `${env.GITHUB_SERVER_URL}/${env.GITHUB_REPOSITORY}/actions/runs/${id}` }
+      : {}),
+  });
+  const gitlabOrigin = (): RunOrigin => ({
+    forge: "gitlab",
+    ...(env.CI_PROJECT_PATH ? { repo: env.CI_PROJECT_PATH } : {}),
+    ...(env.CI_PIPELINE_URL ? { url: env.CI_PIPELINE_URL } : {}),
+  });
+
+  if (explicit) {
+    if (env.GITHUB_RUN_ID && explicit === env.GITHUB_RUN_ID) return { runId: explicit, runOrigin: githubOrigin(explicit) };
+    if (env.CI_PIPELINE_ID && explicit === env.CI_PIPELINE_ID) return { runId: explicit, runOrigin: gitlabOrigin() };
+    return { runId: explicit };
+  }
+  if (env.GITHUB_RUN_ID) return { runId: env.GITHUB_RUN_ID, runOrigin: githubOrigin(env.GITHUB_RUN_ID) };
+  if (env.CI_PIPELINE_ID) return { runId: env.CI_PIPELINE_ID, runOrigin: gitlabOrigin() };
+  return { runId: `local-${Date.now()}`, runOrigin: { forge: "local" } };
+}
+
 /**
  * Append one immutable release record to the `<env>` ledger on the
  * `chant/lifecycle` orphan branch. Throws `InvalidReleaseRecordError` before

package/src/op/activity-contract.ts

@@ -75,6 +75,18 @@ export interface ActivityContract<Args = unknown, Return = unknown> {
    * per #1290 — a later step's reference into this one's output.
    */
   returns?: z.ZodType<Return>;
+  /**
+   * Names of top-level args whose values identify what the activity's effect
+   * touches in the estate (#2022) — an entity id, a resource address, a
+   * target endpoint — as opposed to scope (`env`, a stack name) or mechanics
+   * (a timeout, a mode). op.json's IR resolves these per step into
+   * `OpIRActivityStep.entities`, so a renderer can join a step to the estate
+   * nodes it touches instead of inventing joins off scope fields. Optional
+   * and partial by design, like the contract itself: an activity whose
+   * touched set is not spelled in its args (e.g. an applier that derives
+   * stack members internally) simply declares none.
+   */
+  entities?: string[];
 }
 
 /** Declare an activity contract. */
@@ -82,12 +94,14 @@ export function activityContract<ArgsSchema extends z.ZodTypeAny, ReturnSchema e
   name: string,
   args: ArgsSchema,
   returns?: ReturnSchema,
+  opts?: { entities?: string[] },
 ): ActivityContract<z.infer<ArgsSchema>, ReturnSchema extends z.ZodTypeAny ? z.infer<ReturnSchema> : unknown> {
   return {
     [CONTRACT_BRAND]: true,
     name,
     args,
     ...(returns ? { returns } : {}),
+    ...(opts?.entities && opts.entities.length > 0 ? { entities: opts.entities } : {}),
   } as ActivityContract<z.infer<ArgsSchema>, ReturnSchema extends z.ZodTypeAny ? z.infer<ReturnSchema> : unknown>;
 }
 

package/src/terraform/manifest.test.ts

@@ -3,10 +3,12 @@ import { mkdtempSync, rmSync, writeFileSync } from "fs";
 import { tmpdir } from "os";
 import { join } from "path";
 import {
+  CARVE_MANIFEST_VERSION,
   carveManifestPath,
   listCarveManifests,
   readCarveManifest,
   resolveCarveManifest,
+  resolveManifestFilePath,
   updateCarveManifest,
   writeCarveManifest,
   type CarveManifest,
@@ -89,6 +91,56 @@ describe("carve manifest", () => {
     });
   });
 
+  test("records file paths relative to its own directory, so the tree can move (#2039)", () => {
+    withDir((dir) => {
+      const m = manifest("aws_s3_bucket.assets");
+      m.emit = { source: "tfstate", files: [join(dir, "src", "assets.ts")], at: "t" };
+      m.bridge = {
+        written: [join(dir, "aws_s3_bucket-assets-runbook.md"), join(dir, "..", "api.tf")],
+        appliedInPlace: false,
+        patch: join(dir, "aws_s3_bucket-assets-bridge.patch"),
+        at: "t",
+      };
+      const path = writeCarveManifest(dir, m);
+      const read = readCarveManifest(path)!;
+      expect(read.version).toBe(CARVE_MANIFEST_VERSION);
+      expect(read.emit!.files).toEqual([join("src", "assets.ts")]);
+      expect(read.bridge!.written).toEqual(["aws_s3_bucket-assets-runbook.md", join("..", "api.tf")]);
+      expect(read.bridge!.patch).toBe("aws_s3_bucket-assets-bridge.patch");
+      // `from`/`statePath` locate the estate, a tree the manifest does not
+      // travel with — they stay absolute.
+      expect(read.from).toBe("/estate");
+    });
+  });
+
+  test("resolveManifestFilePath joins relative entries and passes absolute (v1) entries through", () => {
+    expect(resolveManifestFilePath("/moved/carveout", join("src", "assets.ts"))).toBe(join("/moved/carveout", "src", "assets.ts"));
+    expect(resolveManifestFilePath("/moved/carveout", "/original/carveout/src/assets.ts")).toBe("/original/carveout/src/assets.ts");
+  });
+
+  test("reads a version-1 manifest (absolute paths) and migrates it on update", () => {
+    withDir((dir) => {
+      const path = carveManifestPath(dir, "aws_s3_bucket.assets");
+      const v1: CarveManifest = {
+        ...manifest("aws_s3_bucket.assets"),
+        version: 1,
+        emit: { source: "tfstate", files: [join(dir, "src", "assets.ts")], at: "t" },
+      };
+      writeFileSync(path, JSON.stringify(v1, null, 2) + "\n");
+      // Readable as-is, absolute paths intact.
+      expect(readCarveManifest(path)!.emit!.files).toEqual([join(dir, "src", "assets.ts")]);
+
+      // Any update rewrites the whole manifest to the version-2 contract.
+      updateCarveManifest(dir, "aws_s3_bucket.assets", {
+        bridge: { written: [join(dir, "runbook.md")], appliedInPlace: false, at: "t" },
+      });
+      const migrated = readCarveManifest(path)!;
+      expect(migrated.version).toBe(CARVE_MANIFEST_VERSION);
+      expect(migrated.emit!.files).toEqual([join("src", "assets.ts")]);
+      expect(migrated.bridge!.written).toEqual(["runbook.md"]);
+    });
+  });
+
   test("update patches an existing manifest and no-ops on a missing one", () => {
     withDir((dir) => {
       expect(updateCarveManifest(dir, "aws_s3_bucket.assets", { bridge: { written: [], appliedInPlace: false, at: "t" } })).toBeUndefined();