@intentius/chant 0.20.0 → 0.21.0

package/src/fold/fold.ts

@@ -1,5 +1,5 @@
 import * as ts from "typescript";
-import { intrinsicFolds, type IntrinsicDef } from "../lexicon";
+import { intrinsicCallFolds, intrinsicTagFolds, type IntrinsicDef } from "../lexicon";
 import {
   SUPPORTED_BINARY_OPERATORS,
   SUPPORTED_UNARY_OPERATORS,
@@ -10,11 +10,11 @@ import {
   dynamicElementAccessMessage,
   isLiteralElementKey,
   isLiteralPropertyName,
-  resourceCtorArgMessage,
   unsupportedBinaryMessage,
   unsupportedExpressionMessage,
   type SubsetRuleId,
 } from "./subset";
+import { isFoldableHelperName } from "./foldable-helpers";
 
 /**
  * fold — static AST value reducer (chant #1026/#1021/#1024, part of epic #1019)
@@ -32,9 +32,22 @@ import {
  * ({@link "../lint/rules/evl001-non-literal-expression"}), so the linted
  * subset and the folded subset can never drift apart (#1024).
  *
- * A `CallExpression` has no case — a function call as a value is
+ * A `CallExpression` has almost no case — a function call as a value is
  * structurally unrepresentable, not merely linted against. Composite
- * factory calls are out of scope here (epic Phase 5, #1023).
+ * factory calls are out of scope here (epic Phase 5, #1023). There are
+ * exactly two exceptions, both closed allowlists of names declared
+ * somewhere a human had to write them down, and both reducing to a symbolic
+ * envelope that executes nothing here:
+ *
+ *   - a call to a REGISTERED chant authoring helper
+ *     ({@link "./foldable-helpers"}, chant #1082) → {@link FoldedHelperCall};
+ *   - a call to a lexicon intrinsic whose lexicon registered it AND opted
+ *     its call form in ({@link intrinsicCallFolds}, ../lexicon.ts, chant
+ *     #1044) → {@link FoldedIntrinsicCall}, the same `{__intrinsic}` family
+ *     the tagged-template form already reduces to.
+ *
+ * Everything else — a user's function, a method call, an array `.map`, a
+ * registered name shadowed by a local binding — still throws.
  *
  * Cross-file identifier resolution (chant #1020): `consts` alone is always
  * this file's own top-level bindings — that part stays single-file, and
@@ -69,6 +82,7 @@ export type FoldedValue =
   | { [key: string]: FoldedValue }
   | AttrRefValue
   | FoldedIntrinsic
+  | FoldedHelperCall
   | SymbolicValue
   | FoldedResource;
 
@@ -96,12 +110,50 @@ export interface AttrRefValue {
  * Mirrors the runtime call shape `Tag(strings, ...values)` so a later
  * build path can replay it into the real intrinsic object (#1022).
  */
-export interface FoldedIntrinsic {
+export type FoldedIntrinsic = FoldedIntrinsicTag | FoldedIntrinsicCall;
+
+/** The tagged-template form: `Sub\`${x}-y\`` — see {@link FoldedIntrinsic}. */
+export interface FoldedIntrinsicTag {
   __intrinsic: string;
   strings: string[];
   values: FoldedValue[];
 }
 
+/**
+ * The plain-call form of a registered, opted-in lexicon intrinsic
+ * (chant #1044) — `Ref(bucket)`, `Concat("a", b)`, `GetAtt("Fn", "Arn")`.
+ * Same `__intrinsic` key as the tagged-template form, so the same revival
+ * branch handles both and nothing downstream learns a new envelope; the
+ * payload differs because the call shape does — positional `args` mirroring
+ * `Name(...args)`, where the tag form mirrors `Name(strings, ...values)`.
+ *
+ * Symbolic, exactly like the tag form: `fold()` executes nothing, it only
+ * records that a registered intrinsic was called and with what. The real
+ * function is resolved through the folding file's own imports and invoked by
+ * `../discovery/fold-import.ts`'s `reviveFoldedValue`.
+ */
+export interface FoldedIntrinsicCall {
+  __intrinsic: string;
+  args: FoldedValue[];
+}
+
+/**
+ * The result of folding a call to a registered chant authoring helper
+ * (chant #1082) — e.g. `phase("Apply", [...])`, `output(ref, "oX")`. Holds
+ * the helper's name and its folded arguments, in source order.
+ *
+ * Symbolic, exactly like {@link FoldedIntrinsic}: `fold()` executes nothing,
+ * it only records that a registered helper was called and with what. The real
+ * function is resolved through the folding file's own imports and invoked by
+ * `../discovery/fold-import.ts`'s `reviveFoldedValue`, which is also where
+ * the "is this name actually bound to chant's own helper" check lives. See
+ * {@link "./foldable-helpers"} for the allowlist and why it is closed.
+ */
+export interface FoldedHelperCall {
+  __helper: string;
+  args: FoldedValue[];
+}
+
 /**
  * A sub-expression inside a folded intrinsic that fold could not reduce to
  * a value without resolving an identifier from outside this file — e.g. an
@@ -129,6 +181,18 @@ export interface FoldedResource {
    * ../runtime.ts). Present only when the source actually passed one.
    */
   attributes?: { [key: string]: FoldedValue };
+  /**
+   * chant #1082 — every constructor argument, folded, in source order. Present
+   * only when the argument list is NOT the classic `(props)` / `(props,
+   * attributes)` shape — most often because the props object isn't first
+   * (`new Parameter("String", {...})`, whose signature is `(type, props)`).
+   *
+   * When present this is authoritative: the entity is constructed by spreading
+   * it, so the constructor receives exactly what the source wrote. `props`
+   * alongside it is the first object-literal argument, reported for readers,
+   * never re-passed (which would double-count it).
+   */
+  args?: FoldedValue[];
 }
 
 /**
@@ -257,26 +321,49 @@ function resolvesToResource(consts: Map<string, ts.Expression>, ident: ts.Identi
 
 /**
  * True when `node` is an identifier, or a dotted/bracketed access chain
- * rooted at an identifier, that isn't bound in `consts` — e.g.
- * `AWS.StackName` from an imported pseudo-parameter namespace, or a bare
- * imported identifier. Resolving what it actually refers to requires
- * following an import (#1020), which is out of scope here.
+ * rooted at an identifier, that neither `consts` nor `externals` can resolve
+ * — e.g. `AWS.StackName` from an imported pseudo-parameter namespace inside
+ * a lexicon package (still #1063). Nothing here can say what it refers to,
+ * so an intrinsic's interior keeps it symbolically rather than rejecting it.
+ *
+ * `externals` (chant #1020) is consulted so a root that fold CAN resolve is
+ * not treated as unresolved: `Ref(environment)`, where `environment` is a
+ * `Parameter` imported from a sibling project file, must fold to the REAL,
+ * already-constructed Declarable the fold session made for that file, not to
+ * a `{__symbol}` the bridge later re-imports — re-importing the defining
+ * module builds a second, differently-identified instance of the same
+ * resource, which is exactly the shared-identity property #1020 exists to
+ * preserve (see fold-import.ts's module doc).
  */
-function isUnresolvedSymbolChain(node: ts.Expression, consts: Map<string, ts.Expression>): boolean {
-  if (ts.isIdentifier(node)) return node.text !== "undefined" && !consts.has(node.text);
-  if (ts.isPropertyAccessExpression(node)) return isUnresolvedSymbolChain(node.expression, consts);
-  if (ts.isElementAccessExpression(node)) return isUnresolvedSymbolChain(node.expression, consts);
-  if (ts.isNonNullExpression(node)) return isUnresolvedSymbolChain(node.expression, consts);
+function isUnresolvedSymbolChain(
+  node: ts.Expression,
+  consts: Map<string, ts.Expression>,
+  externals?: ReadonlyMap<string, unknown>,
+): boolean {
+  if (ts.isIdentifier(node)) {
+    return node.text !== "undefined" && !consts.has(node.text) && !externals?.has(node.text);
+  }
+  if (ts.isPropertyAccessExpression(node)) return isUnresolvedSymbolChain(node.expression, consts, externals);
+  if (ts.isElementAccessExpression(node)) return isUnresolvedSymbolChain(node.expression, consts, externals);
+  if (ts.isNonNullExpression(node)) return isUnresolvedSymbolChain(node.expression, consts, externals);
   return false;
 }
 
 /**
- * Fold one interpolated sub-expression of a registered intrinsic tagged
- * template. Identical to {@link fold}, except an unresolved external
- * symbol chain (a pseudo-parameter-style access this file can't see the
- * import for) folds to a {@link SymbolicValue} instead of throwing — the
- * run path resolves it once the module actually imports and runs; fold
- * preserves it symbolically rather than stringifying or rejecting it.
+ * Fold one sub-expression of a registered intrinsic's interior — an
+ * interpolation of its tagged-template form, or (chant #1044) an argument of
+ * its plain-call form. Identical to {@link fold}, except a symbol chain
+ * nothing can resolve (a pseudo-parameter-style access into a lexicon
+ * package, `AWS.StackName`) folds to a {@link SymbolicValue} instead of
+ * throwing — the run path resolves it once the module actually imports and
+ * runs; fold preserves it symbolically rather than stringifying or rejecting
+ * it, and fold-import.ts's `resolveSymbolicValue` resolves it for real
+ * before the intrinsic is constructed.
+ *
+ * `externals` (chant #1020) takes precedence over the symbolic path: see
+ * {@link isUnresolvedSymbolChain} for why an already-resolved cross-file
+ * binding must reach the intrinsic as the real, shared object rather than as
+ * a symbol the bridge re-imports.
  */
 function foldIntrinsicValue(
   node: ts.Expression,
@@ -284,16 +371,7 @@ function foldIntrinsicValue(
   intrinsics: readonly IntrinsicDef[],
   externals?: ReadonlyMap<string, unknown>,
 ): FoldedValue {
-  // Deliberately checks `consts` only, not `externals` — an imported
-  // identifier here still folds to a symbolic `{__symbol}` node exactly as
-  // before #1020, revived later by fold-import.ts's own
-  // `resolveSymbolicValue` (a real, trusted import of the defining module —
-  // fine for a plain pseudo-parameter-style namespace, the only shape this
-  // path exists for). Wiring `externals` in here too would mean two
-  // different mechanisms resolving the same cross-file name inside an
-  // intrinsic interpolation; out of scope for #1020, which only needs
-  // identifiers/property access OUTSIDE tagged templates to resolve.
-  if (isUnresolvedSymbolChain(node, consts)) {
+  if (isUnresolvedSymbolChain(node, consts, externals)) {
     return { __symbol: node.getText() };
   }
   return fold(node, consts, intrinsics, externals);
@@ -301,9 +379,13 @@ function foldIntrinsicValue(
 
 /**
  * Fold a `TaggedTemplateExpression` whose tag is a registered, foldable
- * lexicon intrinsic ({@link intrinsicFolds}, `../lexicon.ts`) to its node
+ * lexicon intrinsic ({@link intrinsicTagFolds}, `../lexicon.ts`) to its node
  * form. An unregistered — or registered-but-not-foldable — tag throws a
  * located {@link FoldError}.
+ *
+ * Checks the TAG-form predicate specifically (chant #1044): an intrinsic
+ * whose lexicon opted its plain-call form in is not thereby usable as a
+ * tagged template, and `` Ref`...` `` stays a rejection.
  */
 function foldTaggedTemplate(
   node: ts.TaggedTemplateExpression,
@@ -312,7 +394,7 @@ function foldTaggedTemplate(
   externals?: ReadonlyMap<string, unknown>,
 ): FoldedIntrinsic {
   const tagName = node.tag.getText();
-  const isRegistered = intrinsics.some((i) => i.name === tagName && intrinsicFolds(i));
+  const isRegistered = intrinsics.some((i) => i.name === tagName && intrinsicTagFolds(i));
   if (!isRegistered) {
     throw foldError(node, `unregistered tagged template intrinsic: ${tagName}\`...\``);
   }
@@ -332,13 +414,15 @@ function foldTaggedTemplate(
 /**
  * Fold a single expression node to a value. Throws {@link FoldError} for
  * anything outside the supported subset — including any `CallExpression`
- * that isn't a registered intrinsic tagged template.
+ * that is neither a registered chant authoring helper nor a registered,
+ * call-form-opted-in lexicon intrinsic (see the module doc).
  *
- * @param intrinsics - Lexicon-registered intrinsics that fold
- *   ({@link intrinsicFolds}, e.g. `Sub`). A tagged template whose tag isn't
- *   in this list, or is registered but not foldable, is rejected. Defaults
- *   to none — pass the target lexicon's manifest `intrinsics` to recognize
- *   its tags.
+ * @param intrinsics - The active lexicons' registered intrinsics. A tagged
+ *   template whose tag isn't in this list, or is in it without
+ *   {@link intrinsicTagFolds}, is rejected; a plain call is rejected unless
+ *   its callee is in this list with {@link intrinsicCallFolds} (chant
+ *   #1044). Defaults to none — pass the target lexicon's manifest
+ *   `intrinsics` to recognize either form.
  * @param externals - chant #1020: pre-resolved imported bindings, consulted
  *   only when an identifier isn't in `consts`. See the module doc above.
  *   `undefined` (the default) preserves the exact pre-#1020 single-file
@@ -555,6 +639,59 @@ export function fold(
   }
 
   if (ts.isCallExpression(node)) {
+    // chant #1082 — the ONE call shape that folds: a registered chant
+    // authoring helper ({@link FOLDABLE_AUTHORING_HELPERS}), called through a
+    // bare identifier that this file hasn't shadowed with its own `const`.
+    // Nothing is executed here — the call reduces to a symbolic
+    // {@link FoldedHelperCall} envelope, exactly as a registered intrinsic
+    // tagged template reduces to a {@link FoldedIntrinsic} one, and for the
+    // same reason: the real function lives in another module, and resolving
+    // + invoking it is the async bridge's job (../discovery/fold-import.ts's
+    // `reviveFoldedValue`), which also verifies the name is actually bound to
+    // an import of chant's own before invoking anything. Every other call —
+    // a user's function, a method call, a call to something declared in this
+    // file — still has no case and throws, unchanged.
+    if (
+      ts.isIdentifier(node.expression) &&
+      isFoldableHelperName(node.expression.text) &&
+      !consts.has(node.expression.text)
+    ) {
+      return {
+        __helper: node.expression.text,
+        args: node.arguments.map((arg) => fold(arg, consts, intrinsics, externals)),
+      };
+    }
+
+    // chant #1044 — the other call shape that folds: a lexicon intrinsic in
+    // PLAIN-CALL form (`Ref(bucket)`, `Concat("a", b)`), where that lexicon
+    // registered it AND opted its call form in ({@link intrinsicCallFolds},
+    // ../lexicon.ts — default off, never inferred). Reduces to the same
+    // `{__intrinsic}` envelope family the tagged-template form produces, with
+    // positional `args`; nothing is executed here, for the same reason as the
+    // tag form — the real function lives in the lexicon module, and resolving
+    // it through this file's own imports and invoking it is the async
+    // bridge's job (../discovery/fold-import.ts's `reviveFoldedValue`).
+    //
+    // Arguments fold through {@link foldIntrinsicValue}, exactly like a tag's
+    // interpolations: an intrinsic's interior is where a pseudo-parameter
+    // chain (`GetAZs(AWS.Region)`) legitimately appears, and it stays
+    // symbolic rather than rejecting.
+    //
+    // The door does not open any wider than this. A bare-identifier callee
+    // only, so `ns.Ref(...)` and `arr.map(...)` are untouched; the file's own
+    // `const` shadowing wins, so a local `Ref` is not the lexicon's; and a
+    // name absent from the active lexicons' registered set — or registered
+    // without the opt-in — falls straight through to the throw below.
+    if (ts.isIdentifier(node.expression) && !consts.has(node.expression.text)) {
+      const calleeName = node.expression.text;
+      if (intrinsics.some((i) => i.name === calleeName && intrinsicCallFolds(i))) {
+        return {
+          __intrinsic: calleeName,
+          args: node.arguments.map((arg) => foldIntrinsicValue(arg, consts, intrinsics, externals)),
+        };
+      }
+    }
+
     throw foldError(node, callExpressionMessage(node));
   }
 
@@ -562,12 +699,23 @@ export function fold(
 }
 
 /**
- * Fold a resource constructor call — `new Type({ ...props }, { ...attributes
- * })` — to its spec. Each argument present must be an object literal
- * (anything else is not statically evaluable and throws a located
- * {@link FoldError}). The second argument (CFN-style resource attributes —
- * `DependsOn`, `Condition`, `DeletionPolicy`, …) is optional, matching
- * `createResource`'s runtime constructor signature (../runtime.ts).
+ * Fold a resource constructor call to its spec.
+ *
+ * The common `createResource` shape (../runtime.ts) is `new Type({ ...props
+ * })` or `new Type({ ...props }, { ...attributes })` — CFN-style resource
+ * attributes (`DependsOn`, `Condition`, `DeletionPolicy`, …) second — and
+ * that shape reduces to `props` (+ `attributes`) exactly as before.
+ *
+ * chant #1082 — but that is a convention, not a rule every lexicon class
+ * follows. AWS's deploy-time `Parameter` is `(type, props)`
+ * (lexicons/aws/src/parameter.ts): the props object is the SECOND argument
+ * and the first is a plain string. `foldResource` used to require argument 0
+ * to be an object literal, so no `new Parameter(...)` anywhere could ever
+ * fold, whatever surrounded it. The general case now folds every argument in
+ * source order into {@link FoldedResource.args}, which the caller constructs
+ * the entity from verbatim — no positional assumption at all. `props` is
+ * still reported (the first object-literal argument, for callers that read
+ * it) but is a VIEW onto `args`, not the thing constructed from.
  */
 export function foldResource(
   node: ts.NewExpression,
@@ -576,24 +724,33 @@ export function foldResource(
   externals?: ReadonlyMap<string, unknown>,
 ): FoldedResource {
   const typeName = node.expression.getText();
-  const [firstArg, secondArg] = node.arguments ?? [];
+  const args = node.arguments ?? ([] as unknown as ts.NodeArray<ts.Expression>);
+  const [firstArg, secondArg] = args;
+  const foldArg = (arg: ts.Expression) => fold(arg, consts, intrinsics, externals);
 
   if (!firstArg) {
     return { __resource: typeName, props: {} };
   }
-  if (!ts.isObjectLiteralExpression(firstArg)) {
-    throw foldError(firstArg, resourceCtorArgMessage(typeName));
-  }
-  const props = fold(firstArg, consts, intrinsics, externals) as { [key: string]: FoldedValue };
 
-  if (!secondArg) {
-    return { __resource: typeName, props };
-  }
-  if (!ts.isObjectLiteralExpression(secondArg)) {
-    throw foldError(secondArg, `resource attributes argument must be an object literal: ${typeName}(...)`);
+  // The classic (props) / (props, attributes) shape — reported without an
+  // `args` list so the spec of an ordinary resource is unchanged.
+  if (ts.isObjectLiteralExpression(firstArg)) {
+    const props = foldArg(firstArg) as { [key: string]: FoldedValue };
+    if (args.length === 1) {
+      return { __resource: typeName, props };
+    }
+    if (args.length === 2 && ts.isObjectLiteralExpression(secondArg)) {
+      return { __resource: typeName, props, attributes: foldArg(secondArg) as { [key: string]: FoldedValue } };
+    }
   }
-  const attributes = fold(secondArg, consts, intrinsics, externals) as { [key: string]: FoldedValue };
-  return { __resource: typeName, props, attributes };
+
+  // Anything else: fold every argument positionally. Each one still has to be
+  // in the fold subset on its own terms — a non-foldable argument throws from
+  // `fold()` exactly as a non-foldable prop value does.
+  const folded = args.map(foldArg);
+  const propsIndex = args.findIndex((arg) => ts.isObjectLiteralExpression(arg));
+  const props = (propsIndex === -1 ? {} : folded[propsIndex]) as { [key: string]: FoldedValue };
+  return { __resource: typeName, props, args: folded };
 }
 
 function hasExportModifier(statement: ts.VariableStatement): boolean {

package/src/fold/foldable-helpers.ts

@@ -0,0 +1,171 @@
+/**
+ * foldable-helpers — the closed, declared allowlist of chant's OWN authoring
+ * helpers that a call expression may fold through (chant #1082, epic #1019).
+ *
+ * ## Why this exists
+ *
+ * `fold()` has no general case for a `CallExpression`: a function call as a
+ * value is structurally unrepresentable there, because folding it would mean
+ * executing code, which is the one thing the fold path exists to avoid. That
+ * rule is right for user code and stays right — a user's own function, an
+ * arrow function, a method call (`naming.name(...)`) all keep failing exactly
+ * as before.
+ *
+ * But it also blocks chant's own documented authoring API. `phase("Apply",
+ * [...])` is how the component contract says to write a component; `output(ref,
+ * "oX")` is how a lexicon output is authored. An application cannot avoid them
+ * and still use components or outputs, so every file that uses one falls back
+ * to run no matter how statically evaluable the rest of it is.
+ *
+ * #1044 already settled the shape of the answer one level down, for lexicon
+ * intrinsics: a call-shaped thing may fold ONLY when it is registered, opt-in,
+ * per-helper — never because it merely looks like a call. This module is the
+ * same decision applied one level up, to chant's own helpers, with the
+ * registration written here by hand instead of coming from a lexicon manifest.
+ *
+ * ## What "registered" buys, and what still has to be true
+ *
+ * A name in this list is NOT permission to invoke whatever it happens to be
+ * bound to. Folding a helper call is a two-key operation:
+ *
+ *   1. **Shape + name** (here, and in `fold()`/`findSubsetViolation`): the
+ *      callee is a bare identifier whose text is in {@link
+ *      FOLDABLE_AUTHORING_HELPERS} and which is not shadowed by a local
+ *      `const`. `fold()` reduces the call to a symbolic
+ *      `{ __helper, args }` envelope — it still executes nothing.
+ *   2. **Provenance + invocation** (`../discovery/fold-import.ts`): the
+ *      envelope is revived by resolving that name through the folding FILE'S
+ *      OWN `import` bindings and checking the import actually comes from chant
+ *      ({@link isChantOwnedSpecifier}, or a path inside chant-core's own tree
+ *      for in-repo/absolute-specifier callers). Only then is the real function
+ *      invoked, with the real folded arguments. A same-named helper imported
+ *      from somewhere else, or declared in the file itself, resolves to
+ *      nothing chant owns and the whole file falls back to run.
+ *
+ * So the function that runs is always the same function the run path would
+ * have called, from the same module the source itself imported — fold does not
+ * substitute its own reimplementation, which is why this list cannot drift
+ * from the helpers' real behavior.
+ *
+ * ## Admission criteria
+ *
+ * A helper belongs here only if all of these hold:
+ *
+ *   - chant owns and documents it as authoring surface;
+ *   - it is a pure function of its arguments — no I/O, no `process.env`, no
+ *     module-level mutable state, no observable side effect;
+ *   - calling it early (at fold time) is indistinguishable from calling it
+ *     during a real run of the file.
+ *
+ * Deliberately NOT admitted — see this module's tests and the #1082 PR body:
+ *
+ *   - `env()` (`../env.ts`) reads `process.env`. Folding it would bake one
+ *     run's environment into a statically-derived value. It is exactly the
+ *     kind of call fold must keep rejecting.
+ *   - `Op()` (`../op/builders.ts`) constructs an `OpResource` — a `Declarable`.
+ *     `fold()` already rejects a nested `new Type(...)` used as a value for a
+ *     real, differential-caught reason (the envelope leaks into
+ *     serialization); a factory that returns one is the same hazard wearing a
+ *     call.
+ *   - `propagate()`, `withDefaults()`, `resource()`, `mergeDefaults()`
+ *     (`../composite.ts`) are composite *definition* helpers, not value-position
+ *     helpers. `propagate()` in particular mutates its argument in place, and
+ *     the composite spine in fold-import.ts already resolves it live.
+ *   - `createResource()`/`createProperty()` (`../runtime.ts`) are used at a
+ *     lexicon module's top level to build classes, never as a value inside a
+ *     project file.
+ *   - Lexicon intrinsics in CALL form (`Ref(...)`, `Join(...)`) are lexicon
+ *     surface, not chant's own, and are #1044's registry (`IntrinsicDef`,
+ *     `../lexicon.ts`) to admit — not this one. Only their tagged-template
+ *     form folds today.
+ */
+
+/**
+ * One registered helper. `module` and `note` carry no runtime behavior — they
+ * are the audit trail for why this entry passed the admission criteria above,
+ * kept next to the name it justifies rather than in a comment that can drift
+ * away from the list.
+ */
+export interface FoldableHelperDef {
+  /** The exported name, matched against the callee identifier's text. */
+  readonly name: string;
+  /** Where chant defines it (a path under `packages/core/src`, for the audit trail). */
+  readonly module: string;
+  /** Why it qualifies — what it returns and why calling it at fold time is safe. */
+  readonly note: string;
+}
+
+/**
+ * The allowlist. Adding an entry is a deliberate act: it must satisfy every
+ * admission criterion in this module's doc, and it widens what `fold()` and
+ * `findSubsetViolation` accept for EVERY project, so it belongs in a PR that
+ * says so.
+ *
+ * Two names below are defined TWICE in chant, by different modules, with
+ * different return types (`phase`/`gate` by both the component contract and
+ * the Op builders; `stackOutput` by both the component contract and the
+ * cross-stack output primitive). That is fine and needs no disambiguation
+ * here: registration is by name, but the function actually invoked is the one
+ * the folding file itself imported (see step 2 in the module doc), so each
+ * file gets its own. Both definitions of each name independently satisfy the
+ * criteria, which is what makes registering the shared name safe.
+ */
+export const FOLDABLE_AUTHORING_HELPERS: readonly FoldableHelperDef[] = [
+  {
+    name: "phase",
+    module: "components/component.ts, op/builders.ts",
+    note: "Returns a plain `{ phase, steps, parallel? }` / `{ name, steps, parallel? }` object literal built from its arguments. No state, no I/O.",
+  },
+  {
+    name: "gate",
+    module: "components/component.ts, op/builders.ts",
+    note: "Returns a plain `{ kind: 'gate', signalName, ... }` object literal built from its arguments.",
+  },
+  {
+    name: "activity",
+    module: "op/builders.ts",
+    note: "Returns a plain `{ kind: 'activity', fn, args?, profile? }` object literal built from its arguments.",
+  },
+  {
+    name: "stackOutput",
+    module: "components/component.ts, stack-output.ts",
+    note: "Component form returns a plain `{ stackOutput: { stack, name } }` literal. Cross-stack form derives a `StackOutput` from a real `AttrRef`/`Intrinsic` and throws on anything else — so a fold that only has a symbolic reference fails loudly into run-fallback rather than producing a wrong output.",
+  },
+  {
+    name: "output",
+    module: "lexicon-output.ts",
+    note: "Constructs a `LexiconOutput` from a real `AttrRef`/`Intrinsic` and a name. Pure, but identity-sensitive: it reads through the ref's `WeakRef` to its parent entity. Only folds when the ref argument revives to a REAL live reference (see fold-import.ts's `requireLiveRefs`); a symbolic `{ __attrRef }` envelope is rejected, not silently wrapped.",
+  },
+];
+
+const HELPER_NAMES: ReadonlySet<string> = new Set(FOLDABLE_AUTHORING_HELPERS.map((h) => h.name));
+
+/**
+ * True when `name` is a registered foldable authoring helper. Name-only — this
+ * is the shape-level half of the check (step 1 in the module doc). It says
+ * nothing about where the name is bound; `../discovery/fold-import.ts` decides
+ * that before anything is invoked.
+ */
+export function isFoldableHelperName(name: string): boolean {
+  return HELPER_NAMES.has(name);
+}
+
+/**
+ * Package specifiers chant itself publishes. A registered helper name only
+ * folds when the folding file imported it from one of these — or, for in-repo
+ * and test callers that import chant-core by relative/absolute path, from
+ * inside chant-core's own tree (checked separately, in fold-import.ts, since
+ * only that module knows how to resolve a specifier to a path).
+ *
+ * Lexicon packages are included because several core helpers are re-exported
+ * through them and that is the documented import in real projects — e.g.
+ * `import { output } from "@intentius/chant-lexicon-aws"`.
+ */
+const CHANT_PACKAGE_SPECIFIERS: readonly string[] = ["@intentius/chant", "@intentius/chant-lexicon-"];
+
+/** True for a bare specifier that names a chant-published package (or one of its subpaths). */
+export function isChantOwnedSpecifier(specifier: string): boolean {
+  return CHANT_PACKAGE_SPECIFIERS.some(
+    (prefix) => specifier === prefix || specifier.startsWith(prefix.endsWith("-") ? prefix : `${prefix}/`),
+  );
+}

package/src/fold/subset-doc-parity.test.ts

@@ -135,12 +135,39 @@ describe("subset-doc-parity — supported patterns in typescript-as-data.mdx cla
     expect(findSubsetViolation(resourceArg(consts, "store"))).toBeUndefined();
   });
 
+  test("Registered intrinsic calls", () => {
+    // chant #1044 — the one doc snippet that needs the registry to classify:
+    // `Ref(...)` is only in the subset because a lexicon opted its call form
+    // in, and `findSubsetViolation` answers exactly that question when it is
+    // given the registry (subset.ts module doc, point 2c). Without one it
+    // would report a violation, which is the pre-#1044 answer EVL still gets.
+    const consts = parseConsts(extractFencedBlock("Registered intrinsic calls"));
+    const intrinsics = [
+      { name: "Sub", isTag: true },
+      { name: "Ref", isTag: false, foldsAsCall: true },
+    ];
+    expect(findSubsetViolation(resourceArg(consts, "store"), intrinsics)).toBeUndefined();
+    expect(findSubsetViolation(resourceArg(consts, "store"))).toBeDefined();
+  });
+
   test("Typed property-kind constructors", () => {
     const consts = parseConsts(extractFencedBlock("Typed property-kind constructors"));
     expect(findSubsetViolation(resourceArg(consts, "config"))).toBeUndefined();
     expect(findSubsetViolation(resourceArg(consts, "access"))).toBeUndefined();
   });
 
+  test("Registered authoring helpers", () => {
+    // chant #1082 — not a `new Type({...})` declaration, so classify the
+    // exported component object literal directly. `findSubsetViolation`
+    // checks the helper NAME only (subset.ts module doc, point 2b); the
+    // doc's own snippet imports them from chant, which is what the bridge
+    // additionally verifies at fold time.
+    const consts = parseConsts(extractFencedBlock("Registered authoring helpers"));
+    const web = consts.get("web");
+    if (!web) throw new Error(`subset-doc-parity: "web" did not parse as a const declaration`);
+    expect(findSubsetViolation(web)).toBeUndefined();
+  });
+
   test("Nullish coalescing for defaults", () => {
     // Not a standalone statement in the doc (a single object-literal
     // property, deliberately shown as a fragment) — wrapped in an object