@intentius/chant 0.20.0 → 0.21.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 { 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,77 @@ 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);
+  });
+});

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.
@@ -137,10 +171,6 @@ 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 +178,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 +216,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 +261,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 +269,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 +277,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 +308,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(),
 });
 
 // ---------------------------------------------------------------------------

package/src/lexicon.ts

@@ -153,39 +153,89 @@ export interface IntrinsicDef {
    * `../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 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.
+ * 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 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.
+ * 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 `{ 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.
+ * 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 }): boolean {
+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;
+}
+
 /**
  * Options passed to a MigrationSource by `chant migrate`.
  */

package/src/runtime.ts

@@ -54,18 +54,27 @@ export function createResource(
 
 /**
  * Create a property-kind class for a given property type.
+ *
+ * Instances carry DECLARABLE_MARKER/lexicon/entityType/kind at runtime (set
+ * via defineProperty below), so they already satisfy `Declarable` — the
+ * return type just needs to say so. Before this, the signature was
+ * `Record<string, unknown>` with no `Declarable`, so any composite that
+ * returned a property-kind instance as a top-level member only type-checked
+ * by accident: either the caller went through an untyped `require()` (losing
+ * the type entirely) or never assigned the instance where its `Declarable`-ness
+ * was checked statically. See chant #1068.
  */
 export function createProperty(
   type: string,
   lexicon: string,
-): new (props: Record<string, unknown>) => Record<string, unknown> {
+): new (props: Record<string, unknown>) => Declarable & Record<string, unknown> {
   const PropertyClass = function (this: Record<string, unknown>, props: Record<string, unknown>) {
     Object.defineProperty(this, DECLARABLE_MARKER, { value: true, enumerable: false });
     Object.defineProperty(this, "lexicon", { value: lexicon, enumerable: false });
     Object.defineProperty(this, "entityType", { value: type, enumerable: false });
     Object.defineProperty(this, "kind", { value: "property", enumerable: false });
     Object.defineProperty(this, "props", { value: props ?? {}, enumerable: false, configurable: true });
-  } as unknown as new (props: Record<string, unknown>) => Record<string, unknown>;
+  } as unknown as new (props: Record<string, unknown>) => Declarable & Record<string, unknown>;
 
   Object.defineProperty(PropertyClass, "name", { value: type.split(".").pop() ?? type });