@intentius/chant 0.19.1 → 0.21.0

package/src/fold/subset.ts

@@ -0,0 +1,383 @@
+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
+ * 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.
+ *   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.
+ *      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]}`;
+}
+
+/**
+ * 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,
+  intrinsics?: readonly IntrinsicDef[],
+): SubsetViolation | undefined {
+  if (ts.isPropertyAssignment(prop)) {
+    if (!isLiteralPropertyName(prop.name)) {
+      return violation(prop.name, computedPropertyNameMessage(prop.name));
+    }
+    return findSubsetViolation(prop.initializer, intrinsics);
+  }
+  if (ts.isShorthandPropertyAssignment(prop)) {
+    return undefined;
+  }
+  if (ts.isSpreadAssignment(prop)) {
+    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,
+  intrinsics?: readonly IntrinsicDef[],
+): SubsetViolation | undefined {
+  if (ts.isSpreadElement(el)) return findSubsetViolation(el.expression, intrinsics);
+  return findSubsetViolation(el, intrinsics);
+}
+
+/**
+ * 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,
+  intrinsics?: readonly IntrinsicDef[],
+): SubsetViolation | undefined {
+  if (
+    ts.isParenthesizedExpression(node) ||
+    ts.isAsExpression(node) ||
+    ts.isSatisfiesExpression(node) ||
+    ts.isNonNullExpression(node)
+  ) {
+    return findSubsetViolation(node.expression, intrinsics);
+  }
+
+  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, intrinsics);
+      if (v) return v;
+    }
+    return undefined;
+  }
+
+  if (ts.isObjectLiteralExpression(node)) {
+    for (const prop of node.properties) {
+      const v = checkObjectMember(prop, intrinsics);
+      if (v) return v;
+    }
+    return undefined;
+  }
+
+  if (ts.isArrayLiteralExpression(node)) {
+    for (const el of node.elements) {
+      const v = checkArrayElement(el, intrinsics);
+      if (v) return v;
+    }
+    return undefined;
+  }
+
+  if (ts.isPropertyAccessExpression(node)) {
+    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, intrinsics);
+  }
+
+  if (ts.isPrefixUnaryExpression(node)) {
+    if (!SUPPORTED_UNARY_OPERATORS.has(node.operator)) {
+      return violation(node, UNSUPPORTED_UNARY_MESSAGE);
+    }
+    return findSubsetViolation(node.operand, intrinsics);
+  }
+
+  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, intrinsics) ?? findSubsetViolation(node.right, intrinsics);
+  }
+
+  if (ts.isConditionalExpression(node)) {
+    // Flow-insensitive — see module doc: fold() only folds the taken branch.
+    return (
+      findSubsetViolation(node.condition, intrinsics) ??
+      findSubsetViolation(node.whenTrue, intrinsics) ??
+      findSubsetViolation(node.whenFalse, intrinsics)
+    );
+  }
+
+  if (ts.isNewExpression(node)) {
+    // 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 undefined;
+  }
+
+  if (ts.isSpreadElement(node)) {
+    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));
+  }
+
+  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

@@ -6,6 +6,7 @@ import {
   IntrinsicDefSchema,
   LexiconEntrySchema,
 } from "./lexicon-schema";
+import { intrinsicFolds, intrinsicTagFolds, intrinsicCallFolds } from "./lexicon";
 
 // ---------------------------------------------------------------------------
 // validateManifest
@@ -131,6 +132,62 @@ 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);
+  });
+
+  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

@@ -13,7 +13,14 @@ 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(),
+  // 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(),
 });
 
 // ---------------------------------------------------------------------------

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,103 @@ 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;
+  /**
+   * chant #1044 — opt this intrinsic's PLAIN-CALL form into folding
+   * (`Ref(bucket)`, `Concat(a, b)` reduce to their intrinsic node instead of
+   * falling the whole file back to the run path).
+   *
+   * Optional, and OFF unless a lexicon writes `true`. That default is the
+   * point: `fold()` has no general `CallExpression` case by construction
+   * (epic #1019), and this field is the only thing that admits one. It is a
+   * closed, lexicon-declared allowlist, decided one intrinsic at a time —
+   * never inferred from `isTag`, from the name, or from the call's shape. An
+   * intrinsic with no `foldsAsCall` behaves exactly as it did before #1044.
+   *
+   * Only set it when calling the intrinsic is a pure function of its
+   * arguments that builds a deterministic data envelope — the whole
+   * correctness argument is that invoking it while folding is
+   * indistinguishable from invoking it during a real run of the file. An
+   * intrinsic that reads the environment, mutates state, or depends on
+   * anything but its arguments does not qualify, and neither does a tagged
+   * template (see {@link isTag}: the two forms are mutually exclusive, and
+   * `chant dev check-lexicon` rejects `isTag: true` + `foldsAsCall: true`).
+   *
+   * Registration is by name. It is not permission to invoke whatever that
+   * name happens to be bound to: `fold()` reduces the call to a symbolic
+   * envelope executing nothing, and `../discovery/fold-import.ts` resolves
+   * the name through the folding FILE'S OWN imports before invoking the real
+   * function — so the function that runs while folding is the same one the
+   * run path would have called, from the module the source itself named.
+   */
+  readonly foldsAsCall?: boolean;
+}
+
+/**
+ * Whether `chant build --fold` can ever fold a use of this intrinsic
+ * (chant #1062, epic #1019) — in EITHER authored form.
+ *
+ * Two disjoint ways to qualify, one per form:
+ *
+ *   - a registered tagged-template intrinsic (`Sub\`...\``) folds because
+ *     `foldTaggedTemplate` recognizes its tag and recurses into the interior
+ *     ({@link intrinsicTagFolds});
+ *   - a registered plain-call intrinsic (`Ref(...)`, `Concat(...)`) folds
+ *     only when its lexicon opted it in with `foldsAsCall`
+ *     ({@link intrinsicCallFolds}, chant #1044). Before #1044 no plain call
+ *     folded at all, whatever it was named or registered as.
+ *
+ * This function is the single predicate the generated per-lexicon intrinsics
+ * page (`../codegen/docs-sections.ts`'s "Folds?" column) calls — never a
+ * restated copy that could silently drift from the code. `fold()` itself
+ * calls the two form-specific predicates below rather than this one, because
+ * it always knows which form it is looking at, and a tag must not fold as a
+ * call (or vice versa) merely because the other form was opted in.
+ *
+ * Takes a structural `{ isTag?, foldsAsCall? }` rather than
+ * `Pick<IntrinsicDef, ...>` deliberately: `IntrinsicDef.isTag` is required
+ * for new registrations (chant #1067), but these predicates also read 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 either field. `undefined` there
+ * means what it always did — not a tag, not opted in.
+ */
+export function intrinsicFolds(def: { isTag?: boolean; foldsAsCall?: boolean }): boolean {
+  return intrinsicTagFolds(def) || intrinsicCallFolds(def);
+}
+
+/** True when this intrinsic's TAGGED-TEMPLATE form folds (`Sub\`...\``) — see {@link intrinsicFolds}. */
+export function intrinsicTagFolds(def: { isTag?: boolean }): boolean {
+  return def.isTag === true;
+}
+
+/**
+ * True when this intrinsic's PLAIN-CALL form folds (`Ref(...)`) — i.e. the
+ * lexicon opted it in via {@link IntrinsicDef.foldsAsCall} (chant #1044).
+ *
+ * `isTag: true` disqualifies regardless: a tagged template is invoked as
+ * `` Name`...` ``, so a call to it isn't the registered authoring form at
+ * all. Keeping that here rather than trusting registrations means a lexicon
+ * that declares both flags cannot quietly widen `fold()`'s call case — and
+ * `chant dev check-lexicon` fails the registration outright.
+ */
+export function intrinsicCallFolds(def: { isTag?: boolean; foldsAsCall?: boolean }): boolean {
+  return def.isTag !== true && def.foldsAsCall === true;
 }
 
 /**