@intentius/chant 0.20.0 → 0.22.0

package/src/fold/subset.test.ts

@@ -1,6 +1,7 @@
 import { describe, test, expect } from "vitest";
 import * as ts from "typescript";
 import { fold, foldResource, collectConsts, FoldError } from "./fold";
+import { briefNodeText, callExpressionMessage, findSubsetViolation } from "./subset";
 import { evl001NonLiteralExpressionRule } from "../lint/rules/evl001-non-literal-expression";
 import { evl003DynamicPropertyAccessRule } from "../lint/rules/evl003-dynamic-property-access";
 import { evl004SpreadNonConstRule } from "../lint/rules/evl004-spread-non-const";
@@ -58,11 +59,28 @@ const SUPPORTED_CASES: SubsetCase[] = [
     expr: "Sub`${name}-data`",
     intrinsics: [{ name: "Sub", isTag: true }],
   },
+  {
+    // chant #1082 — a registered chant authoring helper is the one call shape
+    // that folds, so EVL001 must not flag it either.
+    name: "registered authoring helper call with foldable arguments",
+    preamble: `const stack = "web";`,
+    expr: `phase("Apply", [{ kind: "cfn-deploy", stack }])`,
+  },
+  {
+    name: "registered authoring helper nested inside another",
+    expr: `phase("Outer", [phase("Inner", []), gate("approve")])`,
+  },
 ];
 
 const UNSUPPORTED_CASES: SubsetCase[] = [
   { name: "function call as a value", expr: `getName()` },
   { name: "method call as a value", expr: `config.getName()` },
+  // chant #1082 — a registered helper NAME reached through a namespace is
+  // still a method call, and still rejected by both sides.
+  { name: "registered helper name reached as a method", expr: `helpers.phase("Apply", [])` },
+  // ...and a registered helper with an unfoldable argument is rejected on the
+  // argument, by both sides, at the argument's own position.
+  { name: "registered helper with an unfoldable argument", expr: `phase("Apply", [getName()])` },
   { name: "computed/dynamic object-literal key", expr: `{ [dynKey]: 1 }` },
   { name: "dynamic element-access key", expr: `config[dynKey]` },
   { name: "non-whitelisted binary operator (%)", expr: `n % 2` },
@@ -221,6 +239,25 @@ describe("documented divergences — NOT unified by design (see subset.ts module
     expect(evl001NonLiteralExpressionRule.check(context)).toHaveLength(0);
   });
 
+  test("authoring-helper shadowing: fold rejects a registered name bound to a local const; EVL001 does not (shape-only, no binding resolution)", () => {
+    // chant #1082 — `phase` is registered, but here it's the file's own local
+    // arrow function, so the local binding wins and fold() rejects. EVL has no
+    // binding resolver (subset.ts module doc, point 1) and stays permissive —
+    // the same direction as every other divergence here.
+    const source = `
+      const phase = (n) => ({ phase: n });
+      const bad = new Thing({ x: phase("Apply") });
+    `;
+    const sourceFile = ts.createSourceFile("t.ts", source, ts.ScriptTarget.Latest, true);
+    const consts = collectConsts(sourceFile);
+    const badInit = consts.get("bad") as ts.NewExpression;
+
+    expect(() => foldResource(badInit, consts, [])).toThrow(FoldError);
+
+    const context: LintContext = { sourceFile, entities: [], filePath: "t.ts", lexicon: undefined };
+    expect(evl001NonLiteralExpressionRule.check(context)).toHaveLength(0);
+  });
+
   test("nested resource construction: fold rejects a nested `new Type()` used as a value (falls back to run); EVL001 allows it statically", () => {
     // A top-level `new Type()` folds (fold-import constructs a real Declarable),
     // but a NESTED one as a property value can only fold to a {__resource,props}
@@ -239,3 +276,143 @@ describe("documented divergences — NOT unified by design (see subset.ts module
     expect(evl001NonLiteralExpressionRule.check(context)).toHaveLength(0);
   });
 });
+
+/**
+ * chant #1044 — the shared predicate's optional intrinsic registry.
+ *
+ * `findSubsetViolation` answers "is this shape foldable?" for two kinds of
+ * caller: `fold()`'s own EVL twin, which has no registry, and a tool that
+ * does (a control plane deciding whether a repository needs a sandboxed
+ * child process). The parameter is what lets the second kind get fold()'s
+ * real answer without running fold, while the first keeps the answer it
+ * always had.
+ */
+describe("findSubsetViolation — optional intrinsic registry (#1044)", () => {
+  const REF: IntrinsicDef[] = [{ name: "Ref", isTag: false, foldsAsCall: true }];
+
+  /** The `x` initializer of `const bad = new Thing({ x: <expr> });`. */
+  function propValue(expr: string, preamble = ""): ts.Expression {
+    const sourceFile = ts.createSourceFile(
+      "t.ts",
+      `${preamble}\nconst bad = new Thing({ x: ${expr} });`,
+      ts.ScriptTarget.Latest,
+      true,
+    );
+    const consts = collectConsts(sourceFile);
+    const init = consts.get("bad") as ts.NewExpression;
+    const props = init.arguments![0] as ts.ObjectLiteralExpression;
+    return (props.properties[0] as ts.PropertyAssignment).initializer;
+  }
+
+  test("with the registry supplied, an opted-in intrinsic call is not a violation — the same answer fold() gives", () => {
+    expect(findSubsetViolation(propValue(`Ref(env)`), REF)).toBeUndefined();
+    const consts = collectConsts(
+      ts.createSourceFile("t.ts", `const env = "p"; const x = Ref(env);`, ts.ScriptTarget.Latest, true),
+    );
+    expect(fold(consts.get("x") as ts.Expression, consts, REF)).toEqual({ __intrinsic: "Ref", args: ["p"] });
+  });
+
+  test("with NO registry, every call stays a violation — the pre-#1044 answer, and the safe one", () => {
+    const v = findSubsetViolation(propValue(`Ref(env)`));
+    expect(v?.ruleId).toBe("EVL001");
+    expect(v?.message).toContain("function call as a value is not foldable: Ref(...)");
+  });
+
+  test("the registry doesn't widen anything else: a name in it without the opt-in, a method call, and .map all stay violations", () => {
+    const notOptedIn: IntrinsicDef[] = [{ name: "Reference", isTag: false }];
+    expect(findSubsetViolation(propValue(`Reference("db")`), notOptedIn)).toBeDefined();
+    expect(findSubsetViolation(propValue(`aws.Ref("db")`), REF)).toBeDefined();
+    expect(findSubsetViolation(propValue(`cidrs.map((c) => c)`, `const cidrs = [];`), REF)).toBeDefined();
+    expect(findSubsetViolation(propValue(`makeName("a")`), REF)).toBeDefined();
+  });
+
+  test("arguments are still classified on their own terms, at their own position", () => {
+    const v = findSubsetViolation(propValue(`Ref(getName())`), REF);
+    expect(v?.message).toContain("getName(...)");
+  });
+
+  test("registry-less EVL is now STRICTER than fold on an opted-in call — a known divergence, not a hole", () => {
+    // chant #1044 — EVL001 has no registry (see subset.ts module doc, point
+    // 2c), so it still flags `Ref(...)` in a resource's props exactly as it
+    // did before this change, while fold() — which is always given one —
+    // folds it. Recorded here so the divergence is a tracked property with a
+    // test rather than a surprise; closing it means handing the lint engine
+    // the active lexicons' intrinsics, which is a change to lint's own
+    // surface and deliberately not part of #1044.
+    const source = `const bad = new Thing({ x: Ref(env) });`;
+    const sourceFile = ts.createSourceFile("t.ts", source, ts.ScriptTarget.Latest, true);
+    const consts = collectConsts(sourceFile);
+    const badInit = consts.get("bad") as ts.NewExpression;
+
+    expect(() => foldResource(badInit, consts, REF)).not.toThrow();
+
+    const context: LintContext = { sourceFile, entities: [], filePath: "t.ts", lexicon: undefined };
+    expect(evl001NonLiteralExpressionRule.check(context).length).toBeGreaterThan(0);
+  });
+});
+
+/**
+ * chant #1054 — `briefNodeText` is what keeps every fold fallback reason
+ * that used to embed a node's raw `getText()` down to one bounded line. A
+ * real composite call's source is many lines; a fold reason that reproduces
+ * it verbatim buries the actual error after all of it (the bug this issue
+ * reports) and breaks any line-oriented consumer of `[fold:run]` output.
+ */
+describe("briefNodeText — single-line, bounded diagnostic text (chant #1054)", () => {
+  function initializerOf(source: string): ts.Expression {
+    const sourceFile = ts.createSourceFile("t.ts", source, ts.ScriptTarget.Latest, true);
+    const consts = collectConsts(sourceFile);
+    const init = consts.get("x");
+    if (!init) throw new Error(`fixture error: "x" did not parse in ${JSON.stringify(source)}`);
+    return init;
+  }
+
+  test("a short, single-line node passes through unchanged", () => {
+    expect(briefNodeText(initializerOf(`const x = GkeCluster;`))).toBe("GkeCluster");
+  });
+
+  test("a multi-line node's newlines collapse to spaces — the result is always one line", () => {
+    const text = briefNodeText(
+      initializerOf(`
+        const x = GkeCluster({
+          name: config.clusterName,
+          location: config.region,
+        });
+      `),
+    );
+    expect(text).not.toContain("\n");
+    expect(text.split("\n")).toHaveLength(1);
+  });
+
+  test("text over the length cap is truncated with a trailing marker rather than left unbounded", () => {
+    const text = briefNodeText(
+      initializerOf(`const x = { aVeryLongPropertyNameNumberOne: 1, aVeryLongPropertyNameNumberTwo: 2 };`),
+      20,
+    );
+    expect(text.length).toBe(20);
+    expect(text.endsWith("...")).toBe(true);
+  });
+});
+
+describe("callExpressionMessage — one line regardless of the call's own argument list (chant #1054)", () => {
+  test("only the callee is embedded — a multi-line argument list never leaks into the message", () => {
+    const sourceFile = ts.createSourceFile(
+      "t.ts",
+      `
+        const x = GkeCluster({
+          name: config.clusterName,
+          location: config.region,
+          machineType: "n2-standard-2",
+        });
+      `,
+      ts.ScriptTarget.Latest,
+      true,
+    );
+    const consts = collectConsts(sourceFile);
+    const call = consts.get("x") as ts.CallExpression;
+
+    const message = callExpressionMessage(call);
+
+    expect(message).toBe("function call as a value is not foldable: GkeCluster(...)");
+  });
+});

package/src/fold/subset.ts

@@ -1,4 +1,6 @@
 import * as ts from "typescript";
+import { isFoldableHelperName } from "./foldable-helpers";
+import { intrinsicCallFolds, type IntrinsicDef } from "../lexicon";
 
 /**
  * subset — the single canonical definition of chant's statically-foldable
@@ -37,6 +39,38 @@ import * as ts from "typescript";
  *      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.
+ *   2b. Authoring-helper *provenance* (chant #1082) — a call to a registered
+ *      chant helper (`phase(...)`, `output(...)`; ./foldable-helpers.ts)
+ *      folds, but only when the name is genuinely bound to an import of
+ *      chant's own. That needs the module graph, which a syntax-only lint
+ *      rule doesn't have. This module checks the NAME only and stays
+ *      permissive; `fold()`'s bridge does the provenance check and falls the
+ *      file back to run when it fails. Same direction as every other item
+ *      here — a false negative for EVL, never a false positive.
+ *   2c. Intrinsic *call-form* registration (chant #1044) — a plain call to a
+ *      lexicon intrinsic the lexicon opted in (`Ref(bucket)`,
+ *      `Concat(a, b)`; `IntrinsicDef.foldsAsCall`, ../lexicon.ts) folds.
+ *      Whether a given name is such an intrinsic is not knowable from shape,
+ *      so {@link findSubsetViolation} takes the registry as an OPTIONAL
+ *      parameter instead of guessing: supply it and the answer for a call is
+ *      exact (fold()'s own), omit it and every call is a violation, the
+ *      pre-#1044 answer.
+ *
+ *      That parameter is the whole reason the call case lives here rather
+ *      than only in `fold()`. This module is a shared predicate, and the
+ *      point of a shared predicate is that a consumer can ask "will this
+ *      fold?" without running fold — a control plane deciding whether a
+ *      repository needs a sandboxed child process at all, for instance.
+ *      Keeping the case out of here would make the predicate answer "no" for
+ *      idiomatic `Ref(...)` source that `fold()` reduces cleanly: not a
+ *      permissive gap but a systematically WRONG answer in the expensive
+ *      direction, and the one direction this module is not allowed to be
+ *      wrong in (see the false-negative/false-positive rule in point 1, and
+ *      the flow-sensitivity note below — the single divergence in the other
+ *      direction, and the one this module treats as a wart). A caller with
+ *      no registry degrades to "assume it runs", which is safe and cheap to
+ *      reason about; EVL is exactly such a caller and its behavior on calls
+ *      is unchanged by #1044.
  *   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.
@@ -107,6 +141,22 @@ export function isLiteralElementKey(node: ts.Expression): node is ts.StringLiter
   return ts.isStringLiteral(node) || ts.isNumericLiteral(node);
 }
 
+/**
+ * A short, single-line rendering of `node`'s source text for embedding in a
+ * diagnostic message — never the raw `getText()`, which reproduces the
+ * node's ENTIRE source verbatim and can span dozens of lines for a real
+ * composite call or object literal (chant #1054: a fold fallback reason that
+ * embeds one of these buries the actual error after it, and breaks any
+ * line-oriented consumer of `[fold:run]` output). Internal whitespace
+ * (including newlines) collapses to a single space, and the result is capped
+ * to a bounded length so one pathological node can't blow out an otherwise
+ * one-line reason either.
+ */
+export function briefNodeText(node: ts.Node, maxLength = 60): string {
+  const collapsed = node.getText().replace(/\s+/g, " ").trim();
+  return collapsed.length > maxLength ? `${collapsed.slice(0, maxLength - 3)}...` : collapsed;
+}
+
 // ---------------------------------------------------------------------------
 // Shared message builders — `fold()` and `findSubsetViolation` both call
 // these so the diagnostic text for the same violation kind is the same
@@ -114,11 +164,11 @@ export function isLiteralElementKey(node: ts.Expression): node is ts.StringLiter
 // ---------------------------------------------------------------------------
 
 export function computedPropertyNameMessage(node: ts.PropertyName): string {
-  return `computed/dynamic property name not foldable: ${node.getText()}`;
+  return `computed/dynamic property name not foldable: ${briefNodeText(node)}`;
 }
 
 export function dynamicElementAccessMessage(keyNode: ts.Expression): string {
-  return `dynamic property access — computed key must be a string or numeric literal: ${keyNode.getText()}`;
+  return `dynamic property access — computed key must be a string or numeric literal: ${briefNodeText(keyNode)}`;
 }
 
 export const UNSUPPORTED_OBJECT_MEMBER_MESSAGE = "unsupported object member";
@@ -129,18 +179,25 @@ export function unsupportedBinaryMessage(opKind: ts.SyntaxKind): string {
   return `unsupported binary operator: ${ts.SyntaxKind[opKind]}`;
 }
 
+/**
+ * chant #1054 — the ONE wording for "a bare function/method call used where
+ * chant needs a value it can fold." Before this, `fold()` (this message) and
+ * `../discovery/fold-import.ts`'s `resolveCallExpression` (a top-level
+ * export's own call-as-a-value check) had each grown their own hand-written
+ * copy — "function call as a value" here, "call expression as a value"
+ * there — for the identical rejection, which meant a tool grouping fallback
+ * reasons by text had to match both to avoid silently under-counting one of
+ * them. `resolveCallExpression` now calls this function directly instead of
+ * building its own string.
+ */
 export function callExpressionMessage(node: ts.CallExpression): string {
-  return `function call as a value is not foldable: ${node.expression.getText()}(...)`;
+  return `function call as a value is not foldable: ${briefNodeText(node.expression)}(...)`;
 }
 
 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
@@ -148,26 +205,32 @@ export function resourceCtorArgMessage(typeName: string): string {
  * 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 {
+export function checkObjectMember(
+  prop: ts.ObjectLiteralElementLike,
+  intrinsics?: readonly IntrinsicDef[],
+): SubsetViolation | undefined {
   if (ts.isPropertyAssignment(prop)) {
     if (!isLiteralPropertyName(prop.name)) {
       return violation(prop.name, computedPropertyNameMessage(prop.name));
     }
-    return findSubsetViolation(prop.initializer);
+    return findSubsetViolation(prop.initializer, intrinsics);
   }
   if (ts.isShorthandPropertyAssignment(prop)) {
     return undefined;
   }
   if (ts.isSpreadAssignment(prop)) {
-    return findSubsetViolation(prop.expression);
+    return findSubsetViolation(prop.expression, intrinsics);
   }
   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);
+function checkArrayElement(
+  el: ts.Expression,
+  intrinsics?: readonly IntrinsicDef[],
+): SubsetViolation | undefined {
+  if (ts.isSpreadElement(el)) return findSubsetViolation(el.expression, intrinsics);
+  return findSubsetViolation(el, intrinsics);
 }
 
 /**
@@ -180,14 +243,17 @@ function checkArrayElement(el: ts.Expression): SubsetViolation | undefined {
  * `fold()`-evaluation-order) unsupported node, or `undefined` when `node`'s
  * whole shape is foldable.
  */
-export function findSubsetViolation(node: ts.Node): SubsetViolation | undefined {
+export function findSubsetViolation(
+  node: ts.Node,
+  intrinsics?: readonly IntrinsicDef[],
+): SubsetViolation | undefined {
   if (
     ts.isParenthesizedExpression(node) ||
     ts.isAsExpression(node) ||
     ts.isSatisfiesExpression(node) ||
     ts.isNonNullExpression(node)
   ) {
-    return findSubsetViolation(node.expression);
+    return findSubsetViolation(node.expression, intrinsics);
   }
 
   if (
@@ -222,7 +288,7 @@ export function findSubsetViolation(node: ts.Node): SubsetViolation | undefined
 
   if (ts.isTemplateExpression(node)) {
     for (const span of node.templateSpans) {
-      const v = findSubsetViolation(span.expression);
+      const v = findSubsetViolation(span.expression, intrinsics);
       if (v) return v;
     }
     return undefined;
@@ -230,7 +296,7 @@ export function findSubsetViolation(node: ts.Node): SubsetViolation | undefined
 
   if (ts.isObjectLiteralExpression(node)) {
     for (const prop of node.properties) {
-      const v = checkObjectMember(prop);
+      const v = checkObjectMember(prop, intrinsics);
       if (v) return v;
     }
     return undefined;
@@ -238,28 +304,28 @@ export function findSubsetViolation(node: ts.Node): SubsetViolation | undefined
 
   if (ts.isArrayLiteralExpression(node)) {
     for (const el of node.elements) {
-      const v = checkArrayElement(el);
+      const v = checkArrayElement(el, intrinsics);
       if (v) return v;
     }
     return undefined;
   }
 
   if (ts.isPropertyAccessExpression(node)) {
-    return findSubsetViolation(node.expression);
+    return findSubsetViolation(node.expression, intrinsics);
   }
 
   if (ts.isElementAccessExpression(node)) {
     if (!isLiteralElementKey(node.argumentExpression)) {
       return violation(node.argumentExpression, dynamicElementAccessMessage(node.argumentExpression), "EVL003");
     }
-    return findSubsetViolation(node.expression);
+    return findSubsetViolation(node.expression, intrinsics);
   }
 
   if (ts.isPrefixUnaryExpression(node)) {
     if (!SUPPORTED_UNARY_OPERATORS.has(node.operator)) {
       return violation(node, UNSUPPORTED_UNARY_MESSAGE);
     }
-    return findSubsetViolation(node.operand);
+    return findSubsetViolation(node.operand, intrinsics);
   }
 
   if (ts.isBinaryExpression(node)) {
@@ -269,32 +335,74 @@ export function findSubsetViolation(node: ts.Node): SubsetViolation | undefined
     }
     // 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);
+    return findSubsetViolation(node.left, intrinsics) ?? findSubsetViolation(node.right, intrinsics);
   }
 
   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)
+      findSubsetViolation(node.condition, intrinsics) ??
+      findSubsetViolation(node.whenTrue, intrinsics) ??
+      findSubsetViolation(node.whenFalse, intrinsics)
     );
   }
 
   if (ts.isNewExpression(node)) {
-    const [firstArg] = node.arguments ?? [];
-    if (!firstArg) return undefined;
-    if (!ts.isObjectLiteralExpression(firstArg)) {
-      return violation(firstArg, resourceCtorArgMessage(node.expression.getText()));
+    // chant #1082 — no positional assumption about which argument is the
+    // props object. `foldResource` folds every argument in source order (the
+    // props object is second in `new Parameter("String", {...})`), so every
+    // argument is classified on its own terms and nothing is rejected merely
+    // for being in the "wrong" position.
+    for (const arg of node.arguments ?? []) {
+      const v = findSubsetViolation(arg, intrinsics);
+      if (v) return v;
     }
-    return findSubsetViolation(firstArg);
+    return undefined;
   }
 
   if (ts.isSpreadElement(node)) {
-    return findSubsetViolation(node.expression);
+    return findSubsetViolation(node.expression, intrinsics);
   }
 
   if (ts.isCallExpression(node)) {
+    // chant #1082 — a call to a REGISTERED chant authoring helper folds
+    // (`phase(...)`, `output(...)`, …; see ./foldable-helpers.ts), so this
+    // classifier must accept it too or EVL001 would flag source `fold()`
+    // reduces cleanly. Name-only here, deliberately: this module classifies
+    // shape and never resolves bindings (module doc, point 1), and the
+    // provenance half of the check — is this name actually bound to an import
+    // of chant's own? — needs the module graph, which only
+    // ../discovery/fold-import.ts has. Same asymmetry as intrinsic tag
+    // registration (point 2) and in the same direction: this module can only
+    // ever be MORE permissive than `fold()`, never stricter.
+    if (ts.isIdentifier(node.expression) && isFoldableHelperName(node.expression.text)) {
+      for (const arg of node.arguments) {
+        const v = findSubsetViolation(arg, intrinsics);
+        if (v) return v;
+      }
+      return undefined;
+    }
+
+    // chant #1044 — a plain call to a lexicon intrinsic whose lexicon opted
+    // its call form in folds too (`Ref(bucket)`, `Concat("a", b)`). Unlike
+    // the helper case above, this one is only answerable with the registry
+    // in hand, which is exactly why it is a parameter: a caller that passes
+    // `intrinsics` gets fold()'s own answer, and a caller that can't supply
+    // one (EVL, any syntax-only tool) keeps the pre-#1044 answer — every
+    // call is a violation. See the module doc, point 2c, for why the
+    // registry-less answer is the safe one to leave in place.
+    if (
+      intrinsics &&
+      ts.isIdentifier(node.expression) &&
+      intrinsics.some((i) => i.name === (node.expression as ts.Identifier).text && intrinsicCallFolds(i))
+    ) {
+      for (const arg of node.arguments) {
+        const v = findSubsetViolation(arg, intrinsics);
+        if (v) return v;
+      }
+      return undefined;
+    }
+
     return violation(node, callExpressionMessage(node));
   }
 

package/src/lexicon-schema.test.ts

@@ -6,6 +6,7 @@ import {
   IntrinsicDefSchema,
   LexiconEntrySchema,
 } from "./lexicon-schema";
+import { intrinsicFolds, intrinsicTagFolds, intrinsicCallFolds } from "./lexicon";
 
 // ---------------------------------------------------------------------------
 // validateManifest
@@ -145,6 +146,48 @@ describe("IntrinsicDefSchema", () => {
     expect(IntrinsicDefSchema.safeParse({ name: "Ref", isTag: false }).success).toBe(true);
     expect(IntrinsicDefSchema.safeParse({ name: "Ref", isTag: "false" }).success).toBe(false);
   });
+
+  test("foldsAsCall is optional and boolean — omitted means not opted in (chant #1044)", () => {
+    const omitted = IntrinsicDefSchema.safeParse({ name: "Ref", isTag: false });
+    expect(omitted.success).toBe(true);
+    if (omitted.success) expect(omitted.data.foldsAsCall).toBeUndefined();
+    expect(IntrinsicDefSchema.safeParse({ name: "Ref", isTag: false, foldsAsCall: true }).success).toBe(true);
+    expect(IntrinsicDefSchema.safeParse({ name: "Ref", isTag: false, foldsAsCall: "yes" }).success).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Foldability predicates (chant #1044)
+// ---------------------------------------------------------------------------
+
+describe("intrinsic foldability predicates", () => {
+  test("a tagged template folds as a tag, never as a call", () => {
+    const sub = { isTag: true };
+    expect(intrinsicTagFolds(sub)).toBe(true);
+    expect(intrinsicCallFolds(sub)).toBe(false);
+    expect(intrinsicFolds(sub)).toBe(true);
+  });
+
+  test("a plain call folds only once its lexicon opts it in — never by inference", () => {
+    const optedIn = { isTag: false, foldsAsCall: true };
+    expect(intrinsicCallFolds({ isTag: false })).toBe(false);
+    expect(intrinsicFolds({ isTag: false })).toBe(false);
+    expect(intrinsicCallFolds(optedIn)).toBe(true);
+    expect(intrinsicFolds(optedIn)).toBe(true);
+    expect(intrinsicTagFolds(optedIn)).toBe(false);
+  });
+
+  test("a registration claiming BOTH forms does not fold as a call — isTag wins, and check-lexicon fails it", () => {
+    const both = { isTag: true, foldsAsCall: true };
+    expect(intrinsicCallFolds(both)).toBe(false);
+    expect(intrinsicTagFolds(both)).toBe(true);
+  });
+
+  test("an older manifest with neither field folds in neither form", () => {
+    expect(intrinsicFolds({})).toBe(false);
+    expect(intrinsicTagFolds({})).toBe(false);
+    expect(intrinsicCallFolds({})).toBe(false);
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/lexicon-schema.ts

@@ -16,6 +16,11 @@ export const IntrinsicDefSchema = z.object({
   // Required (chant #1067) — no silent default for whether an intrinsic
   // folds. See IntrinsicDef.isTag in ../lexicon.ts for the history.
   isTag: z.boolean(),
+  // chant #1044 — optional and default-off on purpose: absent means "this
+  // intrinsic's plain-call form does not fold", which is what every
+  // registration written before #1044 means. Only an explicit `true` opts a
+  // call into folding. See IntrinsicDef.foldsAsCall in ../lexicon.ts.
+  foldsAsCall: z.boolean().optional(),
 });
 
 // ---------------------------------------------------------------------------