@intentius/chant 0.19.1 → 0.20.0

package/src/fold/subset.ts

@@ -0,0 +1,302 @@
+import * as ts from "typescript";
+
+/**
+ * subset — the single canonical definition of chant's statically-foldable
+ * expression subset (chant #1024, epic #1019).
+ *
+ * `fold()` ({@link "./fold"}, the enforcement layer — a construct outside
+ * this subset simply has no case there) and EVL001/EVL003
+ * ({@link "../lint/rules/evl001-non-literal-expression"},
+ * {@link "../lint/rules/evl003-dynamic-property-access"} — the pre-flight
+ * diagnostic layer) both import this module so the two can never drift
+ * apart on *which node kinds, operators, and key shapes* are foldable.
+ * Before this module existed, `fold()` and EVL001 each hand-rolled their
+ * own recursive classifier; they agreed almost everywhere but had several
+ * real, silent gaps (see git history of #1024 for the enumerated list —
+ * dynamic object-literal keys, template/tagged-template interiors, and
+ * unrestricted binary/unary operators were all accepted by EVL001 but
+ * rejected by `fold()`). This module is the fix: one classifier, two
+ * importers.
+ *
+ * Scope — this module classifies *shape* only: the syntactic kind of an
+ * expression, its operator, and (for keys) its literal-ness. It
+ * deliberately does NOT resolve bindings or perform any evaluation, because
+ * three things a full fold needs are inherently environment-dependent and
+ * cannot be recovered from shape alone:
+ *
+ *   1. Identifier *resolution* — is a bare name actually a local `const`,
+ *      vs. an unbound name? That needs the file's `consts` map. Both
+ *      `fold()` and this module treat a bare identifier as shape-valid;
+ *      `fold()` alone resolves it (and rejects if unresolved) once it has
+ *      that map. A lint rule has no equivalent binding-resolution pass
+ *      today, so EVL (via this module) stays permissive here — a known,
+ *      intentional asymmetry, not a bug: it can only ever be a *false
+ *      negative* on EVL's part (EVL passes something `fold()` might later
+ *      reject for being unresolved), never the reverse.
+ *   2. Tagged-template *tag registration* — needs a lexicon's intrinsics
+ *      manifest, which isn't available to a syntax-only lint rule. `fold()`
+ *      alone checks it; this module treats any tag name as shape-valid and
+ *      only classifies the interpolated values.
+ *   3. Runtime *type* of a folded value — e.g. spreading `const n = 5`
+ *      (`{...n}`) is shape-valid (`n` is a plain identifier) but `fold()`
+ *      rejects it once it discovers `n` folds to a number, not an object.
+ *      Only real evaluation catches this; EVL004 independently narrows
+ *      spread sources to a stricter "traceable to a const" shape, which
+ *      catches most real-world misuse without evaluating, but is not a
+ *      full substitute.
+ *
+ * One more inherent gap, on the *value-flow* side rather than shape:
+ * `fold()` evaluates `&&`/`||`/`??` and `? :` lazily — it only folds the
+ * side/branch actually taken, exactly like the JS runtime — so an
+ * otherwise-unfoldable *untaken* branch does not reject
+ * (`false && sideEffect()` folds cleanly to `false`). This module (and so
+ * EVL) is flow-insensitive: it has no notion of "taken", so it requires
+ * every operand/branch to be shape-valid. This can only make EVL *stricter*
+ * than `fold()` (a false positive relative to fold, flagging code the
+ * folder would actually accept) — never the reverse. Making EVL
+ * flow-sensitive would mean re-implementing an evaluator inside a lint
+ * rule; out of scope here. See #1024.
+ */
+
+/** The two EVL rule ids a shape violation can be attributed to. */
+export type SubsetRuleId = "EVL001" | "EVL003";
+
+/** A located, shape-level rejection: the offending node, the EVL rule id it maps to, and a message. */
+export interface SubsetViolation {
+  node: ts.Node;
+  ruleId: SubsetRuleId;
+  message: string;
+}
+
+function violation(node: ts.Node, message: string, ruleId: SubsetRuleId = "EVL001"): SubsetViolation {
+  return { node, ruleId, message };
+}
+
+/** Binary operators `fold()` implements — see `fold()`'s operator switch in ./fold.ts. */
+export const SUPPORTED_BINARY_OPERATORS: ReadonlySet<ts.SyntaxKind> = new Set([
+  ts.SyntaxKind.AmpersandAmpersandToken,
+  ts.SyntaxKind.BarBarToken,
+  ts.SyntaxKind.QuestionQuestionToken,
+  ts.SyntaxKind.PlusToken,
+  ts.SyntaxKind.MinusToken,
+  ts.SyntaxKind.AsteriskToken,
+  ts.SyntaxKind.SlashToken,
+  ts.SyntaxKind.EqualsEqualsEqualsToken,
+  ts.SyntaxKind.ExclamationEqualsEqualsToken,
+  ts.SyntaxKind.GreaterThanToken,
+  ts.SyntaxKind.LessThanToken,
+  ts.SyntaxKind.GreaterThanEqualsToken,
+  ts.SyntaxKind.LessThanEqualsToken,
+]);
+
+/** Prefix unary operators `fold()` implements: logical-not and numeric negation. */
+export const SUPPORTED_UNARY_OPERATORS: ReadonlySet<ts.SyntaxKind> = new Set([
+  ts.SyntaxKind.ExclamationToken,
+  ts.SyntaxKind.MinusToken,
+]);
+
+/** A property name foldable without execution: identifier, string, or numeric literal (not a computed name). */
+export function isLiteralPropertyName(
+  node: ts.PropertyName,
+): node is ts.Identifier | ts.StringLiteral | ts.NumericLiteral {
+  return ts.isIdentifier(node) || ts.isStringLiteral(node) || ts.isNumericLiteral(node);
+}
+
+/** An element-access key foldable without execution: a string or numeric LITERAL only (EVL003 semantics). */
+export function isLiteralElementKey(node: ts.Expression): node is ts.StringLiteral | ts.NumericLiteral {
+  return ts.isStringLiteral(node) || ts.isNumericLiteral(node);
+}
+
+// ---------------------------------------------------------------------------
+// Shared message builders — `fold()` and `findSubsetViolation` both call
+// these so the diagnostic text for the same violation kind is the same
+// string, not two hand-written copies that can drift.
+// ---------------------------------------------------------------------------
+
+export function computedPropertyNameMessage(node: ts.PropertyName): string {
+  return `computed/dynamic property name not foldable: ${node.getText()}`;
+}
+
+export function dynamicElementAccessMessage(keyNode: ts.Expression): string {
+  return `dynamic property access — computed key must be a string or numeric literal: ${keyNode.getText()}`;
+}
+
+export const UNSUPPORTED_OBJECT_MEMBER_MESSAGE = "unsupported object member";
+
+export const UNSUPPORTED_UNARY_MESSAGE = "unsupported unary";
+
+export function unsupportedBinaryMessage(opKind: ts.SyntaxKind): string {
+  return `unsupported binary operator: ${ts.SyntaxKind[opKind]}`;
+}
+
+export function callExpressionMessage(node: ts.CallExpression): string {
+  return `function call as a value is not foldable: ${node.expression.getText()}(...)`;
+}
+
+export function unsupportedExpressionMessage(node: ts.Node): string {
+  return `unsupported expression: ${ts.SyntaxKind[node.kind]}`;
+}
+
+export function resourceCtorArgMessage(typeName: string): string {
+  return `resource constructor argument must be an object literal: ${typeName}(...)`;
+}
+
+/**
+ * Classify one object-literal member (`{ a: 1 }`'s `a: 1`, `{ ...x }`'s
+ * `...x`, or a shorthand `{ a }`). Checks the key's shape before the
+ * value's, mirroring `propName()` in fold.ts, which runs before folding
+ * the value. Returns the first violation within this member, or
+ * `undefined` when it's fully in the subset.
+ */
+export function checkObjectMember(prop: ts.ObjectLiteralElementLike): SubsetViolation | undefined {
+  if (ts.isPropertyAssignment(prop)) {
+    if (!isLiteralPropertyName(prop.name)) {
+      return violation(prop.name, computedPropertyNameMessage(prop.name));
+    }
+    return findSubsetViolation(prop.initializer);
+  }
+  if (ts.isShorthandPropertyAssignment(prop)) {
+    return undefined;
+  }
+  if (ts.isSpreadAssignment(prop)) {
+    return findSubsetViolation(prop.expression);
+  }
+  return violation(prop, UNSUPPORTED_OBJECT_MEMBER_MESSAGE);
+}
+
+/** Classify one array-literal element: a value, or a `...spread`. */
+function checkArrayElement(el: ts.Expression): SubsetViolation | undefined {
+  if (ts.isSpreadElement(el)) return findSubsetViolation(el.expression);
+  return findSubsetViolation(el);
+}
+
+/**
+ * The canonical recursive shape classifier: is `node`'s expression *shape*
+ * within the subset `fold()` can reduce? Mirrors `fold()`'s own dispatch
+ * node-kind for node-kind (see ./fold.ts) — every branch here has a
+ * matching branch there, and vice versa — but performs no
+ * resolution/evaluation (see the module doc comment for the three
+ * environment-dependent exceptions). Returns the first (deepest,
+ * `fold()`-evaluation-order) unsupported node, or `undefined` when `node`'s
+ * whole shape is foldable.
+ */
+export function findSubsetViolation(node: ts.Node): SubsetViolation | undefined {
+  if (
+    ts.isParenthesizedExpression(node) ||
+    ts.isAsExpression(node) ||
+    ts.isSatisfiesExpression(node) ||
+    ts.isNonNullExpression(node)
+  ) {
+    return findSubsetViolation(node.expression);
+  }
+
+  if (
+    ts.isStringLiteral(node) ||
+    ts.isNoSubstitutionTemplateLiteral(node) ||
+    ts.isNumericLiteral(node) ||
+    node.kind === ts.SyntaxKind.TrueKeyword ||
+    node.kind === ts.SyntaxKind.FalseKeyword ||
+    node.kind === ts.SyntaxKind.NullKeyword
+  ) {
+    return undefined;
+  }
+
+  // Identifiers (including a bare `undefined` reference, which the parser
+  // represents as an Identifier, not a keyword token) — resolution is
+  // environment-dependent, see module doc.
+  if (ts.isIdentifier(node)) return undefined;
+
+  if (ts.isTaggedTemplateExpression(node)) {
+    // Tagged-template interiors are OPAQUE to the shape classifier. A tagged
+    // template may be a registered lexicon intrinsic (e.g. Sub`...`) whose
+    // interpolations legitimately contain deploy-time intrinsic references
+    // (Ref(env), AWS.StackName, ...) — valid, but not statically foldable. EVL
+    // has no intrinsic registry at lint time (see module doc), so it cannot tell
+    // an intrinsic call from a plain one; recursing here would false-flag Ref()
+    // inside Sub`...` and break every intrinsic-using example. fold() DOES have
+    // the registry: it recurses into a *registered* tag's interior itself
+    // (foldIntrinsicValue) and rejects an unfoldable one there. So an unfoldable
+    // tagged-template interior is a documented fold/EVL divergence, not a hole.
+    return undefined;
+  }
+
+  if (ts.isTemplateExpression(node)) {
+    for (const span of node.templateSpans) {
+      const v = findSubsetViolation(span.expression);
+      if (v) return v;
+    }
+    return undefined;
+  }
+
+  if (ts.isObjectLiteralExpression(node)) {
+    for (const prop of node.properties) {
+      const v = checkObjectMember(prop);
+      if (v) return v;
+    }
+    return undefined;
+  }
+
+  if (ts.isArrayLiteralExpression(node)) {
+    for (const el of node.elements) {
+      const v = checkArrayElement(el);
+      if (v) return v;
+    }
+    return undefined;
+  }
+
+  if (ts.isPropertyAccessExpression(node)) {
+    return findSubsetViolation(node.expression);
+  }
+
+  if (ts.isElementAccessExpression(node)) {
+    if (!isLiteralElementKey(node.argumentExpression)) {
+      return violation(node.argumentExpression, dynamicElementAccessMessage(node.argumentExpression), "EVL003");
+    }
+    return findSubsetViolation(node.expression);
+  }
+
+  if (ts.isPrefixUnaryExpression(node)) {
+    if (!SUPPORTED_UNARY_OPERATORS.has(node.operator)) {
+      return violation(node, UNSUPPORTED_UNARY_MESSAGE);
+    }
+    return findSubsetViolation(node.operand);
+  }
+
+  if (ts.isBinaryExpression(node)) {
+    const opKind = node.operatorToken.kind;
+    if (!SUPPORTED_BINARY_OPERATORS.has(opKind)) {
+      return violation(node, unsupportedBinaryMessage(opKind));
+    }
+    // Flow-insensitive — see module doc: fold() short-circuits &&/||/?? and
+    // only evaluates the taken side; EVL requires both sides shape-valid.
+    return findSubsetViolation(node.left) ?? findSubsetViolation(node.right);
+  }
+
+  if (ts.isConditionalExpression(node)) {
+    // Flow-insensitive — see module doc: fold() only folds the taken branch.
+    return (
+      findSubsetViolation(node.condition) ??
+      findSubsetViolation(node.whenTrue) ??
+      findSubsetViolation(node.whenFalse)
+    );
+  }
+
+  if (ts.isNewExpression(node)) {
+    const [firstArg] = node.arguments ?? [];
+    if (!firstArg) return undefined;
+    if (!ts.isObjectLiteralExpression(firstArg)) {
+      return violation(firstArg, resourceCtorArgMessage(node.expression.getText()));
+    }
+    return findSubsetViolation(firstArg);
+  }
+
+  if (ts.isSpreadElement(node)) {
+    return findSubsetViolation(node.expression);
+  }
+
+  if (ts.isCallExpression(node)) {
+    return violation(node, callExpressionMessage(node));
+  }
+
+  return violation(node, unsupportedExpressionMessage(node));
+}

package/src/index.ts

@@ -7,6 +7,7 @@
 export * from "./declarable";
 export * from "./composite";
 export * from "./provenance";
+export * from "./build-params";
 export * from "./intrinsic";
 export * from "./types";
 export * from "./errors";
@@ -33,6 +34,7 @@ export * from "./graph-dot";
 export * from "./graph-layout";
 export * from "./graph-lens";
 export * from "./detectLexicon";
+export * from "./fold/fold";
 export * from "./lint/parser";
 export * from "./lint/rule";
 export * from "./lint/rules";

package/src/lexicon-output.ts

@@ -45,8 +45,13 @@ export class LexiconOutput implements Intrinsic {
   readonly outputName: string;
   /** @internal WeakRef to the source entity object for identity-based matching */
   readonly _sourceParent: WeakRef<object> | null;
-  /** @internal Intrinsic value when constructed from an Intrinsic rather than AttrRef */
-  private readonly _intrinsic: Intrinsic | null;
+  /**
+   * @internal Intrinsic value when constructed from an Intrinsic rather than AttrRef.
+   * Readable outside the class (like `_sourceParent` above) so the entity-wire
+   * encoder can reach it without an `as unknown as` cast that would erase type
+   * checking on every field it reads (#1047).
+   */
+  readonly _intrinsic: Intrinsic | null;
 
   constructor(ref: AttrRef | Intrinsic | string, name: string) {
     if (ref instanceof AttrRef) {

package/src/lexicon-schema.test.ts

@@ -131,6 +131,20 @@ describe("IntrinsicDefSchema", () => {
     const result = IntrinsicDefSchema.safeParse({ description: "no name" });
     expect(result.success).toBe(false);
   });
+
+  // chant #1067 — isTag went from optional to required: a registration
+  // silently defaulting to "not a tag" is exactly how #1039 shipped
+  // (aws's Sub had no isTag at all and never folded in production).
+  test("rejects a registration with isTag omitted", () => {
+    const result = IntrinsicDefSchema.safeParse({ name: "Sub", description: "no isTag" });
+    expect(result.success).toBe(false);
+  });
+
+  test("accepts isTag: true and isTag: false, rejects non-boolean isTag", () => {
+    expect(IntrinsicDefSchema.safeParse({ name: "Sub", isTag: true }).success).toBe(true);
+    expect(IntrinsicDefSchema.safeParse({ name: "Ref", isTag: false }).success).toBe(true);
+    expect(IntrinsicDefSchema.safeParse({ name: "Ref", isTag: "false" }).success).toBe(false);
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/lexicon-schema.ts

@@ -13,7 +13,9 @@ export const IntrinsicDefSchema = z.object({
   name: z.string().min(1, "intrinsic name must not be empty"),
   description: z.string().optional(),
   outputKey: z.string().optional(),
-  isTag: z.boolean().optional(),
+  // Required (chant #1067) — no silent default for whether an intrinsic
+  // folds. See IntrinsicDef.isTag in ../lexicon.ts for the history.
+  isTag: z.boolean(),
 });
 
 // ---------------------------------------------------------------------------

package/src/lexicon.ts

@@ -18,6 +18,41 @@ export type { ReferenceCatalog, IdentityRule, RefRule } from "./graph-refs";
 
 /**
  * Manifest for a packaged lexicon — metadata embedded in the tarball.
+ *
+ * chant #1067 decided each optional field below explicitly rather than
+ * leaving them all equally unchecked:
+ *
+ * - `chantVersion` — now validated for presence/shape by `chant dev
+ *   check-lexicon` (a lexicon's `dist/manifest.json` must declare one).
+ *   NOT validated for compatibility against the core version actually
+ *   running — that needs a live check at plugin-load time (a different
+ *   surface: `loadPlugin`/`loadPlugins` in `./cli/plugins.ts`), which stays
+ *   a deliberate non-goal here.
+ * - `namespace` — deliberately NOT validated for cross-lexicon uniqueness in
+ *   #1067. `chant dev check-lexicon <dir>` only ever inspects one lexicon at
+ *   a time, so it structurally can't catch a collision between two
+ *   *different* lexicons. The natural home is `checkConflicts` (./cli/
+ *   conflict-check.ts), which already detects cross-lexicon rule-id/skill/
+ *   MCP-tool/MCP-resource collisions when multiple plugins load together —
+ *   but `namespace` isn't on the runtime `LexiconPlugin` surface at all
+ *   (manifest-only, baked in at package time), so extending that check would
+ *   mean adding a new field to `LexiconPlugin` itself. Deferred rather than
+ *   done under time pressure alongside a concurrent, unrelated change to
+ *   this same interface (chant #1064).
+ * - `pseudoParameters` — deliberately NOT validated against what the
+ *   lexicon actually exports in #1067, unlike `intrinsics` (see
+ *   `IntrinsicDef.isTag` below and `./cli/commands/check-lexicon-
+ *   intrinsics.ts`). The same static-analysis approach would apply — check
+ *   each declared pseudo-parameter's short name against the real exported
+ *   namespace object's properties (`AWS.StackName`, `Azure.ResourceGroupName`,
+ *   ...) — but unlike `intrinsics()`, `pseudoParameters(): string[]` is a
+ *   flat list of dotted strings with no structural link back to a specific
+ *   export/property declaration, making the same trick more involved to
+ *   generalize correctly. Relevant to #1063 (folding cross-file references
+ *   into lexicon pseudo-parameter namespaces): once that lands, a wrong or
+ *   missing pseudo-parameter property would silently break folding exactly
+ *   the way #1039 did for intrinsics, which would be the moment this
+ *   deferral needs revisiting.
  */
 export interface LexiconManifest {
   name: string;
@@ -102,7 +137,53 @@ export interface IntrinsicDef {
   readonly name: string;
   readonly description?: string;
   readonly outputKey?: string;
-  readonly isTag?: boolean;
+  /**
+   * Whether this intrinsic is authored as a JS tagged template (`` Sub`...` ``)
+   * rather than a plain function call (`Ref(...)`). Required — chant #1067 —
+   * because an omitted value silently defaulted to "not a tag" with no
+   * signal that the registration had never been decided. That produced #1039
+   * in both directions at once: aws's `Sub` (a genuine tagged template, the
+   * most-used intrinsic in the ecosystem) shipped with no `isTag` at all and
+   * silently never folded, while gitlab's `reference()` (a plain call)
+   * shipped with `isTag: true`. Both were wrong, and both shipped, because
+   * nothing forced the declaration or checked it against how the intrinsic is
+   * actually authored. `chant dev check-lexicon` now validates every
+   * registration here against its real declaration (tagged-template
+   * signature vs plain call) and against the package's own exports — see
+   * `../cli/commands/check-lexicon-intrinsics.ts`.
+   */
+  readonly isTag: boolean;
+}
+
+/**
+ * Whether `chant build --fold` can ever fold a call to this intrinsic
+ * (chant #1062, epic #1019). Today the answer is a direct function of
+ * `isTag`: `fold()` (../fold/fold.ts) has no `CallExpression` case at all —
+ * a plain-call intrinsic (`Ref(...)`, `Concat(...)`, `reference(...)`, …) is
+ * always a run-fallback, no matter what it's named or registered as — while
+ * a *registered* tagged-template intrinsic (`Sub\`...\``) folds because
+ * `foldTaggedTemplate` recognizes its tag and recurses into the interior.
+ *
+ * This function is the single predicate both `fold()` (deciding whether a
+ * tag is registered for real) and the generated per-lexicon intrinsics page
+ * (`../codegen/docs-sections.ts`'s "Folds?" column) call — never two copies
+ * of the same `isTag === true` check that could silently drift. #1044 (per-
+ * intrinsic, per-lexicon foldability) changes this function's body to
+ * consult something more than `isTag` for a plain call that becomes
+ * foldable; every caller keeps working unchanged, and the generated matrix
+ * updates the moment a lexicon's registration says a given intrinsic now
+ * folds — no doc rewrite, no second code path to remember.
+ *
+ * Takes `{ isTag?: boolean }` rather than `Pick<IntrinsicDef, "isTag">`
+ * deliberately: `IntrinsicDef.isTag` is required for new registrations
+ * (chant #1067), but this predicate also reads `isTag` off untrusted,
+ * possibly-older parsed JSON (`ManifestJSON` in `./codegen/docs-types.ts`,
+ * on disk as a published lexicon's `dist/manifest.json`) that may predate
+ * the required field. `undefined` there means the same thing it always
+ * did — not a tag — so the check below is intentionally unchanged.
+ */
+export function intrinsicFolds(def: { isTag?: boolean }): boolean {
+  return def.isTag === true;
 }
 
 /**

package/src/lifecycle/git.test.ts

@@ -2,6 +2,7 @@ import { describe, test, expect } from "vitest";
 import { withTestDir } from "@intentius/chant-test-utils";
 import { spawnSync } from "node:child_process";
 import { writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
   writeSnapshot,
@@ -182,12 +183,16 @@ describe("lifecycle/git", () => {
    * `origin`. Returns the clone path; the caller writes snapshots there.
    */
   async function setupClonePair(): Promise<{ clonePath: string; remotePath: string; cleanup: () => Promise<void> }> {
-    const remotePath = join(import.meta.dirname ?? "/tmp", `chant-state-remote-${Date.now()}-${Math.random()}`);
-    const clonePath = join(import.meta.dirname ?? "/tmp", `chant-state-clone-${Date.now()}-${Math.random()}`);
+    // These land in the OS temp dir, never under `import.meta.dirname` — that
+    // would put live git repos inside `packages/core/src`, which other suites
+    // walk recursively while this one creates and deletes them (update.test.ts
+    // -> copyTypeFiles hit ENOENT mid-walk that way).
+    const remotePath = join(tmpdir(), `chant-state-remote-${Date.now()}-${Math.random()}`);
+    const clonePath = join(tmpdir(), `chant-state-clone-${Date.now()}-${Math.random()}`);
     const { mkdir, rm } = await import("node:fs/promises");
     await mkdir(remotePath, { recursive: true });
     git(["init", "-q", "--bare", "-b", "main"], remotePath);
-    git(["clone", "-q", remotePath, clonePath], import.meta.dirname ?? "/tmp");
+    git(["clone", "-q", remotePath, clonePath], tmpdir());
     git(["config", "user.email", "test@chant.dev"], clonePath);
     git(["config", "user.name", "Test"], clonePath);
     writeFileSync(join(clonePath, "README.md"), "fixture\n");
@@ -233,9 +238,9 @@ describe("lifecycle/git", () => {
   test("concurrent write rejected: second push throws StaleLifecycleBranchError", async () => {
     // Simulate two concurrent operators by setting up two clones of the same remote.
     const { clonePath: cloneA, remotePath, cleanup } = await setupClonePair();
-    const cloneB = join(import.meta.dirname ?? "/tmp", `chant-state-clone-b-${Date.now()}-${Math.random()}`);
+    const cloneB = join(tmpdir(), `chant-state-clone-b-${Date.now()}-${Math.random()}`);
     try {
-      git(["clone", "-q", remotePath, cloneB], import.meta.dirname ?? "/tmp");
+      git(["clone", "-q", remotePath, cloneB], tmpdir());
       git(["config", "user.email", "test@chant.dev"], cloneB);
       git(["config", "user.name", "Test"], cloneB);
 

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

@@ -129,6 +129,34 @@ describe("release-ledger", () => {
       });
     });
 
+    test("records an approver, distinct from the actor, for a gated change (#1035)", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        await appendReleaseRecord(
+          makeInput({ actor: "ci-bot", approver: "alice@corp" }),
+          { cwd: dir },
+        );
+        const { records } = await readReleaseLedger("prod", { cwd: dir });
+        expect(records).toHaveLength(1);
+        expect(records[0].actor).toBe("ci-bot");
+        expect(records[0].approver).toBe("alice@corp");
+        // Separation of duties: approver is not just an echo of actor.
+        expect(records[0].approver).not.toBe(records[0].actor);
+      });
+    });
+
+    test("approver is absent for an ungated change (#1035)", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        await appendReleaseRecord(makeInput(), { cwd: dir });
+        const { records } = await readReleaseLedger("prod", { cwd: dir });
+        expect(records).toHaveLength(1);
+        expect(records[0].approver).toBeUndefined();
+        // The optional approver never blocks a valid ungated record.
+        expect(validateReleaseRecord({ version: 1, ...makeInput() })).toEqual([]);
+      });
+    });
+
     test("release ledger and snapshot coexist on the same orphan branch without clobbering each other", async () => {
       const { writeSnapshot, readSnapshot } = await import("./git");
       await withTestDir(async (dir) => {

package/src/lifecycle/release-ledger.ts

@@ -65,6 +65,17 @@ export interface ReleaseRecord {
   timestamp: string;
   /** Who/what triggered the deploy (a username, a CI actor, a service account). */
   actor: string;
+  /**
+   * Who approved the change at its durable approval gate (#1035). Populated for
+   * a gated change — the same identity the approver supplied when they cleared
+   * the Temporal gate (`chant run signal ... --approver`, carried in the gate
+   * signal payload and thus the workflow history). Optional and omitted for an
+   * ungated change (nothing to approve), so `actor` alone answers "who made
+   * it" while `approver` answers "who approved it" only where a gate exists.
+   * Distinct from `actor`: the approver is deliberately a different person than
+   * the one who triggered the deploy (separation of duties).
+   */
+  approver?: string;
   /** Optional: the archive's own manifest digest (../components/verbs/build-archive.ts's `manifestDigest`), when the caller has it — lets a reader recover full build contents/provenance, not just the promoted image digest. */
   manifestDigest?: string;
 }

package/src/lint/component-checks.ts

@@ -93,15 +93,22 @@ export interface ComponentCheck {
  * error under the pseudo-check id "COMP000" rather than silently dropped —
  * matching how `discoverComponents`'s caller (`../components/cli-support.ts`)
  * always surfaces `result.errors` rather than ignoring them.
+ *
+ * `sandbox` (chant #1051, `chant lint --sandbox`) is threaded straight
+ * through to `discoverComponents` — `chant lint`'s own AST-only rule engine
+ * never executes project source (see this module's own doc comment), but
+ * COMP* checks exist precisely because they need the discovered `Component`
+ * graph, which does mean importing `*.component.ts` files.
  */
 export async function runComponentChecks(
   path: string,
   checks: ComponentCheck[],
   registryContext?: Pick<ComponentCheckContext, "knownKinds" | "rollbackPolicies">,
+  sandbox?: boolean,
 ): Promise<ComponentCheckDiagnostic[]> {
   if (checks.length === 0) return [];
 
-  const result = await discoverComponents(path);
+  const result = await discoverComponents(path, { sandbox });
   const diagnostics: ComponentCheckDiagnostic[] = [];
 
   for (const err of result.errors) {