@intentius/chant 0.51.0 → 0.52.1

package/src/cli/build-options.ts

@@ -0,0 +1,109 @@
+/**
+ * The one place chant assembles `build()`'s options for a project directory.
+ *
+ * chant #2002 — `chant build` (./commands/build.ts) and the `policyGate` Op
+ * step (../lint/policy.ts's `evaluateProjectPolicies`) both build the same
+ * directory, and each used to assemble that option object itself. The two lists
+ * drifted to nine options against two: the gate built with fold off (the path
+ * `chant build` retired as its default in #1134), without the project's config
+ * (so serializers lost their lexicon-scoped dialect settings and a policy
+ * reading `ctx.docs` inspected different documents), and without `buildRoots`
+ * (so config-declared roots contributed no entities at all). A gate can only
+ * decide on a build `chant build` would produce if the two are assembled from
+ * one place, so they are.
+ *
+ * Two functions rather than one because the *modes* are needed earlier than the
+ * rest: `chant build` arms sandboxed policy execution from the resolved
+ * `sandbox` before it loads any policy module, which happens before build-time
+ * parameters and the ownership marker exist. {@link resolveBuildModes} is that
+ * early half; {@link resolveProjectBuildOptions} takes its result and assembles
+ * everything `build()` is given.
+ */
+import { resolveFoldEnabled, resolveSandboxEnabled, type ChantConfig } from "../config";
+import { collectBuildRootContributors, resolveLexiconVersions } from "./plugins";
+import type { LexiconPlugin } from "../lexicon";
+import type { BuildOptions } from "../build";
+import type { OwnershipMarker } from "../ownership";
+import type { BuildParamProvenance } from "../provenance";
+
+/** The resolved fold/sandbox execution modes for one build. */
+export interface BuildModes {
+  /** #1022/#1134 — fold source modules statically; the default build path. */
+  fold: boolean;
+  /** #1045 Phase 2 — execute run-fallback files in a sandboxed child. */
+  sandbox: boolean;
+}
+
+/**
+ * Resolve this build's execution modes: an explicit CLI flag wins over
+ * `chant.config.ts`'s `build.fold`/`build.sandbox`, which wins over the default
+ * (fold on, sandbox off). Callers with no flags to offer (the `policyGate` step)
+ * pass no overrides and get the project's own answer.
+ */
+export function resolveBuildModes(
+  config: ChantConfig,
+  overrides?: { fold?: boolean; sandbox?: boolean },
+): BuildModes {
+  return {
+    fold: resolveFoldEnabled(config, overrides?.fold),
+    sandbox: resolveSandboxEnabled(config, overrides?.sandbox),
+  };
+}
+
+/** Inputs {@link resolveProjectBuildOptions} needs to assemble a build. */
+export interface ProjectBuildOptionsInput {
+  /** The project's resolved config, from `loadChantConfigUpward`. */
+  config: ChantConfig;
+  /** Directory the config was found in — build roots are rooted here, not at a (possibly sourceDir-scoped) build path. */
+  configDir: string;
+  /** The lexicon plugins loaded for this build. */
+  plugins?: readonly LexiconPlugin[];
+  /** Resolved execution modes, from {@link resolveBuildModes}. */
+  modes: BuildModes;
+  /** The resolved ownership marker, when marking is on. */
+  ownership?: OwnershipMarker;
+  /** This build's resolved build-time parameters (#1064). */
+  buildParams?: BuildParamProvenance[];
+}
+
+/**
+ * Assemble the option object `build()` takes for a project directory.
+ *
+ * Every option here is derived from the project (its config, its plugins, its
+ * resolved parameters) rather than from the command that asked, so two callers
+ * handing in the same project get byte-identical builds. A new option belongs
+ * in this function, never at a call site.
+ */
+export function resolveProjectBuildOptions(input: ProjectBuildOptionsInput): BuildOptions {
+  const { config, configDir, plugins, modes, ownership, buildParams } = input;
+
+  // #1039 — each loaded plugin's registered intrinsics (e.g. AWS's `Sub`), so
+  // a file using a registered intrinsic tagged template folds instead of
+  // unconditionally falling back to run. `intrinsics` is an optional plugin
+  // extension, hence the guard.
+  const intrinsics = plugins?.flatMap((plugin) => plugin.intrinsics?.() ?? []) ?? [];
+
+  // #1063 — the same loaded plugins, by NAME, are this build's allowlist for
+  // following a bare import specifier into a lexicon package (so `Azure`,
+  // `GCP`, `S3Actions`, `CI` fold as values).
+  const lexicons = plugins?.map((plugin) => plugin.name) ?? [];
+
+  return {
+    ownership,
+    config: config as unknown as Record<string, unknown>,
+    fold: modes.fold,
+    sandbox: modes.sandbox,
+    intrinsics,
+    lexicons,
+    // chant #1442 — which lexicon VERSION interpreted each declaration.
+    lexiconVersions: resolveLexiconVersions(lexicons),
+    buildParams,
+    // #1548 piece 3 — config-declared build roots (kustomize dirs, committed
+    // ciphertext), rendered into entities by the owning lexicon's hook.
+    buildRoots: collectBuildRootContributors(
+      plugins,
+      config as unknown as Record<string, unknown>,
+      configDir,
+    ),
+  };
+}

package/src/cli/commands/build.ts

@@ -5,17 +5,15 @@ import {
   resolveOwnershipEnv,
   ownershipEnvDisagreement,
   isOwnershipParamRef,
-  resolveFoldEnabled,
-  resolveSandboxEnabled,
   resolveKnowledgeDir,
 } from "../../config";
+import { resolveBuildModes, resolveProjectBuildOptions } from "../build-options";
 import { loadOkfBundle } from "../../okf-read";
 import { unknownEnvError } from "../../env";
 import type { OwnershipMarker } from "../../ownership";
 import { resolveCliBuildParams } from "../build-params-cli";
 import type { Serializer, SerializerResult } from "../../serializer";
 import type { LexiconPlugin } from "../../lexicon";
-import { resolveLexiconVersions, collectBuildRootContributors } from "../plugins";
 import { runPostSynthChecks } from "../../lint/post-synth";
 import { coreReceiptChecks } from "../../lint/receipt-checks";
 import { coreOutputChecks } from "../../lint/output-checks";
@@ -182,15 +180,14 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
   const configDir = loaded.configPath ? dirname(loaded.configPath) : infraPath;
   const policies = config.lint?.policies ?? [];
 
-  // #1022/#1134 — fold is the default build path: an explicit CLI flag
-  // (--fold/--no-fold) wins over `chant.config.ts`'s `build.fold`, which
-  // wins over the default of `true`.
-  const fold = resolveFoldEnabled(config, options.fold);
-
-  // #1045 Phase 2 — opt-in sandboxed execution of run-fallback files (or,
-  // without --fold, every file). Same CLI-flag-wins-over-config precedence
-  // as fold, resolved independently.
-  const sandbox = resolveSandboxEnabled(config, options.sandbox);
+  // #1022/#1134 (fold) and #1045 Phase 2 (sandbox) — an explicit CLI flag
+  // (--fold/--no-fold, --sandbox) wins over `chant.config.ts`'s
+  // `build.fold`/`build.sandbox`, which wins over the defaults (fold on,
+  // sandbox off). Resolved here rather than with the rest of the build
+  // options below because arming sandboxed policy execution has to happen
+  // before any policy module could be loaded — see #2002 in ../build-options.ts.
+  const modes = resolveBuildModes(config, { fold: options.fold, sandbox: options.sandbox });
+  const { fold, sandbox } = modes;
 
   // #1131 — arm sandboxed policy execution from the RESOLVED value, before any
   // policy module could be loaded. Resolved, not `options.sandbox`, because
@@ -301,48 +298,22 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
     }
   }
 
-  // #1039 — thread each loaded plugin's registered intrinsics (e.g. AWS's
-  // `Sub`) through to the fold path, so a file using a registered intrinsic
-  // tagged template folds instead of unconditionally falling back to run.
-  // `intrinsics` is an optional plugin extension (not every lexicon defines
-  // any), hence the guard.
-  const intrinsics = options.plugins?.flatMap((plugin) => plugin.intrinsics?.() ?? []) ?? [];
-
-  // #1063 — the same loaded plugins, by NAME, are this build's allowlist for
-  // following a bare import specifier into a lexicon package (so `Azure`,
-  // `GCP`, `S3Actions`, `CI` fold as values). A plugin's `name` is the
-  // lexicon name `loadPlugin()` was called with, which is exactly what
-  // `@intentius/chant-lexicon-<name>` was imported from — see
-  // ../plugins.ts and fold-import.ts's `lexiconPackageName`.
-  const lexicons = options.plugins?.map((plugin) => plugin.name) ?? [];
-
-  // chant #1442 — which lexicon VERSION interpreted each declaration. The
-  // declaration is fingerprinted by `hashProps`; the thing that turned it into
-  // output was not recorded at all, so a lexicon bump that changed emitted
-  // output left the build digest identical. Captured here because this is the
-  // layer that knows which lexicons were loaded — `build()` is given only
-  // their names.
-  const lexiconVersions = resolveLexiconVersions(lexicons);
-
-  // Run the build
-  const result = await build(infraPath, options.serializers, undefined, {
-    ownership,
-    config: config as unknown as Record<string, unknown>,
-    fold,
-    sandbox,
-    intrinsics,
-    lexicons,
-    lexiconVersions,
-    buildParams: paramsResolution.provenance,
-    // #1548 piece 3 — config-declared build roots (kustomize dirs), rendered
-    // into entities by the owning lexicon's hook. Rooted at the config dir,
-    // not the (possibly sourceDir-scoped) infra path.
-    buildRoots: collectBuildRootContributors(
-      options.plugins,
-      config as unknown as Record<string, unknown>,
+  // Run the build. #2002 — every option comes from the shared assembler
+  // (../build-options.ts), which `evaluateProjectPolicies` calls too, so the
+  // `policyGate` step decides on the same project this command builds.
+  const result = await build(
+    infraPath,
+    options.serializers,
+    undefined,
+    resolveProjectBuildOptions({
+      config,
       configDir,
-    ),
-  });
+      plugins: options.plugins,
+      modes,
+      ownership,
+      buildParams: paramsResolution.provenance,
+    }),
+  );
 
   // #1022 — report per-file fold vs run so it's visible what still runs.
   // #1424 — one line by default; the per-file lines and their reasons are

package/src/cli/handlers/lifecycle.test.ts

@@ -753,6 +753,25 @@ describe("runLifecyclePlan", () => {
     expect(stdoutBuf.join("\n")).toContain("bucket");
   });
 
+  // #1983 — `--report markdown` emits the reviewer-facing projection instead
+  // of the human render, same as `--report gitlab-mr` swaps in the widget JSON.
+  test("--report markdown emits the markdown projection instead of the human render", async () => {
+    buildMock.mockResolvedValue(makeBuildResult({ aws: ["bucket"] }));
+    const plugins: LexiconPlugin[] = [
+      createMockPlugin({ name: "aws", emulator: awsEmulatorStub, describeResources: staticDescribeResources({}) }),
+    ];
+    const exit = await runLifecyclePlan({
+      args: makeArgs({ path: "plan", extraPositional: "prod", reportFile: "markdown" }),
+      plugins,
+      serializers: plugins.map((p) => p.serializer),
+    });
+    expect(exit).toBe(0);
+    const out = stdoutBuf.join("\n");
+    expect(out).toContain("## Plan for `prod`");
+    expect(out).toContain("### CREATE");
+    expect(out).toContain("- `bucket`");
+  });
+
   // #1620 — the resolved read address rides plan entries the same way it rides
   // the live diff. Regression: the plan path dropped the observation's queried
   // map, so only unobserved rows ever carried an address while the docs

package/src/cli/handlers/lifecycle.ts

@@ -18,7 +18,7 @@ import {
 } from "../../lifecycle/observation-baseline";
 import { computeBuildDigest, diffDigests } from "../../lifecycle/digest";
 import { diffLive, diffLiveArtifacts, diffSnapshots, type LiveDiffResult, type LiveArtifactDiffResult, type SnapshotDiffResult } from "../../lifecycle/live-diff";
-import { buildChangeSet, renderChangeSet, gitlabMrReport, summarize, type ChangeSet } from "../../lifecycle/change-set";
+import { buildChangeSet, renderChangeSet, renderChangeSetMarkdown, gitlabMrReport, unobservedPlanNotice, type ChangeSet } from "../../lifecycle/change-set";
 import { mergeReceiptEntries, observedValueResolver, planReceipts, readReceiptValue, type ReceiptReading } from "../../lifecycle/receipt-plan";
 import { annotateDisruption, disruptionNotices } from "../../lifecycle/disruption";
 import { collectEffectReceipts, isEffectReceipt } from "../../effect-receipt";
@@ -1302,12 +1302,11 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
   merged.entries.sort((a, b) => a.name.localeCompare(b.name));
 
   // Say it on stderr too, so `--json` and `--report gitlab-mr` consumers (whose
-  // shapes have no room for it) still learn the plan has a hole (#1089).
-  const unobservedCount = summarize(merged).unobserved;
-  if (unobservedCount > 0) {
-    console.error(formatWarning({
-      message: `${unobservedCount} declared entity(ies) could not be observed — no create/update/delete is proposed for them. This plan is incomplete, not clean.`,
-    }));
+  // shapes have no room for it) still learn the plan has a hole (#1089). The
+  // `markdown` report carries the same wording in its own body instead — a
+  // reviewer reading a comment never sees this stderr.
+  for (const notice of unobservedPlanNotice(merged)) {
+    console.error(formatWarning({ message: notice }));
   }
 
   // Same reason as above (#1665): the `--json` and `--report gitlab-mr` shapes
@@ -1324,6 +1323,14 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
     return 0;
   }
 
+  // `--report markdown` emits the reviewer-facing projection (#1983) — a
+  // counts header, entries grouped and attributed to their lexicon, holes and
+  // disruption both carried in the body rather than left to stderr.
+  if (args.reportFile === "markdown") {
+    console.log(renderChangeSetMarkdown(merged));
+    return 0;
+  }
+
   if (args.json) {
     console.log(JSON.stringify(merged, null, 2));
   } else {

package/src/cli/handlers/run.test.ts

@@ -987,6 +987,102 @@ describe("runOp dispatcher", () => {
   });
 });
 
+/**
+ * chant #2003 — `--sandbox` is a global flag and `../main.ts` arms the
+ * process-wide policy latch off it for every command, so `chant run <op>
+ * --sandbox` on an Op with a `policyGate` step used to reach `loadPolicyChecks`
+ * mid-run and show the user a message written for a chant maintainer ("This is
+ * a chant bug"). At the CLI level, not on `loadPolicyChecks`: the defect was
+ * that the combination got that far, not what the refusal says.
+ */
+describe("runOp: --sandbox with a policyGate step (chant #2003)", () => {
+  const policyGateOp = (name: string) =>
+    localOp(name, [{ kind: "activity", fn: "policyGate", args: { path: "." } }]);
+
+  beforeEach(() => {
+    discoverOpsMock.mockReset();
+    loadTemporalClientMock.mockReset();
+    loadChantConfigMock.mockReset();
+    resolveProfileMock.mockReset();
+    existsSyncMock.mockReset();
+    spawnChildMock.mockReset();
+  });
+
+  test("local mode → refuses before any phase runs, naming the combination", async () => {
+    discoverOpsMock.mockResolvedValue({ ops: new Map([policyGateOp("gate")]), errors: [] });
+    const stderr = makeStderrSpy();
+
+    const exit = await runOp({ args: makeArgs({ path: "gate", temporal: false, sandbox: true }), plugins: [], serializers: [] });
+
+    expect(exit).toBe(1);
+    const out = stderr.join("\n");
+    expect(out).toContain("policyGate");
+    expect(out).toContain("--sandbox");
+    // The message the user used to get instead.
+    expect(out).not.toContain("This is a chant bug");
+  });
+
+  test("--temporal → the same refusal, as a CLI error rather than an activity failure", async () => {
+    discoverOpsMock.mockResolvedValue({ ops: new Map([policyGateOp("gate")]), errors: [] });
+    const stderr = makeStderrSpy();
+
+    const exit = await runOp({ args: makeArgs({ path: "gate", temporal: true, sandbox: true }), plugins: [], serializers: [] });
+
+    expect(exit).toBe(1);
+    expect(stderr.join("\n")).toContain("policyGate");
+    // Refused before the project config is even loaded — nothing is scheduled.
+    expect(loadChantConfigMock).not.toHaveBeenCalled();
+    expect(loadTemporalClientMock).not.toHaveBeenCalled();
+  });
+
+  test("a policyGate nested in an effect step is found too", async () => {
+    discoverOpsMock.mockResolvedValue({
+      ops: new Map([
+        localOp("gate", [
+          { kind: "effect", steps: [{ kind: "activity", fn: "policyGate", args: { path: "." } }] },
+        ]),
+      ]),
+      errors: [],
+    });
+    const stderr = makeStderrSpy();
+
+    const exit = await runOp({ args: makeArgs({ path: "gate", temporal: false, sandbox: true }), plugins: [], serializers: [] });
+
+    expect(exit).toBe(1);
+    expect(stderr.join("\n")).toContain("policyGate");
+  });
+
+  test("without --sandbox the same Op is not refused", async () => {
+    discoverOpsMock.mockResolvedValue({ ops: new Map([policyGateOp("gate")]), errors: [] });
+    loadChantConfigMock.mockResolvedValue({ config: {} });
+    resolveProfileMock.mockReturnValue({ address: "localhost:7233", namespace: "default", taskQueue: "q" });
+    existsSyncMock.mockReturnValue(false);
+    const stderr = makeStderrSpy();
+
+    // The Temporal path, so the run stops at the missing worker.ts rather than
+    // actually building a project: reaching that point proves the pre-flight
+    // let it through.
+    const exit = await runOp({ args: makeArgs({ path: "gate", temporal: true }), plugins: [], serializers: [] });
+
+    expect(exit).toBe(1);
+    expect(stderr.join("\n")).toContain("worker.ts not found");
+    expect(loadChantConfigMock).toHaveBeenCalled();
+  });
+
+  test("--sandbox on an Op with no policyGate step is untouched", async () => {
+    discoverOpsMock.mockResolvedValue({
+      ops: new Map([localOp("hello", [{ kind: "activity", fn: "shellCmd", args: { cmd: "true" } }])]),
+      errors: [],
+    });
+    const stderrWrite = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+
+    const exit = await runOp({ args: makeArgs({ path: "hello", temporal: false, sandbox: true }), plugins: [], serializers: [] });
+
+    expect(exit).toBe(0);
+    stderrWrite.mockRestore();
+  });
+});
+
 describe("Temporal-only subcommand guards", () => {
   const cases: Array<[string, (ctx: { args: ParsedArgs; plugins: never[]; serializers: never[] }) => Promise<number>]> = [
     ["list", runOpList],

package/src/cli/handlers/run.ts

@@ -4,8 +4,9 @@ import { createConnection } from "node:net";
 import { spawn as spawnChild, type ChildProcess } from "node:child_process";
 import { loadChantConfig, resolveAutoReleaseDisabled, type ChantConfig } from "../../config";
 import { discoverOps } from "../../op/discover";
+import type { OpConfig } from "../../op/types";
 import { loadActivities, loadProfiles } from "../../op/activity-registry";
-import { runOpLocally, findGate, LocalGateUnsupportedError, OpRunFailure, type StepRecord } from "../../op/local-executor";
+import { runOpLocally, findGate, findPolicyGateStep, LocalGateUnsupportedError, OpRunFailure, type StepRecord } from "../../op/local-executor";
 import { renderHuman, renderJson } from "../../op/local-output";
 import { formatError, formatWarning, formatSuccess, formatBold, formatInfo } from "../format";
 import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli";
@@ -561,6 +562,32 @@ function renderProgress(opName: string, history: WorkflowHistoryRaw): void {
  * live reaching an actual cloud shell-out. Erroring here is the safe minimum
  * called out on the issue; a real preview is future work.
  */
+/**
+ * Pre-flight for `chant run <op> --sandbox` on an Op containing a `policyGate`
+ * step (chant #2003). `--sandbox` is a global flag, and `../main.ts` arms the
+ * process-wide policy latch off it for every command — so the gate's
+ * `loadPolicyChecks` refuses mid-run with a message addressed to a chant
+ * maintainer ("This is a chant bug"), or, under `--temporal`, as a
+ * non-retryable activity failure inside the workflow. Neither is an answer a
+ * user can act on. Refuse here instead, before anything runs, naming the
+ * combination and what to do about it.
+ *
+ * Keyed on the flag rather than on whether the project declares
+ * `lint.policies`: the flag is what arms the latch, and a gate that builds the
+ * project in this process is a divergence from what `--sandbox` promises
+ * whether or not a policy module happens to be declared. Returns true when the
+ * caller should stop.
+ */
+function refusesPolicyGateUnderSandbox(ctx: CommandContext, config: OpConfig, opName: string): boolean {
+  if (!ctx.args.sandbox) return false;
+  if (!findPolicyGateStep(config)) return false;
+  console.error(formatError({
+    message: `Op "${opName}" has a policyGate step, which cannot run under --sandbox: the gate builds this project and imports its lint.policies in the chant process, which --sandbox forbids.`,
+    hint: "Re-run without --sandbox, or drop the policyGate step from this Op. Running the gate itself inside the sandbox boundary is tracked on chant#1157.",
+  }));
+  return true;
+}
+
 export async function runOp(ctx: CommandContext): Promise<number> {
   if (ctx.args.components && ctx.args.report) {
     console.error(formatError({
@@ -1061,6 +1088,9 @@ export async function runOpLocal(ctx: CommandContext): Promise<number> {
 
   const { config } = discovered;
 
+  // Pre-flight: --sandbox cannot cover a policyGate step (#2003).
+  if (refusesPolicyGateUnderSandbox(ctx, config, opName)) return 1;
+
   // Pre-flight: gates/schedules need a durable runtime — fail before any step.
   const gate = findGate(config);
   if (gate) {
@@ -1145,6 +1175,12 @@ async function runOpTemporal(ctx: CommandContext): Promise<number> {
   }
 
   const { config } = discovered;
+
+  // Pre-flight: --sandbox cannot cover a policyGate step (#2003). Refused here
+  // too, so the durable path fails as a CLI error rather than as a
+  // non-retryable activity failure buried in workflow history.
+  if (refusesPolicyGateUnderSandbox(ctx, config, opName)) return 1;
+
   const projectPath = resolve(".");
 
   // Load config + profile

package/src/cli/main.ts

@@ -624,6 +624,8 @@ Options:
                         OR with a path arg: SARIF report destination (migrate)
                         OR '--report gitlab-mr': emit the GitLab MR plan-widget
                         JSON (lifecycle plan)
+                        OR '--report markdown': emit a reviewer-facing markdown
+                        render, holes and disruption included (lifecycle plan)
   --from <name>         Source lexicon for migrate (default: github)
   --to <name>           Target lexicon for migrate (default: gitlab)
   --emit <fmt>          Migration output format: yaml (default) or ts

package/src/discovery/fold-import.test.ts

@@ -2015,6 +2015,108 @@ describe("tryFoldFile — active lexicon package exports (#1063)", () => {
   });
 });
 
+describe("tryFoldFile — sandbox trust boundary, subpath import of an active lexicon package (chant #1995)", () => {
+  let testDir: string;
+  let seq = 0;
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `chant-fold-import-lexsubpath-test-${Date.now()}-${Math.random()}`);
+    await mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  /**
+   * Install a package into `<testDir>/node_modules/<name>` shaped like a real
+   * lexicon package: a barrel at "." AND a `./generated/index` subpath — the
+   * exact shape `examples/cc-azure-canonical/src/cc-cluster/cluster.ts`
+   * imports `AksCluster` through (`@intentius/chant-lexicon-azure/generated/index`).
+   * The subpath module exports a real resource CLASS with the same runtime
+   * shape `createResource` (chant-core's own factory) produces — plain,
+   * dependency-free JS using `Symbol.for("chant.declarable")` directly (same
+   * global-registry trick `../declarable.ts`'s own `DECLARABLE_MARKER` uses,
+   * and the same convention `installLexiconPackage`'s `LEXICON_SOURCE` above
+   * follows), rather than importing chant-core's runtime module: a real
+   * package's OWN `.js` file is loaded by a genuine `import()`, not run
+   * through this repo's TS loader, so a bare relative import of `runtime.ts`
+   * from inside it would need an extension Node's ESM resolver never gets —
+   * self-contained avoids that entirely and is just as faithful a stand-in.
+   */
+  async function installSubpathLexiconPackage(): Promise<{ lexicon: string; specifier: string }> {
+    const lexicon = `fold1995x${seq++}${Date.now().toString(36)}`;
+    const specifier = `@intentius/chant-lexicon-${lexicon}`;
+    const dir = join(testDir, "node_modules", specifier);
+    await mkdir(join(dir, "generated"), { recursive: true });
+    await writeFile(
+      join(dir, "package.json"),
+      JSON.stringify({
+        name: specifier,
+        version: "0.0.0",
+        type: "module",
+        exports: { ".": "./index.js", "./generated/index": "./generated/index.js" },
+      }),
+    );
+    await writeFile(join(dir, "index.js"), `export * from "./generated/index.js";`);
+    await writeFile(
+      join(dir, "generated", "index.js"),
+      `
+        const DECLARABLE_MARKER = Symbol.for("chant.declarable");
+        export function Widget(props) {
+          this[DECLARABLE_MARKER] = true;
+          this.lexicon = ${JSON.stringify(lexicon)};
+          this.entityType = "Test::Widget";
+          this.kind = "resource";
+          this.props = props ?? {};
+        }
+      `,
+    );
+    return { lexicon, specifier };
+  }
+
+  test("a subpath import of a declared-active lexicon package is trusted, and folds under --sandbox", async () => {
+    const { lexicon, specifier } = await installSubpathLexiconPackage();
+    const file = join(testDir, "main.ts");
+    await writeFile(
+      file,
+      `
+        import { Widget } from ${JSON.stringify(`${specifier}/generated/index`)};
+        export const widget = new Widget({ name: "test" });
+      `,
+    );
+
+    const sandboxed = await tryFoldFile(file, [], createFoldSession([], undefined, [lexicon], true));
+
+    expect(sandboxed.ok, !sandboxed.ok ? sandboxed.reason : "").toBe(true);
+    if (!sandboxed.ok) return;
+    const [, entity] = sandboxed.entities[0];
+    expect(isDeclarable(entity)).toBe(true);
+  });
+
+  test("a subpath import of a lexicon package NOT active for this build stays refused under --sandbox", async () => {
+    // chant #1995's own boundary — the fix must not widen trust beyond the
+    // build's declared-active set: an installed, importable package whose
+    // root the build never listed is still untrusted, subpath or not.
+    const { specifier } = await installSubpathLexiconPackage();
+    const file = join(testDir, "main.ts");
+    await writeFile(
+      file,
+      `
+        import { Widget } from ${JSON.stringify(`${specifier}/generated/index`)};
+        export const widget = new Widget({ name: "test" });
+      `,
+    );
+
+    const sandboxed = await tryFoldFile(file, [], createFoldSession([], undefined, ["aws"], true));
+
+    expect(sandboxed.ok).toBe(false);
+    if (sandboxed.ok) return;
+    expect(sandboxed.reason).toContain("--sandbox");
+    expect(sandboxed.reason).toContain(`constructor "Widget"`);
+  });
+});
+
 /**
  * chant #1169 — a `new Type(...)` used as a VALUE.
  *

package/src/discovery/fold-import.ts

@@ -1078,11 +1078,46 @@ function paramsModulePath(): string | null {
  *  - **Lexicons of THIS build only.** Not "any `@intentius/chant-lexicon-*`
  *    package on disk", and emphatically not "any bare specifier". A lexicon
  *    the build did not load is as out of scope as `node:fs`.
+ *
+ * chant #1995 — the "no subpaths" restriction above stays as documented for
+ * THIS function's caller ({@link resolveActiveLexiconExport}, #1063's
+ * data-export resolution): every lexicon's public data surface is reachable
+ * from the barrel, so a subpath buys that caller nothing and would cost the
+ * same cold-resolution risk. {@link isTrustedExecutableBinding} (#1093) asks a
+ * different question — not "does this specifier name a reachable data
+ * export" but "has the CLI already loaded this code" — and a project file
+ * reaching a lexicon's generated module by subpath instead of through the
+ * barrel is code the CLI already imported and executed either way, so that
+ * caller resolves a subpath's package root separately, via
+ * {@link bareSpecifierPackageRoot}, rather than widening this function.
  */
 function activeLexiconPackage(specifier: string, lexiconPackages: ReadonlySet<string>): string | undefined {
   return lexiconPackages.has(specifier) ? specifier : undefined;
 }
 
+/**
+ * chant #1995 — the package-ROOT portion of a bare subpath specifier
+ * (`@intentius/chant-lexicon-azure/generated/index` ->
+ * `@intentius/chant-lexicon-azure`), or `undefined` when `specifier` is a
+ * relative/absolute path, is already a bare root with no subpath, or is
+ * malformed (a lone `@scope` with nothing after it).
+ *
+ * Text only, no resolution — the same discipline {@link activeLexiconPackage}
+ * documents and for the identical reason: resolving an arbitrary bare
+ * specifier to find out what package it belongs to is the pathological cold
+ * `require.resolve` chant#1020 measured. A scoped package (`@scope/name`)
+ * reserves its first two `/`-separated segments for the root; an unscoped
+ * package (`name`) reserves one.
+ */
+function bareSpecifierPackageRoot(specifier: string): string | undefined {
+  if (specifier.startsWith(".") || isAbsolute(specifier)) return undefined;
+  const segments = specifier.split("/");
+  if (specifier.startsWith("@")) {
+    return segments.length > 2 ? `${segments[0]}/${segments[1]}` : undefined;
+  }
+  return segments.length > 1 ? segments[0] : undefined;
+}
+
 /**
  * chant #1063 — resolve one named import binding against an active lexicon
  * package's REAL exports, for {@link buildExternals}.
@@ -2706,10 +2741,19 @@ function isChantOwnedHelperBinding(binding: ImportBinding, ctx: ResolveCtx): boo
  * in the CLI's own process when the #1045 sandbox is active. Exactly two
  * arms, and neither of them trusts text the project controls:
  *
- *  1. **An ACTIVE lexicon package of this build** — matched against
- *     {@link FoldSession.lexiconPackages}, a closed set built from the
- *     lexicon names the BUILD resolved and `loadPlugins` already imported
- *     (../cli/plugins.ts), not from anything the file under fold says.
+ *  1. **An ACTIVE lexicon package of this build, root OR subpath** — the
+ *     exact specifier matched against {@link FoldSession.lexiconPackages}, a
+ *     closed set built from the lexicon names the BUILD resolved and
+ *     `loadPlugins` already imported (../cli/plugins.ts), not from anything
+ *     the file under fold says; OR (chant #1995) a subpath of one of those
+ *     same packages (`@intentius/chant-lexicon-azure/generated/index`), whose
+ *     package ROOT is extracted from the specifier TEXT
+ *     ({@link bareSpecifierPackageRoot}, no resolution) and checked against
+ *     the identical set. A subpath is trusted because the code it names
+ *     belongs to a package the CLI already imported and executed to load that
+ *     lexicon's serializers/lint rules — reaching one of that package's own
+ *     modules by subpath instead of through the barrel names code the process
+ *     already trusts, not code the project controls.
  *  2. **chant-core's own executing tree** — the specifier is RESOLVED and the
  *     resulting path checked against {@link chantCoreRoot}. A text match is
  *     not enough here: `@intentius/chant` and `@intentius/chant-lexicon-evil`
@@ -2738,6 +2782,12 @@ function isChantOwnedHelperBinding(binding: ImportBinding, ctx: ResolveCtx): boo
  */
 function isTrustedExecutableBinding(binding: ImportBinding, ctx: ResolveCtx): boolean {
   if (activeLexiconPackage(binding.specifier, ctx.lexiconPackages) !== undefined) return true;
+  // chant #1995 — arm 1's subpath case: same allowlist, matched against the
+  // specifier's package ROOT (text only, see bareSpecifierPackageRoot) rather
+  // than the specifier itself, so `<activeLexiconPkg>/generated/index` is
+  // trusted exactly like the bare package import already is.
+  const subpathRoot = bareSpecifierPackageRoot(binding.specifier);
+  if (subpathRoot !== undefined && activeLexiconPackage(subpathRoot, ctx.lexiconPackages) !== undefined) return true;
   // Only a chant-shaped or project-relative specifier is worth resolving; any
   // other bare specifier is untrusted by definition, and resolving it to find
   // that out would cost the pathological cold `require.resolve` (chant#1020).