@intentius/chant 0.124.23 → 0.124.25

package/dist/workspace/trust/verify.js

@@ -8,6 +8,12 @@
  * that touches those files must be attested by a signer the base policy
  * trusts, and by an admin when the base policy grants the admin role.
  *
+ * The write scope is policy too (#3079): when the workspace declaration at
+ * base has a `writeScope` or `agents` block, a commit that changes either
+ * block, or removes the declaration, is a protected write on the same terms.
+ * Other edits to the declaration are not. The declaration is found from
+ * `cwd`, as `chant workspace check --changes` finds it.
+ *
  * Attestation is opt-in (#2525 rule 6). Without a signers file at base the
  * check passes and says so, unless `--require attested` asks for more.
  *
@@ -21,6 +27,11 @@
  * `--require`, `runs` reports and nothing fails (studio-035 d).
  */
 import { execFileSync } from "node:child_process";
+import { posix } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { DECLARATION_FILES, WorkspaceReadError } from "../declaration.js";
+import { parseJsonText } from "../jsonc.js";
+import { locateWorkspace } from "../which-chant.js";
 import { policyAtBase, commitProvenance, resolveBase } from "./provenance.js";
 import { policyWriters, protectedPaths } from "./policy.js";
 import { fileAt, nextVersion, rotationPath, signerHistory } from "./rotation.js";
@@ -45,6 +56,47 @@ export function commitsTouching(repo, range, paths) {
     }
     return out;
 }
+const SCOPE_BLOCKS = ["writeScope", "agents"];
+function scopeState(repo, rev, dir) {
+    const present = DECLARATION_FILES.map((name) => ({ name, text: fileAt(repo, rev, posix.join(dir, name)) })).filter((f) => f.text !== undefined);
+    if (present.length === 0)
+        return { blocks: {} };
+    if (present.length > 1)
+        return { unreadable: present.map((f) => f.text).join("\0") };
+    const parsed = parseJsonText(present[0].text, { jsonc: present[0].name.endsWith(".jsonc") });
+    if (!parsed.ok || typeof parsed.value !== "object" || parsed.value === null || Array.isArray(parsed.value))
+        return { unreadable: present[0].text };
+    const obj = parsed.value;
+    return { blocks: Object.fromEntries(SCOPE_BLOCKS.filter((b) => obj[b] !== undefined).map((b) => [b, obj[b]])) };
+}
+/** The scope blocks that differ between two states; all of them when either can't be read and the texts differ. */
+function changedBlocks(a, b) {
+    if ("unreadable" in a || "unreadable" in b) {
+        return "unreadable" in a && "unreadable" in b && a.unreadable === b.unreadable ? [] : [...SCOPE_BLOCKS];
+    }
+    return SCOPE_BLOCKS.filter((k) => !isDeepStrictEqual(a.blocks[k], b.blocks[k]));
+}
+/**
+ * The directory, from the repository root, of the declaration found from
+ * `cwd` at `base`, with the scope blocks it has there. Null when there is no
+ * declaration, or one with neither block: then nothing in it is protected. A
+ * declaration that can't be read at base counts as having both.
+ */
+function scopedDeclarationAt(repo, cwd, base) {
+    let dir;
+    try {
+        const root = locateWorkspace(cwd, base).root;
+        dir = root === "." ? "" : root;
+    }
+    catch (err) {
+        if (err instanceof WorkspaceReadError)
+            return null;
+        throw err;
+    }
+    const state = scopeState(repo, base, dir);
+    const blocks = "unreadable" in state ? [...SCOPE_BLOCKS] : SCOPE_BLOCKS.filter((b) => b in state.blocks);
+    return blocks.length > 0 ? { dir, blocks } : null;
+}
 /** Whether a merge commit changes nothing beyond what its parents bring. */
 function mergeWithoutOwnChanges(repo, commit, parents) {
     if (parents < 2)
@@ -73,6 +125,7 @@ export function verifyChange(opts) {
         protectedPaths: protectedPaths(policy),
         protectedChanged: [],
         protectedWrites: [],
+        declaration: null,
         rotation: null,
         notes: [],
         failures: [],
@@ -99,7 +152,8 @@ export function verifyChange(opts) {
     }
     // Every commit in the change, oldest first, with its parents.
     const listing = git(repo, ["rev-list", "--reverse", "--parents", `${base.commit}..${head}`]).split("\n").filter(Boolean);
-    const parentsOf = new Map(listing.map((l) => { const [c, ...p] = l.split(" "); return [c, p.length]; }));
+    const parentList = new Map(listing.map((l) => { const [c, ...p] = l.split(" "); return [c, p]; }));
+    const parentsOf = new Map([...parentList].map(([c, p]) => [c, p.length]));
     report.runs = changeRuns(repo, [...parentsOf.keys()], policy.runners);
     if (opts.require === "attested-runs") {
         if (policy.runners.length === 0 && report.runs.commits.length > 0) {
@@ -145,24 +199,50 @@ export function verifyChange(opts) {
         report.commits.push(v);
     }
     // Protected writes: every commit that touches the policy needs a writer's signature.
+    const writers = policyWriters(policy);
+    const judge = (commit, paths, blocks) => {
+        const v = verdicts.get(commit) ?? { ...commitProvenance(repo, policy, commit, opts.attestors), commit, subject: "" };
+        const allowed = v.level === "attested" && v.principal !== undefined && writers.has(v.principal);
+        const who = policy.roles.admin?.length ? "an admin the policy at base names" : "a signer the policy at base lists";
+        const what = blocks ? `${paths.join(", ")} (${blocks.join(", ")})` : paths.join(", ");
+        const reason = allowed
+            ? `signed by ${v.principal}, ${who.replace(/^an? /, "")}`
+            : v.level === "attested"
+                ? `signed by ${v.principal}, who is not ${who}`
+                : `${what} is protected and needs a signature by ${who}: ${v.reason}`;
+        report.protectedWrites.push({ commit, paths, ...(blocks ? { blocks } : {}), level: v.level, ...(v.principal ? { principal: v.principal } : {}), allowed, reason });
+        if (!allowed)
+            report.failures.push(`${commit.slice(0, 8)} changes ${what}: ${reason}`);
+    };
     if (changedPaths.length > 0) {
-        const writers = policyWriters(policy);
         const touching = commitsTouching(repo, `${base.commit}..${head}`, report.protectedPaths);
         if (touching.size === 0) {
             report.failures.push(`the policy files ${changedPaths.join(", ")} differ from base, and no commit in the change accounts for it`);
         }
-        for (const [commit, paths] of touching) {
-            const v = verdicts.get(commit) ?? { ...commitProvenance(repo, policy, commit, opts.attestors), commit, subject: "" };
-            const allowed = v.level === "attested" && v.principal !== undefined && writers.has(v.principal);
-            const who = policy.roles.admin?.length ? "an admin the policy at base names" : "a signer the policy at base lists";
-            const reason = allowed
-                ? `signed by ${v.principal}, ${who.replace(/^an? /, "")}`
-                : v.level === "attested"
-                    ? `signed by ${v.principal}, who is not ${who}`
-                    : `${paths.join(", ")} is protected and needs a signature by ${who}: ${v.reason}`;
-            report.protectedWrites.push({ commit, paths, level: v.level, ...(v.principal ? { principal: v.principal } : {}), allowed, reason });
-            if (!allowed)
-                report.failures.push(`${commit.slice(0, 8)} changes ${paths.join(", ")}: ${reason}`);
+        for (const [commit, paths] of touching)
+            judge(commit, paths);
+    }
+    // The write scope in the declaration at base (#3079): a commit that changes writeScope or agents.
+    const scoped = scopedDeclarationAt(repo, opts.cwd ?? repo, base.commit);
+    if (scoped) {
+        const files = DECLARATION_FILES.map((name) => posix.join(scoped.dir, name));
+        const changed = changedBlocks(scopeState(repo, mergeBase, scoped.dir), scopeState(repo, head, scoped.dir));
+        report.declaration = { path: files.find((f) => fileAt(repo, base.commit, f) !== undefined) ?? files[0], blocks: scoped.blocks, changed };
+        if (changed.length > 0) {
+            let accounted = false;
+            for (const [commit, paths] of commitsTouching(repo, `${base.commit}..${head}`, files)) {
+                const after = scopeState(repo, commit, scoped.dir);
+                // A merge changes a block only when it differs from every parent.
+                const per = (parentList.get(commit) ?? []).map((p) => new Set(changedBlocks(scopeState(repo, p, scoped.dir), after)));
+                const blocks = SCOPE_BLOCKS.filter((b) => per.length > 0 && per.every((s) => s.has(b)));
+                if (blocks.length === 0)
+                    continue;
+                accounted = true;
+                judge(commit, paths, blocks);
+            }
+            if (!accounted) {
+                report.failures.push(`${changed.join(" and ")} in ${report.declaration.path} differ from base, and no commit in the change accounts for it`);
+            }
         }
     }
     // A new signer set must be signed by a threshold of the set at base (#2553).

package/dist/workspace/write-scope.d.ts

@@ -37,7 +37,7 @@
  * `write-scope-class-unknown` until the plugin is installed at the pinned
  * version or the entry is removed.
  */
-import { type AgentDeclaration, type ClassScope, type Declaration, type PrincipalClass, type ProtectedPath, type WriteVerb } from "./declaration.js";
+import { WorkspaceReadError, type AgentDeclaration, type ClassScope, type Declaration, type PrincipalClass, type ProtectedPath, type WriteVerb } from "./declaration.js";
 import { classesOf, roleGrants, type ClassRegistry } from "./principal-classes.js";
 import { type TrustPolicy } from "./trust/policy.js";
 import { AGENT_TRAILER } from "./trailers.js";
@@ -164,6 +164,8 @@ export interface ScopeSource {
     policy: TrustPolicy;
     /** The principal classes: the core four and those the declaration's pins supply, path pins read where the declaration was (#3080). */
     classes: ClassRegistry;
+    /** Why the working tree's declaration couldn't be read when `declaration` is null: declaration-missing, or declaration-invalid with the problem (#3433). */
+    failure?: WorkspaceReadError;
 }
 /**
  * The scope for a write from `cwd`: the declaration and the trust policy at

package/dist/workspace/write-scope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write-scope.d.ts","sourceRoot":"","sources":["../../src/workspace/write-scope.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"write-scope.d.ts","sourceRoot":"","sources":["../../src/workspace/write-scope.ts"],"names":[],"mappings":"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"}

package/dist/workspace/write-scope.js

@@ -275,17 +275,22 @@ export function judgePath(declaration, writer, path, change) {
         message: `${who(writer)} may not write ${path}${allowance}: writeScope.${writer.class}.protected lists ${guarded.path}`,
     };
 }
-function readAt(cwd, at) {
+/** The declaration at `at` (the working tree without it), or the read error that says why there is none. */
+function readOrFailure(cwd, at) {
     try {
         const located = locateWorkspace(cwd, at);
         return { declaration: readDeclaration(located.tree), rootOnDisk: located.rootOnDisk, root: located.root, tree: located.tree };
     }
     catch (err) {
         if (err instanceof WorkspaceReadError)
-            return null;
+            return err;
         throw err;
     }
 }
+function readAt(cwd, at) {
+    const read = readOrFailure(cwd, at);
+    return read instanceof WorkspaceReadError ? null : read;
+}
 /**
  * The scope for a write from `cwd`: the declaration and the trust policy at
  * the base revision (`origin/HEAD`, `main` or `master`), so a write can't
@@ -306,8 +311,10 @@ export function scopeSource(cwd, at) {
         if (atBase)
             return { ...withClasses(atBase), from: "base", policy };
     }
-    const here = readAt(cwd);
-    return here ? { ...withClasses(here), from: "working-tree", policy } : { declaration: null, from: null, rootOnDisk: null, root: null, policy, classes: coreClassRegistry() };
+    const here = readOrFailure(cwd);
+    if (here instanceof WorkspaceReadError)
+        return { declaration: null, from: null, rootOnDisk: null, root: null, policy, classes: coreClassRegistry(), failure: here };
+    return { ...withClasses(here), from: "working-tree", policy };
 }
 const toPosix = (p) => (sep === "/" ? p : p.split(sep).join("/"));
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.124.23",
+  "version": "0.124.25",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/ci-jobs.ts

@@ -15,7 +15,9 @@
  *  - the `setup` steps and `environment` a job may carry, checked once per
  *    forge ({@link assertSetupSteps}, {@link assertEnvironment},
  *    {@link gitlabSetupScript}, {@link assertGitlabEnvironment});
- *  - GitLab's `rules:` expressions and `id_tokens:` declaration.
+ *  - GitLab's `rules:` expressions and `id_tokens:` declaration;
+ *  - where a job runs and the id tokens it asks for (#3914), {@link githubRunsOn},
+ *    {@link gitlabTags}, {@link gitlabIdTokensDoc} and {@link idTokenAudienceEnv}.
  *
  * The Forgejo dialect (action refs, dropped `permissions:` and
  * `environment:`, the header note naming what was dropped) is the forgejo
@@ -96,11 +98,66 @@ export function dirnameOf(path: string): string {
   return i <= 0 ? "." : path.slice(0, i);
 }
 
+/**
+ * Where a generated job runs (#3914): a runner label, a list of labels the
+ * runner must all carry, or on GitHub a runner group with optional labels.
+ * `runs-on` on GitHub and Forgejo, `tags` on GitLab.
+ */
+export type CiRunner = string | readonly string[] | { group: string; labels?: readonly string[] };
+
+/** True when `runner` is a GitHub runner group, which only GitHub has. */
+export function isRunnerGroup(runner: CiRunner | undefined): runner is { group: string; labels?: readonly string[] } {
+  return runner !== undefined && typeof runner === "object" && !Array.isArray(runner);
+}
+
+/**
+ * Refuse a runner group on a forge that has none (#3914). `subject` and
+ * `field` name whose runner it is, such as `Op waves "x"` and `wave "prod"
+ * runner`.
+ */
+export function assertRunnerLabels(subject: string, field: string, runner: CiRunner | undefined, forge: "GitLab" | "Forgejo"): void {
+  if (!isRunnerGroup(runner)) return;
+  throw new Error(
+    `${subject}: ${field} is the runner group "${runner.group}", which only GitHub has. ` +
+      `${forge === "GitLab" ? "GitLab picks a runner by its tags" : "Forgejo picks a runner by its labels"}; give a label or a list of labels.`,
+  );
+}
+
+/**
+ * Each id token's audience as a variable, `<NAME>_AUDIENCE` (#3914). On
+ * GitHub and Forgejo the audience is chosen when the job requests the token,
+ * so the job reads it from there; GitLab declares it in `id_tokens:`
+ * ({@link gitlabIdTokensDoc}).
+ */
+export function idTokenAudienceEnv(idTokens: Readonly<Record<string, string>> | undefined): Record<string, string> {
+  return Object.fromEntries(Object.entries(idTokens ?? {}).map(([name, aud]) => [`${name}_AUDIENCE`, aud]));
+}
+
+/** A job's GitLab `id_tokens:` for `{ <variable>: <audience> }` (#3914), or undefined when there are none. */
+export function gitlabIdTokensDoc(idTokens: Readonly<Record<string, string>> | undefined): Record<string, { aud: string }> | undefined {
+  const entries = Object.entries(idTokens ?? {});
+  return entries.length > 0 ? Object.fromEntries(entries.map(([name, aud]) => [name, { aud }])) : undefined;
+}
+
+/** A job's GitLab `tags:` for `runner` (#3914), or undefined when it names none. */
+export function gitlabTags(runner: CiRunner | undefined): string[] | undefined {
+  if (runner === undefined || isRunnerGroup(runner)) return undefined;
+  return typeof runner === "string" ? [runner] : [...runner];
+}
+
 // ── GitHub Actions and Forgejo Actions ──────────────────────────────────────
 
 /** The runner label a generated job asks for; the Forgejo dialect rewrites it to the project's label. */
 export const GITHUB_RUNNER = "ubuntu-latest";
 
+/** A job's `runs-on` for `runner` (#3914): {@link GITHUB_RUNNER} when it names none. */
+export function githubRunsOn(runner: CiRunner | undefined): string | string[] | { group: string; labels?: string[] } {
+  if (runner === undefined) return GITHUB_RUNNER;
+  if (typeof runner === "string") return runner;
+  if (isRunnerGroup(runner)) return { group: runner.group, ...(runner.labels && runner.labels.length > 0 ? { labels: [...runner.labels] } : {}) };
+  return [...runner];
+}
+
 /** The job token, which GitHub and Forgejo both mint for every run. */
 export const GITHUB_JOB_TOKEN = "${{ github.token }}";
 

package/src/cli/commands/build.ts

@@ -32,6 +32,7 @@ import { loadPolicyChecks } from "../../lint/policy";
 import { armSandboxPolicyExecution, runProjectPolicies } from "../../lint/policy-sandbox";
 import { sortedJsonReplacer } from "../../utils";
 import { rankFoldBlockers, toCollapsedFormat, type FoldRankResult } from "../../discovery/fold-rank";
+import { foldExecutionCounts } from "../../discovery/fold-import";
 import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format";
 import { writeFileSync, mkdirSync } from "fs";
 import { resolve, dirname, join, relative } from "path";
@@ -396,6 +397,23 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
             : (decision.reason ?? "fell back to run");
         console.error(formatInfo(`[fold:${decision.mode}] ${rel} — ${detail}`));
       }
+      // typescript-as-data#177 — the exact instrument beside the sampled one.
+      // `test/leftness` reports "0 MB of definition-library code on the path"
+      // from a `node --cpu-prof` recording, and a profile has a sampling
+      // floor: 0 MB is everything the profiler could see rather than nothing
+      // having run. L10.1's counters have no floor.
+      //
+      // Inside --verbose with the per-file lines, not beside them. The default
+      // path is deliberately quiet for the reason above, and the leftness
+      // capture already runs --verbose and greps this log for `[fold:fold]`.
+      const counts = foldExecutionCounts();
+      console.error(
+        formatInfo(
+          `[fold:counts] factoryInvocations=${counts.factoryInvocations} ` +
+            `projectFactoryInvocations=${counts.projectFactoryInvocations} ` +
+            `factoryInterpretations=${counts.factoryInterpretations}`,
+        ),
+      );
     } else {
       console.error(formatInfo(summarizeFoldDecisions(result.foldDecisions)));
     }

package/src/cli/compiled-cli.e2e.test.ts

@@ -7,7 +7,9 @@
  * Each run is traced through a load hook that NODE_OPTIONS hands to the CLI's
  * node, so the test can say what loaded: none of chant's TypeScript source,
  * ever, and tsx only for a command that imports TypeScript (here the
- * lexicon and the project source).
+ * lexicon and the project source). tsx's ESM hooks run on a thread of their
+ * own, about 200 MB of the process (#3276), so a workspace read must not
+ * register it either.
  *
  * End to end because it packs, installs from the registry and spawns the CLI.
  */
@@ -20,12 +22,14 @@ import { afterAll, beforeAll, describe, expect, test } from "vitest";
 
 const coreRoot = resolve(import.meta.dirname, "..", "..");
 const renderRoot = resolve(coreRoot, "..", "..", "lexicons", "render");
+const referenceDecisions = resolve(coreRoot, "..", "..", "reference-workspace", "decisions");
 const version = (JSON.parse(readFileSync(join(coreRoot, "package.json"), "utf-8")) as { version: string }).version;
 
 let scratch: string;
 let project: string;
 let cjsProject: string;
 let waves: string;
+let workspace: string;
 let chant: string;
 let tracer: string;
 
@@ -126,6 +130,31 @@ beforeAll(() => {
   writeFileSync(join(waves, ".gitignore"), ".chant/\n");
   git("add", "-A");
   git("commit", "-qm", "ignore");
+
+  // A workspace whose declaration names a .mjs record kind, with a member
+  // that has a chant.config.ts, for the workspace reads below (#3276).
+  workspace = join(scratch, "workspace");
+  mkdirSync(join(workspace, "decisions"), { recursive: true });
+  mkdirSync(join(workspace, "app"));
+  for (const file of ["decision.kind.mjs", "decision.schema.json", "ref-001-how-the-app-is-deployed.md"]) {
+    writeFileSync(join(workspace, "decisions", file), readFileSync(join(referenceDecisions, file)));
+  }
+  writeFileSync(
+    join(workspace, "chant.workspace.json"),
+    JSON.stringify({
+      name: "e2e",
+      schema: 1,
+      members: [{ name: "app", dir: "app", kind: "chant" }],
+      records: [{ kind: "decisions/decision.kind.mjs" }],
+    }),
+  );
+  writeFileSync(join(workspace, "app", "chant.config.ts"), `export default { lexicons: [] as string[] };\n`);
+  symlinkSync(join(project, "node_modules"), join(workspace, "node_modules"), "dir");
+  const wsGit = (...args: string[]) => execFileSync("git", ["-c", "user.email=e2e@chant", "-c", "user.name=e2e", ...args], { cwd: workspace, stdio: "ignore" });
+  wsGit("init", "-q", "-b", "main");
+  writeFileSync(join(workspace, ".gitignore"), "node_modules\n");
+  wsGit("add", "-A");
+  wsGit("commit", "-qm", "workspace");
 }, 600_000);
 
 afterAll(() => {
@@ -148,6 +177,21 @@ describe("the installed chant CLI (#3878)", () => {
     expect(r.loaded).toMatchObject({ chantSrc: 0, tsx: 0 });
   });
 
+  test("workspace ls reads a .mjs record kind from a member with a chant.config.ts without loading tsx", () => {
+    const r = run(join(workspace, "app"), ["workspace", "ls", "--json"]);
+    expect(r.status, r.stderr).toBe(0);
+    const ls = JSON.parse(r.stdout) as { workspace: { records: Array<{ name: string; kind: string | null }> } };
+    expect(ls.workspace.records.map((k) => k.kind)).toEqual(["decision"]);
+    expect(r.loaded).toMatchObject({ chantSrc: 0, tsx: 0 });
+  });
+
+  test("workspace records reads the declared .mjs kind's records without loading tsx", () => {
+    const r = run(join(workspace, "app"), ["workspace", "records", "--json"]);
+    expect(r.status, r.stderr).toBe(0);
+    expect(r.stdout).toContain("ref-001");
+    expect(r.loaded).toMatchObject({ chantSrc: 0, tsx: 0 });
+  });
+
   test("build loads the TypeScript lexicon and project through tsx, against the one compiled core", () => {
     const r = run(project, ["build", "src", "-o", "out/render.json"]);
     expect(r.status, r.stderr).toBe(0);

package/src/cli/handlers/approve.ts

@@ -24,6 +24,7 @@ import { FAN_OUT_GATE_OP, OVERRIDE_GATE_OP, WORKSPACE_UPGRADE_GATE_OP } from "..
 import { PR_GATE_OP } from "../../pr-loop";
 import { pushLifecycleReport, requireLifecycleLedger } from "../../lifecycle/git";
 import { LIFECYCLE_LOCAL_NOTE, isLifecycleLocalNote } from "../../lifecycle/local-note";
+import { ledgerRecordingOff, NO_RECORD_ENV } from "../../lifecycle/no-record";
 import { formatError, formatWarning, formatSuccess, formatInfo } from "../format";
 import type { CommandContext } from "../registry";
 
@@ -267,6 +268,14 @@ export async function recordGateApproval(
   gate: string,
   opts: GateApprovalOptions,
 ): Promise<GateApprovalOutcome> {
+  // #3955: with recording off the approval would be dropped with the process.
+  if (ledgerRecordingOff()) {
+    console.error(formatError({
+      message: `Cannot record the approval of "${gate}": ${NO_RECORD_ENV} is set, so nothing is written to chant/lifecycle`,
+      hint: `Unset ${NO_RECORD_ENV} to approve the gate.`,
+    }));
+    return { ok: false };
+  }
   const { ops } = await discoverOps();
   // `fan-out` is the op name every `chant components fan-out` gate is recorded
   // under (../handlers/fan-out.ts). It is a command rather than a declaration,

package/src/cli/handlers/emulator.test.ts

@@ -42,7 +42,7 @@ vi.mock("node:child_process", async () => {
   return { ...actual, exec: execWithCustom, execFile: execFileWithCustom };
 });
 
-const { runEmulator, formatEmulatorHelp, parsePortMappings } = await import("./emulator");
+const { runEmulator, formatEmulatorHelp, parsePortMappings, parseUpOptions } = await import("./emulator");
 
 function cap(): EmulatorCapability {
   return {
@@ -286,3 +286,63 @@ describe("chant emulator --port and --help (#3673)", () => {
     expect(formatEmulatorHelp([])).toContain("No lexicon configured for this project has a local emulator.");
   });
 });
+
+describe("chant emulator up --image, --network, --setting, --loopback (#3952)", () => {
+  const floci = (): EmulatorCapability => ({ ...cap(), spec: { ...cap().spec, settingsPrefix: "FLOCI_" } });
+  const other = (): EmulatorCapability => ({
+    spec: { name: "chant-floci-az", image: "floci/floci-az:1.0.0", containerPort: 4577, healthPath: "/health" },
+    env: () => ({}),
+  });
+
+  beforeEach(() => {
+    upMock.mockReset();
+    vi.restoreAllMocks();
+  });
+
+  test("up passes each option to the lifecycle", async () => {
+    stderr();
+    upMock.mockResolvedValue({ endpoint: "http://localhost:4566" });
+    const exit = await runEmulator({
+      args: makeArgs({
+        path: "up", image: "floci/floci:1.6.0", network: "loom", loopback: true,
+        setting: ["FLOCI_STORAGE_MODE=memory", "FLOCI_X=a=b"], port: ["4567"],
+      }),
+      plugins: [plugin("aws", floci())],
+      serializers: [],
+    });
+    expect(exit).toBe(0);
+    expect(upMock).toHaveBeenCalledWith({
+      image: "floci/floci:1.6.0", network: "loom", loopback: true,
+      settings: { FLOCI_STORAGE_MODE: "memory", FLOCI_X: "a=b" }, port: 4567,
+    });
+  });
+
+  test("a setting no selected emulator takes is refused before anything starts", async () => {
+    const err = stderr();
+    const exit = await runEmulator({
+      args: makeArgs({ path: "up", setting: ["HOME=/tmp"] }),
+      plugins: [plugin("aws", floci())],
+      serializers: [],
+    });
+    expect(exit).toBe(1);
+    expect(upMock).not.toHaveBeenCalled();
+    expect(err.join("\n")).toContain("--setting HOME: no selected emulator takes it; the selected ones take FLOCI_* (chant-floci)");
+  });
+
+  test("settings go only to the emulator whose prefix matches; --image needs one emulator", () => {
+    const a = floci();
+    const b = other();
+    const opts = parseUpOptions({ setting: ["FLOCI_A=1"], network: "n" }, [a, b]);
+    expect(opts.get(a)).toEqual({ network: "n", settings: { FLOCI_A: "1" } });
+    expect(opts.get(b)).toEqual({ network: "n" });
+    expect(() => parseUpOptions({ image: "x:1" }, [a, b])).toThrow(/--image x:1 is ambiguous with 2 emulators/);
+    expect(() => parseUpOptions({ setting: ["FLOCI_A"] }, [a])).toThrow(/expected <KEY>=<VALUE>/);
+  });
+
+  test("the options apply to up only", async () => {
+    const err = stderr();
+    const exit = await runEmulator({ args: makeArgs({ path: "status", loopback: true }), plugins: [plugin("aws", floci())], serializers: [] });
+    expect(exit).toBe(1);
+    expect(err.join("\n")).toContain("--loopback applies to `chant emulator up` only");
+  });
+});

package/src/cli/handlers/emulator.ts

@@ -1,9 +1,9 @@
 import { exec, execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { emulatorLifecycle, emulatorsOf, type EmulatorCapability } from "../../op";
+import { checkSettings, emulatorLifecycle, emulatorsOf, type EmulatorCapability, type EmulatorUpArgs } from "../../op";
 import type { LexiconPlugin } from "../../lexicon";
 import { formatError, formatWarning, formatSuccess } from "../format";
-import type { CommandContext } from "../registry";
+import type { CommandContext, ParsedArgs } from "../registry";
 
 const execAsync = promisify(exec);
 const execFileAsync = promisify(execFile);
@@ -116,13 +116,60 @@ export function parsePortMappings(values: readonly string[], targets: readonly E
   return ports;
 }
 
+/** The `up` options other than the port (#3952), per selected emulator. */
+type UpOptions = Pick<EmulatorUpArgs, "image" | "network" | "settings" | "loopback">;
+
+/**
+ * `--image`, `--network`, `--setting` and `--loopback` as each selected
+ * emulator's `up` options (#3952). `--image` needs exactly one emulator
+ * selected, the way a bare `--port` does. A `--setting` goes to each emulator
+ * whose settings prefix its key starts with, and a key that no selected
+ * emulator takes is refused rather than passed to a container as plain env.
+ */
+export function parseUpOptions(
+  args: Pick<ParsedArgs, "image" | "network" | "setting" | "loopback">,
+  targets: readonly EmulatorCapability[],
+): Map<EmulatorCapability, UpOptions> {
+  if (args.image !== undefined && targets.length !== 1) {
+    throw new Error(`--image ${args.image} is ambiguous with ${targets.length} emulators selected; pick one with --lexicon <name>`);
+  }
+  const settings = new Map<EmulatorCapability, Record<string, string>>();
+  for (const value of args.setting ?? []) {
+    const match = /^([^=]+)=(.*)$/s.exec(value);
+    if (!match) throw new Error(`--setting ${value}: expected <KEY>=<VALUE>, e.g. --setting FLOCI_<NAME>=<value>`);
+    const [, key, val] = match as unknown as [string, string, string];
+    const takers = targets.filter((t) => t.spec.settingsPrefix && key.startsWith(t.spec.settingsPrefix));
+    if (takers.length === 0) {
+      const prefixes = targets.filter((t) => t.spec.settingsPrefix).map((t) => `${t.spec.settingsPrefix}* (${t.spec.name})`);
+      throw new Error(`--setting ${key}: no selected emulator takes it; ${prefixes.length ? `the selected ones take ${prefixes.join(", ")}` : "the selected ones take no settings"}`);
+    }
+    for (const t of takers) {
+      const own = { ...settings.get(t), [key]: val };
+      checkSettings(t.spec, own);
+      settings.set(t, own);
+    }
+  }
+  const out = new Map<EmulatorCapability, UpOptions>();
+  for (const t of targets) {
+    const opts: UpOptions = {};
+    if (args.image !== undefined) opts.image = args.image;
+    if (args.network !== undefined) opts.network = args.network;
+    if (args.loopback) opts.loopback = true;
+    const own = settings.get(t);
+    if (own) opts.settings = own;
+    out.set(t, opts);
+  }
+  return out;
+}
+
 /**
  * `chant emulator --help` (#3673): the subcommands and flags, and for each
  * configured lexicon's emulator the port, endpoint and sign-in a client uses.
  */
 export function formatEmulatorHelp(plugins: readonly LexiconPlugin[]): string {
   const lines = [
-    "Usage: chant emulator <up|down|status> [--lexicon <name>] [--port <container-port>=<host-port>] [--json]",
+    "Usage: chant emulator <up|down|status> [--lexicon <name>] [--port <container-port>=<host-port>] [--image <ref>]",
+    "       [--network <name>] [--setting <KEY>=<VALUE>] [--loopback] [--json]",
     "",
     "Boot, stop or inspect the local emulators of the project's configured lexicons.",
     "",
@@ -137,6 +184,11 @@ export function formatEmulatorHelp(plugins: readonly LexiconPlugin[]): string {
     "  --lexicon <name>     Act on one lexicon's emulators only.",
     "  --port <c>=<h>       up: publish container port <c> on host port <h>; repeatable.",
     "                       A bare <h> works when one emulator is selected.",
+    "  --image <ref>        up: start this image instead of the pinned default; one emulator only.",
+    "  --network <name>     up: join each started container to this Docker network.",
+    "  --setting <K>=<V>    up: pass an emulator setting as -e K=V; repeatable. The key must",
+    "                       start with the emulator's prefix (FLOCI_ for aws).",
+    "  --loopback           up: publish ports on 127.0.0.1 only, not on every interface.",
     "  --json               Print the machine-readable report on stdout.",
     "",
   ];
@@ -195,9 +247,18 @@ export async function runEmulator(ctx: CommandContext): Promise<number> {
   }
 
   let ports: Map<number, number>;
+  let upOptions: Map<EmulatorCapability, UpOptions>;
   try {
     if (args.port?.length && action !== "up") throw new Error("--port applies to `chant emulator up` only");
+    const upOnly = [
+      args.image !== undefined && "--image",
+      args.network !== undefined && "--network",
+      args.setting?.length && "--setting",
+      args.loopback && "--loopback",
+    ].filter(Boolean);
+    if (upOnly.length && action !== "up") throw new Error(`${upOnly.join(", ")} applies to \`chant emulator up\` only`);
     ports = parsePortMappings(args.port ?? [], targets.map((t) => t.cap));
+    upOptions = parseUpOptions(args, targets.map((t) => t.cap));
   } catch (err) {
     console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
     return 1;
@@ -209,7 +270,7 @@ export async function runEmulator(ctx: CommandContext): Promise<number> {
     if (action === "up") {
       const port = ports.get(cap.spec.containerPort);
       try {
-        const { endpoint } = await lc.up(port === undefined ? {} : { port });
+        const { endpoint } = await lc.up({ ...upOptions.get(cap), ...(port === undefined ? {} : { port }) });
         reports.push({ lexicon, name: cap.spec.name, endpoint, env: cap.env(endpoint) });
       } catch (err) {
         console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));