@intentius/chant 0.124.40 → 0.124.42

package/src/cli/handlers/promote.ts

@@ -26,6 +26,7 @@ import { dirname, join, resolve } from "node:path";
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { loadChantConfig, type ChantConfig } from "../../config";
 import { promotionOrder } from "../../workspace/promotion-order";
+import { releaseTargetRefusal } from "../../components/pr-environment";
 import { resolvePromotionSource } from "../../components/promote-order";
 import { fetchLifecycle, getHeadCommit, pushLifecycle } from "../../lifecycle/git";
 import {
@@ -897,6 +898,14 @@ export async function runComponentsPromote(ctx: CommandContext): Promise<number>
     console.error(formatError({ message: "--to <env> is required", hint: PROMOTE_USAGE }));
     return 1;
   }
+  // #4298: a pull request's environment is neither a release's target nor its source.
+  for (const env of [to, args.migrateFrom]) {
+    const refusal = env ? releaseTargetRefusal(env) : undefined;
+    if (refusal) {
+      console.error(formatError({ message: refusal }));
+      return 1;
+    }
+  }
   const who = actorOrRefuse(ctx);
   if (typeof who === "number") return who;
 

package/src/cli/handlers/query.ts

@@ -0,0 +1,78 @@
+/**
+ * `chant query "<sql>" [dir] [--member <name>] [--json]` (#4297): one
+ * read-only SQL statement over the snapshots, Op runs, gates, deploys and
+ * releases on the local `chant/lifecycle` branch. The tables and the engine
+ * live in `../../lifecycle/query.ts`; this reads the ledgers and prints.
+ *
+ * Inside a workspace every member's ledger is read, each row naming its
+ * member; `--member` keeps the members it names. Outside one the project's
+ * own ledger is read and `member` is NULL. It reads the local branch and
+ * never fetches.
+ */
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { formatError, formatWarning } from "../format";
+import type { CommandContext } from "../registry";
+import type { QueryLedger } from "../../lifecycle/query";
+import { findWorkspaceRoot } from "../../project-root";
+
+const USAGE = 'chant query "<sql>" [dir] [--member <name>] [--json]';
+
+/** The ledgers `chant query` reads from `cwd`: every member's in a workspace, else the project's own. */
+export async function queryLedgers(cwd: string, members?: readonly string[]): Promise<QueryLedger[]> {
+  const { gitLedgerReadPort } = await import("../../lifecycle/git");
+  const found = findWorkspaceRoot(cwd);
+  if (!found) return [{ member: null, port: gitLedgerReadPort({ cwd }) }];
+  // Workspace code loads only when there is a workspace, so a level-0 project never pays for it.
+  const { readDeclaration, WorkspaceReadError } = await import("../../workspace/declaration");
+  const { workingTree } = await import("../../workspace/tree");
+  const { QueryError } = await import("../../lifecycle/query");
+  let declaration;
+  try {
+    declaration = readDeclaration(workingTree(found.dir), "");
+  } catch (err) {
+    if (err instanceof WorkspaceReadError) throw new QueryError(`${err.code}: ${err.message}`);
+    throw err;
+  }
+  const wanted = members && members.length > 0 ? new Set(members) : null;
+  if (wanted) {
+    const unknown = [...wanted].filter((n) => !declaration.members.some((m) => m.name === n));
+    if (unknown.length > 0) throw new QueryError(`--member ${unknown.join(", ")} names no member of the workspace`);
+  }
+  return declaration.members
+    .filter((m) => !wanted || wanted.has(m.name))
+    .map((m) => ({ member: m.name, port: gitLedgerReadPort({ cwd: found.dir, member: m.dir === "." ? "." : m.name }) }));
+}
+
+export async function runQueryCommand(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const sql = args.positionals?.[0];
+  if (sql === undefined || sql.trim() === "") {
+    console.error(formatError({ message: "chant query needs a statement", hint: `${USAGE}, such as chant query "SELECT env, count(*) FROM resources GROUP BY env"` }));
+    return 1;
+  }
+  const cwd = resolve(args.positionals?.[1] ?? ".");
+  if (!existsSync(cwd)) {
+    console.error(formatError({ message: `${cwd} does not exist`, hint: USAGE }));
+    return 1;
+  }
+  const { loadQueryData, runQuery, formatQueryResult, QueryError } = await import("../../lifecycle/query");
+  try {
+    const load = await loadQueryData(await queryLedgers(cwd, args.members));
+    const result = await runQuery(sql, load);
+    if (args.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(formatQueryResult(result));
+      const bad = Object.entries(result.malformed).filter(([, n]) => n > 0);
+      if (bad.length > 0) console.error(formatWarning({ message: `left out what could not be read: ${bad.map(([t, n]) => `${n} in ${t}`).join(", ")}` }));
+    }
+    return 0;
+  } catch (err) {
+    if (err instanceof QueryError) {
+      console.error(formatError({ message: err.message, hint: USAGE }));
+      return 1;
+    }
+    throw err;
+  }
+}

package/src/cli/handlers/run.ts

@@ -34,6 +34,7 @@ import { appliedDigestOf, extractRunDigest, maybeRecordAutoRelease, type Applied
 import { maybePersistBuildManifest } from "../../components/manifest-persistence";
 import { failedRunExitCode, type DriverComponentResult } from "../../components/driver";
 import { isComponentList, type ComponentRunPlan, type RunComponentsResult } from "../../components/cli-support";
+import { parseComponentTargets } from "../../components/capability";
 import { isApplyRecord, resolveCiRun, type ReleaseRecord, type RunOrigin } from "../../lifecycle/release-ledger";
 import { gateAdmission, gateApprover } from "../../components/promote";
 import { runOpGenerate } from "./run-generate";
@@ -1202,10 +1203,19 @@ async function runComponentSelection(ctx: CommandContext): Promise<number> {
         if (plan.added.length > 0) console.error(formatInfo(`added as dependencies: ${plan.added.join(", ")}`));
       }
     : undefined;
+  // #4300: `--target <component>:<address>`, the addresses a component's steps narrow to.
+  let targets: Record<string, string[]> | undefined;
+  try {
+    targets = ctx.args.targets && ctx.args.targets.length > 0 ? parseComponentTargets(ctx.args.targets) : undefined;
+  } catch (err) {
+    console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+    return 1;
+  }
   let result: RunComponentsResult;
   try {
     result = await runtime.runComponents(projectPath, selector, {
       env: ctx.args.env,
+      ...(targets ? { targets } : {}),
       componentOutputs: seededOutputs,
       onProgress,
       ...(events ? { onRunEvent: events.emit } : {}),

package/src/cli/main.ts

@@ -173,6 +173,11 @@ Commands:
                         terms; --live or --at <ref> with --env <name> reads the
                         estate or a recorded snapshot; --show <attr>,
                         --check-live, --check-snapshot, --fail-on-drift)
+  query "<sql>" [dir]   Run one read-only SQL statement over chant/lifecycle:
+                        the resources and snapshots each lexicon observed, Op
+                        runs, gates, deploys, releases and cuts, loaded into
+                        node:sqlite (schema v1, listed in chant_schema).
+                        --member <name> keeps members; --json prints rows
   generate             Generate typed code from sources chant.config declares
                         (k8s.crds, helm.charts) into src/generated/<lexicon>/
                         (codegen.outDir); --check exits 1 when the committed
@@ -342,7 +347,7 @@ CI:
                         key. --trust commits its runner entry on a branch of its
                         own and pushes it for review; the target branch is never
                         written
-  ci init --workflow trunk-curated|trunk-curated+apply-on-merge
+  ci init --workflow trunk-curated|trunk-curated+apply-on-merge|apply-before-merge
               [--forge github|gitlab|forgejo] [--security <group>]... [--yes]
                         Set the workspace up for a prescribed delivery workflow:
                         print what it would write as a diff, then write it on
@@ -558,6 +563,15 @@ Ops:
                         applies it once, if .chant/overriders at base lists
                         --actor
 
+  lock <target>...      Lock targets for a pull request on chant/lifecycle
+                        (--pr <n>, --stage plan|apply|lock, --head <sha>,
+                        --by <who>, --gate <name>, --json). --from-report
+                        <pr-plan.json> locks the components a plan selected.
+                        --forge <kind> reads which holders are still open and
+                        posts chant/lock on --head. Exits 3 when another open
+                        pull request holds a target. --list prints the locks
+  unlock [<target>...]  Release the locks a pull request holds (--pr <n>,
+                        --gate <name>, --json)
   graph                 Show Op dependency graph (--stacks for cross-stack order,
                         --format ir|mermaid|dot|layout for the lint-gated graph IR,
                         a Mermaid flowchart, Graphviz DOT, or node positions;
@@ -997,17 +1011,33 @@ Component release ledger + status:
                              when the wave is reached, with --canary <name>
                              for wave 1 and --wave <n> for one wave per CI
                              job; --resume <file> finishes an attempt that
-                             stopped)
+                             stopped; --target <component>:<address> plans
+                             and applies only that address)
   components pr-plan       Plan the components a pull request reaches and
                             the ones that depend on them, and write the
                             report and note (--base <ref> --pr <n>
                             [--forge github|gitlab|forgejo] posts them);
                             applies nothing
+  components pr-post       Post the plan note and the chant/plan status
+                            from the report pr-plan --no-status wrote
+                            (--pr <n> --head <sha> --env <env> --forge
+                            <kind>), in a job that runs none of the
+                            change's code (#4295)
   components pr-record     On merge (#4168): plan the same members again,
                             store the change set and write the merge record
                             _merges/<commit>.json; applies and refuses
                             nothing, and a plan that differs from the
                             approved one sets a failing chant/record status
+  components pr-env        An environment per open pull request (#4298): up
+                            --base <ref> --pr <n> applies the change to pr-<n>,
+                            derived from ci.prEnvironment.template, once an
+                            approval of its plan stands (chant approve pr-<n>
+                            pr-env --plan <digest>); post --pr <n> --head
+                            <sha> keeps the record up --no-push handed on and
+                            posts the note; down --pr <n> tears down
+                            only what carries pr-<n>'s ownership marker; sweep
+                            tears down each one whose TTL passed or whose pull
+                            request closed. Never a release target
   components pr-apply      With --apply-on-merge: plan the same members again and apply
                             them only if an approval stands for that digest
                             (chant approve pr-<n> pr-apply --plan <digest>);
@@ -1026,6 +1056,11 @@ Component release ledger + status:
                             from the one last applied to --env, under the
                             approved plans of the merges since, else at gate
                             op green-<sha>;
+                            --before-merge --pr <n>: apply the open pull
+                            request's head under its gate, once the
+                            declaration at base sets ci.workflow to
+                            apply-before-merge and the forge says it is
+                            approved, mergeable, undiverged and green;
                             --events-json, both commands: the run-event
                             stream on stdout; --report-url <s3 or file URL>,
                             both commands: copy the report, the change set
@@ -1201,7 +1236,8 @@ Options:
                         chant.config.ts's build.sandbox: true; #1045)
   --param <name=value>  (build, graph, run --components, components fan-out,
                         components promote, components rollback,
-                        components redeploy, release cut) Bind a
+                        components redeploy, components pr-env up,
+                        release cut) Bind a
                         declared build-time parameter (chant.config.ts's buildParams)
                         to a value, for source to read as params.<name>
                         (#1064) instead of process.env — repeatable.
@@ -1213,7 +1249,8 @@ Options:
                         chant.template.json declares instead (#2627).
   --params-file <path>  (build, graph, run --components, components fan-out,
                         components promote, components rollback,
-                        components redeploy, release cut) JSON file
+                        components redeploy, components pr-env up,
+                        release cut) JSON file
                         of { "name": value } build-time parameter values
                         (#1064). Second precedence, after --param.
                         init --from refuses it: pass --param instead.
@@ -1441,6 +1478,8 @@ export const commandRegistry: CommandDef[] = [
   { name: "describe", handler: runDescribe },
   { name: "explain", handler: runExplain },
   { name: "search", handler: runSearch },
+  // #4297 — SQL over the snapshots, runs, gates, deploys and releases on chant/lifecycle. Imported on first use.
+  { name: "query", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/query")).runQueryCommand(ctx) },
   // chant#2591 — `import --agents` and `audit` read chant.config statically
   // and never evaluate it (chant#2589 for audit, which audits code it must not run).
   { name: "import", handler: runImport, runsNoConfig: (args) => args.agents === true },
@@ -1524,6 +1563,9 @@ export const commandRegistry: CommandDef[] = [
   { name: "operator log", handler: runOperatorLog },
   { name: "operator", handler: runOperator },
   { name: "approve", handler: runApprove },
+  // #4293 — target locks a pull request holds on chant/lifecycle. Imported on first use.
+  { name: "lock", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/lock")).runLock(ctx) },
+  { name: "unlock", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/lock")).runUnlock(ctx) },
 
   { name: "graph", handler: runGraph },
   { name: "vendor", handler: runVendor },
@@ -1613,7 +1655,10 @@ export const commandRegistry: CommandDef[] = [
   // #3183 — the pull-request loop the generated CI runs. Imported on first use.
   { name: "components pr-plan", requiresPlugins: true, handler: async (ctx) => (await import("./handlers/pr")).runComponentsPrPlan(ctx) },
   { name: "components pr-apply", requiresPlugins: true, handler: async (ctx) => (await import("./handlers/pr")).runComponentsPrApply(ctx) },
+  // #4295: posts from the plan report in a job that runs none of the change's code, so it loads no plugins.
+  { name: "components pr-post", handler: async (ctx) => (await import("./handlers/pr")).runComponentsPrPost(ctx) },
   { name: "components pr-record", requiresPlugins: true, handler: async (ctx) => (await import("./handlers/pr")).runComponentsPrRecord(ctx) },
+  { name: "components pr-env", requiresPlugins: true, handler: async (ctx) => (await import("./handlers/pr-env")).runComponentsPrEnv(ctx) },
   { name: "components status", requiresPlugins: true, handler: runComponentsStatus },
   { name: "components release", handler: runComponentsReleaseRecord },
   { name: "components export", handler: runComponentsExport },

package/src/cli/parse-args.ts

@@ -43,6 +43,7 @@ const BOOLEAN_FLAGS = new Set([
   "--stacks",
   "--components",
   "--pr-build",
+  "--pr-env",
   "--up",
   "--down",
   "--include-dependents",
@@ -72,6 +73,7 @@ const BOOLEAN_FLAGS = new Set([
   "--in-place",
   "--require-runner-start",
   "--no-push",
+  "--list",
   "--no-require-review",
   "--expire",
   "--check-live",
@@ -376,6 +378,11 @@ export function parseArgs(args: string[]): ParsedArgs {
       const share = Number(raw);
       if (!Number.isInteger(share) || share < 1) throw new Error(`--share needs a share number from 1: got "${raw ?? ""}"`);
       result.share = share;
+    } else if (arg === "--target") {
+      // `chant components fan-out|run --components --target <component>:<address>` (#4300), repeatable.
+      const raw = args[++i];
+      if (!raw || raw.startsWith("-") || !raw.includes(":")) throw new Error("--target needs a component and an address: --target <component>:<address>");
+      (result.targets ??= []).push(raw);
     } else if (arg === "--canary") {
       const raw = args[++i];
       if (!raw || raw.startsWith("-")) throw new Error("--canary needs a component name: --canary <name>[,<name>...]");
@@ -396,11 +403,26 @@ export function parseArgs(args: string[]): ParsedArgs {
       if (!result.forge || result.forge.startsWith("-")) throw new Error("--forge needs a forge: --forge github|gitlab|forgejo");
     } else if (arg === "--require-review") {
       result.requireReview = true;
+    } else if (arg === "--list") {
+      // `chant lock --list` (#4293): print the target locks instead of taking any.
+      result.list = true;
+    } else if (arg === "--stage") {
+      // `chant lock --stage plan|apply|lock` (#4293): how the lock was taken.
+      result.lockStage = args[++i];
+      if (!result.lockStage || result.lockStage.startsWith("-")) throw new Error("--stage needs plan, apply or lock: --stage <stage>");
+    } else if (arg === "--from-report") {
+      // `chant lock --from-report <pr-plan.json>` (#4293): lock the components a pull-request report lists.
+      result.fromReport = args[++i];
+      if (!result.fromReport || result.fromReport.startsWith("-")) throw new Error("--from-report needs a report file: --from-report <pr-plan.json>");
     } else if (arg === "--report-url") {
       // `chant components pr-plan|pr-apply --report-url <url>` (#4007).
       const url = args[++i];
       if (!url || url.startsWith("-")) throw new Error("--report-url needs a URL: --report-url s3://<bucket>/<prefix> or file://<directory>");
       result.reportUrl = url;
+    } else if (arg === "--result") {
+      // `chant components pr-post --result <result>` (#4295): the plan job's own result, which fails the status when it failed.
+      result.planResult = args[++i];
+      if (!result.planResult || result.planResult.startsWith("-")) throw new Error("--result needs the plan job's result: --result success|failure|cancelled");
     } else if (arg === "--no-status") {
       // `chant ci run|serve --no-status` (#4097): post no commit status for the job.
       result.noStatus = true;
@@ -419,9 +441,18 @@ export function parseArgs(args: string[]): ParsedArgs {
     } else if (arg === "--green") {
       // `chant components pr-apply --green` (#4168 step 9): apply the green commit at HEAD.
       result.green = true;
+    } else if (arg === "--before-merge") {
+      // `chant components pr-apply --before-merge` (#4301, ws-106): apply an open pull request's plan from its head.
+      result.beforeMerge = true;
+    } else if (arg === "--apply-before-merge") {
+      // `chant build --pr-loop --apply-before-merge` and `chant ci run apply --apply-before-merge` (#4301): the job that applies before merge.
+      result.applyBeforeMerge = true;
     } else if (arg === "--apply-on-merge") {
       // `chant build --pr-loop --apply-on-merge` and `chant ci serve --apply-on-merge` (#4168): opt into applying on merge.
       result.applyOnMerge = true;
+    } else if (arg === "--pr-env") {
+      // `chant build --pr-loop --pr-env` (#4298): add the pull request environment's jobs.
+      result.prEnv = true;
     } else if (arg === "--pr-build") {
       // `chant build --pr-loop --pr-build` (#4088), and `chant ci run --pr-build` (#4094).
       result.prBuild = true;
@@ -864,8 +895,9 @@ export function parseArgs(args: string[]): ParsedArgs {
     } else if (arg === "--expire") {
       result.expire = true;
     } else if (arg === "--role") {
-      // #2508 — a role the approver holds, for a gate whose quorum names
-      // roles. Repeatable, and a comma list works too.
+      // #2508 — a role the approver claims, which a gate's policy sees. A
+      // quorum reads roles from .chant/trust.json at base instead (#4290).
+      // Repeatable, and a comma list works too.
       const value = args[++i] ?? "";
       result.roles = [...(result.roles ?? []), ...value.split(",").map((r) => r.trim()).filter(Boolean)];
     } else if (arg === "--agent") {

package/src/cli/registry.ts

@@ -294,6 +294,12 @@ export interface ParsedArgs {
   share?: number;
   /** `chant run wave --group <name>` (#3914) — apply one job group's runs of a decided wave. */
   group?: string;
+  /**
+   * `chant components fan-out --target <component>:<address>` and `chant run
+   * --components --target ...` (#4300), repeatable: the addresses a
+   * component's steps narrow to. Raw values; `parseComponentTargets` groups them.
+   */
+  targets?: string[];
   /** `chant components fan-out --canary <component>` (#3049), repeatable — components that form wave 1. */
   canary?: string[];
   /**
@@ -302,6 +308,12 @@ export interface ParsedArgs {
    * pr-apply finds it from the commit through `--forge` when omitted.
    */
   pr?: number;
+  /** `chant lock --list` (#4293): print the target locks instead of taking any. */
+  list?: boolean;
+  /** `chant lock --stage plan|apply|lock` (#4293): how the lock is taken. Default `lock`. */
+  lockStage?: string;
+  /** `chant lock --from-report <file>` (#4293): lock the components a `pr-plan.json` lists. */
+  fromReport?: string;
   /** Every `--pr <n>`, in order: `chant release compose` (#4168 4.3) takes several. */
   prs?: number[];
   /** `chant release cut --channel <tag>` (#4168 4.3): the tag a publish of the release moves in place of `latest`. */
@@ -345,6 +357,21 @@ export interface ParsedArgs {
    * approved plans of the merges between or a gate of its own.
    */
   green?: boolean;
+  /** `chant build --pr-loop --pr-env` (#4298) — add the env-up, env-down and env-sweep jobs of a pull request's environment. */
+  prEnv?: boolean;
+  /**
+   * `chant components pr-apply --before-merge` (#4301, ws-106): apply an open
+   * pull request's plan from its head, once the declaration at base sets
+   * `ci.workflow: "apply-before-merge"` and the pull request is approved,
+   * mergeable, undiverged and green.
+   */
+  beforeMerge?: boolean;
+  /**
+   * `chant build --pr-loop --apply-before-merge` and `chant ci run apply
+   * --apply-before-merge` (#4301): the pipeline's apply job applies an open
+   * pull request before it merges, and a merge records.
+   */
+  applyBeforeMerge?: boolean;
   /** `chant build --pr-loop --pr-build` (#4088) — build and lint before pr-plan and pr-apply. */
   prBuild?: boolean;
   /** `chant ci serve --build-command <line>` (#4169) — the line that builds a commit a `ci/build/<sha>` tag asks for, in a worktree of it. */
@@ -477,7 +504,7 @@ export interface ParsedArgs {
   records?: boolean;
   /** `chant workspace wip save --label <text>` (#3172): what the caller calls the snapshot, such as a turn id. */
   label?: string;
-  /** `chant workspace wip --branch <branch>` (#3172): list one branch's snapshots. */
+  /** `chant workspace wip --branch <branch>` (#3172): list one branch's snapshots. `chant components pr-apply|pr-record --branch <branch>` (#4292): the branch pushed, which `ci.branches` routes members by; default the forge's GITHUB_REF_NAME or CI_COMMIT_BRANCH. */
   branch?: string;
   /** `chant ci workflow --workflow <name>`, repeatable (#3573): a workflow whose completion triggers a tick, beside those the scan finds. Also `chant ci init --workflow <name>` (#4168 step 6), the prescribed workflow to set up. */
   ciWorkflows?: string[];
@@ -491,6 +518,8 @@ export interface ParsedArgs {
   ciSecrets?: string;
   /** `chant ci workflow --chant <command>` (#3573): the command the tick step runs chant with, in place of the npx pin. Also `chant ci run --chant` (#4094): what runs chant in the job. */
   ciChant?: string;
+  /** `chant components pr-post --result <result>` (#4295): the plan job's own result. `failure` or `cancelled` fails the `chant/plan` status. */
+  planResult?: string;
   /** `chant ci run|serve --no-status` (#4097): post no commit status for the job. `chant components pr-plan|pr-apply --no-status` (#4161): post neither the status nor the note. */
   noStatus?: boolean;
   /** `chant ci run|serve --status-url <template>` (#4097): the link a job's status carries. `{key}` is `<pr>/<commit>[/<member>]`, as `--report-url` keys it. */
@@ -737,7 +766,7 @@ export interface ParsedArgs {
    * on a model-authored channel.
    */
   allowSameOrigin?: boolean;
-  /** `chant approve --role <name>` (#2508) — roles the approver claims, for a gate whose quorum counts only some roles. Repeatable; a comma list also works. */
+  /** `chant approve --role <name>` (#2508) — roles the approver claims, which a gate's policy sees. A quorum never counts them (#4290): its roles come from `.chant/trust.json` at base. Repeatable; a comma list also works. */
   roles?: string[];
   /** `chant approve --agent` (#2508) — record the approval as an agent's. An agent never counts toward a quorum; it passes a gate only through a policy permit in `enforce` mode. */
   agent?: boolean;

package/src/components/capability-targets.test.ts

@@ -0,0 +1,162 @@
+/**
+ * Resource targeting (#4300): `--target <component>:<address>` narrows a
+ * component's steps, each capability accepts or refuses by name, and the
+ * targets join the plan digest an approval binds.
+ */
+
+import { describe, expect, test } from "vitest";
+import { CapabilityRegistry, parseComponentTargets, targetRefusal, type CapabilityPlan, type DeployContext } from "./capability";
+import { deployContext, runComponentDeploy, type DriverComponent } from "./driver";
+import { bindTargets, planWaveComponent, targetedPlanDigest } from "./wave-plan";
+import { fanOutGateDigest, runFanOut } from "./fan-out-run";
+import { planFanOut } from "./fan-out";
+import { memoryGateLedgerPort } from "../op/gate";
+
+const component = (name: string, ...kinds: string[]): DriverComponent => ({
+  name,
+  deploy: [{ phase: "Deploy", steps: kinds.map((kind) => ({ kind })) }],
+});
+
+/** A registry with a verb that accepts targets, one that refuses, and one that says nothing. */
+function registry(seen: DeployContext[] = []): CapabilityRegistry {
+  const r = new CapabilityRegistry();
+  r.register({
+    kind: "narrow",
+    targets: "accept",
+    async plan(ctx: DeployContext): Promise<CapabilityPlan> {
+      seen.push(ctx);
+      return { member: ctx.component, planDigest: "sha256:base", ...(ctx.targets ? { targets: ctx.targets } : {}) };
+    },
+    async run(ctx: DeployContext) {
+      seen.push(ctx);
+      return { ok: true };
+    },
+  } as never);
+  r.register({
+    kind: "whole",
+    targets: { refuse: "whole applies everything" },
+    async plan(ctx: DeployContext): Promise<CapabilityPlan> {
+      return { member: ctx.component, planDigest: "sha256:whole" };
+    },
+    async run() {
+      return { ok: true };
+    },
+  } as never);
+  r.register({
+    kind: "silent",
+    async run() {
+      return { ok: true };
+    },
+  } as never);
+  return r;
+}
+
+describe("parseComponentTargets", () => {
+  test("groups by component, sorted and unique, splitting at the first colon", () => {
+    expect(parseComponentTargets(["net:aws_vpc.main", "net:aws_subnet.a", "net:aws_vpc.main", "app:Deployment/prod/web", "net:x[\"a:b\"]"])).toEqual({
+      app: ["Deployment/prod/web"],
+      net: ["aws_subnet.a", "aws_vpc.main", 'x["a:b"]'],
+    });
+  });
+
+  test("refuses a value with no component or no address, and an unknown component", () => {
+    expect(() => parseComponentTargets([":aws_vpc.main"])).toThrow(/--target <component>:<address>/);
+    expect(() => parseComponentTargets(["net:"])).toThrow(/--target <component>:<address>/);
+    expect(() => parseComponentTargets(["nope:a"], new Set(["net"]))).toThrow(/no component is named nope/);
+  });
+});
+
+describe("targetRefusal", () => {
+  test("accept, refuse with its reason, and unset refusing by name", () => {
+    expect(targetRefusal({ kind: "a", targets: "accept" })).toBeUndefined();
+    expect(targetRefusal({ kind: "b", targets: { refuse: "no" } })).toBe("no");
+    expect(targetRefusal({ kind: "c" })).toMatch(/^c does not say/);
+  });
+});
+
+describe("deployContext", () => {
+  test("gives a component its own targets, sorted, and none to another", () => {
+    const options = { env: "dev", targets: { net: ["b", "a", "a"] } };
+    expect(deployContext(options, "net").targets).toEqual(["a", "b"]);
+    expect(deployContext(options, "app").targets).toBeUndefined();
+  });
+});
+
+describe("planning a targeted component", () => {
+  test("binds the targets into the member's digest and its change-set part", async () => {
+    const seen: DeployContext[] = [];
+    const ctx = deployContext({ env: "dev", targets: { net: ["aws_vpc.main"] } }, "net");
+    const planned = await planWaveComponent(component("net", "narrow"), registry(seen), ctx, {});
+    expect("error" in planned).toBe(false);
+    if ("error" in planned) return;
+    expect(seen[0]!.targets).toEqual(["aws_vpc.main"]);
+    const digest = targetedPlanDigest("sha256:base", ["aws_vpc.main"]);
+    expect(planned.members).toEqual([{ member: "net", planDigest: digest }]);
+    expect(planned.parts[0]!.member.planDigest).toBe(digest);
+  });
+
+  test("another set of targets is another digest, and none is the plan's own", async () => {
+    const a = targetedPlanDigest("sha256:base", ["x"]);
+    const b = targetedPlanDigest("sha256:base", ["y"]);
+    expect(a).not.toBe(b);
+    expect(targetedPlanDigest("sha256:base", ["y", "x"])).toBe(targetedPlanDigest("sha256:base", ["x", "y"]));
+    const untargeted = await planWaveComponent(component("net", "narrow"), registry(), deployContext({ env: "dev" }, "net"), {});
+    expect("error" in untargeted ? undefined : untargeted.members[0]!.planDigest).toBe("sha256:base");
+  });
+
+  test("a verb that refuses names itself, and so does one that says nothing", async () => {
+    const ctx = deployContext({ env: "dev", targets: { net: ["a"] } }, "net");
+    const refused = await planWaveComponent(component("net", "narrow", "whole"), registry(), ctx, {});
+    expect(refused).toEqual({ component: "net", error: 'component "net": whole refuses targets: whole applies everything' });
+    const silent = await planWaveComponent(component("net", "silent"), registry(), ctx, {});
+    expect("error" in silent && silent.error).toMatch(/silent refuses targets: silent does not say/);
+  });
+
+  test("a plan that does not give the targets back refuses", () => {
+    const ctx: DeployContext = { env: "dev", component: "net", targets: ["a", "b"] };
+    expect(() => bindTargets("narrow", ctx, { member: "net", planDigest: "d" })).toThrow(/names no targets/);
+    expect(() => bindTargets("narrow", ctx, { member: "net", planDigest: "d", targets: ["a"] })).toThrow(/names a$/);
+  });
+});
+
+describe("running a targeted component", () => {
+  test("refuses before any step runs when one verb can't narrow", async () => {
+    const seen: DeployContext[] = [];
+    const ctx = deployContext({ env: "dev", targets: { net: ["a"] } }, "net");
+    const result = await runComponentDeploy(component("net", "narrow", "whole"), ctx, registry(seen), {}, undefined, { port: memoryGateLedgerPort() });
+    expect(result.status).toBe("fail");
+    expect(result.records[0]).toMatchObject({ phase: "Targets", kind: "whole", status: "fail" });
+    expect(seen).toEqual([]);
+  });
+
+  test("hands the targets to a verb that accepts them", async () => {
+    const seen: DeployContext[] = [];
+    const ctx = deployContext({ env: "dev", targets: { net: ["a"] } }, "net");
+    const result = await runComponentDeploy(component("net", "narrow"), ctx, registry(seen), {}, undefined, { port: memoryGateLedgerPort() });
+    expect(result.status).toBe("ok");
+    expect(seen[0]!.targets).toEqual(["a"]);
+  });
+});
+
+describe("a gate over the whole set", () => {
+  test("binds the targets, so the untargeted approval does not cover a targeted run", async () => {
+    expect(fanOutGateDigest("sha256:set", undefined)).toBe("sha256:set");
+    expect(fanOutGateDigest("sha256:set", { net: [] })).toBe("sha256:set");
+    const narrowed = fanOutGateDigest("sha256:set", { net: ["a"] });
+    expect(narrowed).not.toBe("sha256:set");
+    expect(fanOutGateDigest("sha256:set", { net: ["b"] })).not.toBe(narrowed);
+
+    const estate = [component("net", "narrow")];
+    const plan = planFanOut({ components: estate, changed: ["net"] });
+    const gates = memoryGateLedgerPort();
+    const result = await runFanOut(plan, estate, registry(), {
+      env: "dev",
+      gates,
+      now: "2026-01-01T00:00:00Z",
+      gate: { op: "fan-out", gate: "set" },
+      targets: { net: ["a"] },
+    });
+    expect(result.status).toBe("gated");
+    expect(result.gate?.planDigest).toBe(fanOutGateDigest(plan.digest, { net: ["a"] }));
+  });
+});