@intentius/chant 0.124.12 → 0.124.14

package/src/ts-loader.ts

@@ -0,0 +1,122 @@
+/**
+ * #3878 — TypeScript loading for the compiled CLI.
+ *
+ * An installed chant runs `dist/cli/main.js` with plain `node`, so chant's own
+ * modules need no loader. Everything else chant imports at run time still can
+ * be TypeScript: a project's `chant.config.ts` and source files, `*.op.ts`,
+ * policies and lint rules, and the lexicon packages, which ship `src/*.ts`.
+ * {@link ensureTypeScriptLoader} registers tsx for those, the first time one of
+ * them is about to be imported, so a command that imports none (`--version`,
+ * `run wave` on a project with no `chant.config.ts`) never loads tsx at all.
+ *
+ * {@link installCompiledCli} also points every resolution of chant's own
+ * source at the compiled file next to it. A lexicon or project file imports
+ * `@intentius/chant`, and the package exports resolve that to `src/*.ts`;
+ * without the redirect that import would load a second copy of core,
+ * transpiled, beside the one the CLI runs, with its own registries and
+ * classes.
+ *
+ * Run from source (the repository's `bin/chant` through tsx, vitest), this
+ * module is itself TypeScript, the TypeScript loader is already there, and
+ * both functions do nothing.
+ */
+
+import { existsSync } from "node:fs";
+import * as nodeModule from "node:module";
+import { dirname, join, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+// `module.registerHooks` (Node 22.15+, 24) is newer than the @types/node the
+// repository pins, so its shape is declared here.
+interface ResolveResult {
+  url: string;
+  format?: string | null;
+  shortCircuit?: boolean;
+}
+type NextResolve = (specifier: string, context?: unknown) => ResolveResult;
+const { createRequire, registerHooks } = nodeModule as unknown as {
+  createRequire: typeof nodeModule.createRequire;
+  registerHooks: (hooks: { resolve: (specifier: string, context: unknown, nextResolve: NextResolve) => ResolveResult }) => unknown;
+};
+
+interface CompiledCliState {
+  /** Whether tsx has been registered in this process. */
+  tsx: boolean;
+}
+
+const STATE = Symbol.for("chant.compiledCli");
+
+function compiledState(): CompiledCliState | undefined {
+  return (globalThis as { [STATE]?: CompiledCliState })[STATE];
+}
+
+/** True when this module runs as compiled JavaScript, from `<package>/dist`. */
+function runsCompiled(): boolean {
+  return import.meta.url.endsWith(".js");
+}
+
+/**
+ * Called once by the CLI's `main()`. Compiled, it records that TypeScript
+ * loads lazily and installs the `src/*.ts` to `dist/*.js` redirect; from
+ * source it does nothing.
+ */
+export function installCompiledCli(): void {
+  if (!runsCompiled() || compiledState()) return;
+  (globalThis as { [STATE]?: CompiledCliState })[STATE] = { tsx: false };
+
+  const distDir = dirname(fileURLToPath(import.meta.url));
+  const srcUrl = pathToFileURL(join(dirname(distDir), "src") + sep).href;
+  const distUrl = pathToFileURL(distDir + sep).href;
+  const compiled = new Map<string, string | null>();
+
+  registerHooks({
+    resolve(specifier, context, nextResolve) {
+      const result = nextResolve(specifier, context);
+      if (!result.url.startsWith(srcUrl)) return result;
+      const path = result.url.slice(srcUrl.length).replace(/[?#].*$/, "");
+      if (!path.endsWith(".ts") || path.endsWith(".d.ts")) return result;
+      let target = compiled.get(path);
+      if (target === undefined) {
+        const js = distUrl + path.slice(0, -3) + ".js";
+        target = existsSync(fileURLToPath(js)) ? js : null;
+        compiled.set(path, target);
+      }
+      return target === null ? result : { ...result, url: target, format: "module" };
+    },
+  });
+}
+
+/**
+ * Register tsx for the ESM and CommonJS loaders, once, before importing
+ * anything that may be TypeScript. A no-op from source, where tsx (or vitest)
+ * is already loading chant itself. Returns whether the compiled CLI's tsx
+ * registration covers this process, so a caller that registers its own
+ * CommonJS hook from source knows not to add a second one.
+ */
+export function ensureTypeScriptLoader(): boolean {
+  const state = compiledState();
+  if (!state) return false;
+  if (state.tsx) return true;
+  state.tsx = true;
+  const require = createRequire(import.meta.url);
+  (require("tsx/cjs/api") as { register: () => unknown }).register();
+  (require("tsx/esm/api") as { register: () => unknown }).register();
+  return true;
+}
+
+/**
+ * The source directory for a module of chant's own: `dirname` of `moduleUrl`
+ * from source, and the matching directory under `<package>/src` when the
+ * module runs from `<package>/dist`. The sandbox drivers hand chant's own
+ * modules to esbuild by path, and must name the TypeScript source the
+ * project's own `@intentius/chant/*` imports resolve to. String arithmetic
+ * only: no filesystem access, so it is safe inside a sandboxed child.
+ */
+export function chantSourceDir(moduleUrl: string): string {
+  const dir = dirname(fileURLToPath(moduleUrl));
+  if (!moduleUrl.endsWith(".js")) return dir;
+  const marker = `${sep}dist${sep}`;
+  const at = (dir + sep).lastIndexOf(marker);
+  if (at < 0) return dir;
+  return dir.slice(0, at) + `${sep}src` + dir.slice(at + marker.length - 1);
+}

package/src/workspace/chant-migrations/chud-lexicon-exit.ts

@@ -47,7 +47,7 @@
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join, posix } from "node:path";
 import yaml from "js-yaml";
-import answerSchema from "../point-answer.schema.json";
+import answerSchema from "../point-answer.schema.json" with { type: "json" };
 import { fileHash } from "../lineage-lock";
 import { DECISION_POINTS_SCHEMA_ID, POINT_INPUT_OUTPUT_NAMES, parsePoints, PointsError } from "../points";
 import type { ChantMigration, ChantMigrationContext, ChantMigrationPlan, NotMoved, PlanConflict, PlannedChange } from "../chant-migrations";

package/src/workspace/declaration.ts

@@ -19,7 +19,7 @@
 import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
-import schema from "./declaration.schema.json";
+import schema from "./declaration.schema.json" with { type: "json" };
 import { expandGlob } from "./glob";
 import { EXAMPLES_KIND, holdsChantProject } from "./kinds";
 import { parseJsonText, pointerToken, type TextLocation } from "./jsonc";

package/src/workspace/identity-gate-rule.ts

@@ -0,0 +1,109 @@
+/**
+ * The `identity.gates` rule as data and one pure function (#3862).
+ *
+ * A gate the declaration names under `identity.gates` passes only on an
+ * approval sealed by a signer at base, from the class the gate names when it
+ * names one (#3163, ws-080). chant's `gateAdmissionFrom` (`./identity.ts`)
+ * builds a {@link GateAdmissionRule} from what `scopeSource` reads and judges
+ * every approval with {@link admitApprover}. `@intentius/chant/gate-decision`
+ * builds the same rule from a bare clone at a base commit
+ * (`identityGateAdmissionAt`) and judges with the same function, so a tool
+ * counts approvals as chant's wave gate does.
+ *
+ * The module imports node:crypto through `./trust/gate-seal.ts` and nothing
+ * else: no zod, no ajv, no package loading, so it bundles small.
+ */
+
+import { GATE_SEAL_NAMESPACE, gateSealPayload, namespaceAllowed, verifySshSignatureWith, type SealedGateApproval } from "./trust/gate-seal";
+import type { Signer } from "./trust/trust-files";
+
+/** The core classes, in the order a principal's roles are tried; `human` holds no role and is the rest. */
+export const CORE_PRINCIPAL_CLASSES = ["human", "agent", "runner", "service"] as const;
+export type CorePrincipalClass = (typeof CORE_PRINCIPAL_CLASSES)[number];
+
+export interface PrincipalClass {
+  name: string;
+  /** One line saying who is in the class. */
+  description: string;
+  /** The role whose grant at base puts a principal in the class, or null for `human`, the rest. */
+  role: string | null;
+  /** `core`, or the pin (package name or path) that supplies the class. */
+  source: string;
+}
+
+export const CORE_CLASSES: readonly PrincipalClass[] = [
+  { name: "human", description: "a principal holding none of the roles of another class", role: null, source: "core" },
+  { name: "agent", description: "a principal holding the agent role, or a write naming an agent session", role: "agent", source: "core" },
+  { name: "runner", description: "a principal holding the runner role, such as a CI job's signing identity", role: "runner", source: "core" },
+  { name: "service", description: "a principal holding the service role", role: "service", source: "core" },
+];
+
+/** A class as the rule reads it: its name, and the role whose grant puts a principal in it (null for `human`). */
+export type ClassGrant = Pick<PrincipalClass, "name" | "role">;
+
+/** What an `identity.gates` gate is judged by, all read at base. */
+export interface GateAdmissionRule {
+  gate: string;
+  /** The class the approver must be in, or null for any signer. */
+  class: string | null;
+  /** The signers file at base: its path, whether it exists, and its signers. */
+  signers: { signersPath: string; active: boolean; signers: readonly Signer[] };
+  /** The role grants at base (`.chant/trust.json` `roles`). */
+  roles: Readonly<Record<string, readonly string[]>>;
+  /** Every class the rule knows, core first, then domain classes in pin order. */
+  classes: readonly ClassGrant[];
+  /**
+   * Why a class the rule does not know is unknown, for the refusal. Default
+   * "no pinned package supplies", which is what chant says once it has read
+   * every pin.
+   */
+  unknownClass?: string;
+}
+
+const normalise = (name: string): string => name.normalize("NFKC").trim().toLowerCase();
+
+/** Every class `principal`'s role grants put it in, in `classes` order: what `classesOf` in `./principal-classes.ts` answers. */
+export function grantedClasses(classes: readonly ClassGrant[], roles: Readonly<Record<string, readonly string[]>>, principal: string | null): string[] {
+  if (principal === null) return [];
+  const name = normalise(principal);
+  return classes.filter((c) => c.role !== null && (roles[c.role] ?? []).some((p) => normalise(p) === name)).map((c) => c.name);
+}
+
+/**
+ * Why `a` does not count toward the gate, or null when it does. An approval
+ * counts only when its seal verifies for its approver against the signers at
+ * base and, when the rule names a class, the role grants at base put the
+ * approver in it (`human`: in no other class). A class the rule does not
+ * know lets nothing through.
+ */
+export function admitApprover(rule: GateAdmissionRule, a: SealedGateApproval): string | null {
+  const { gate, signers } = rule;
+  const want = rule.class;
+  if (want !== null && !rule.classes.some((c) => c.name === want)) {
+    return `identity.gates.${gate} names the class ${want}, which ${rule.unknownClass ?? "no pinned package supplies"}, so no approval can show it is in that class (known classes: ${rule.classes.map((c) => c.name).join(", ")})`;
+  }
+  if (!signers.active) return `gate ${gate} needs a signed approval, and there is no signers file (${signers.signersPath}) at base to check one against`;
+  const seal = sealRefusal(gate, signers, a);
+  if (seal !== null) return seal;
+  if (want === null) return null;
+  const granted = grantedClasses(rule.classes, rule.roles, a.resolvedBy);
+  const inClass = want === "human" ? granted.length === 0 : granted.includes(want);
+  return inClass ? null : `${a.resolvedBy} is not in the class ${want} that gate ${gate} needs: no role grant at base puts them there`;
+}
+
+/** The seal step, worded as `checkGateSeal` (`./trust/seal.ts`) words it against an active signers file at base. */
+function sealRefusal(gate: string, signers: GateAdmissionRule["signers"], a: SealedGateApproval): string | null {
+  const what = `the approval of gate ${a.gate} by ${a.resolvedBy}`;
+  if (a.seal === undefined || a.seal === null) return `the approval by ${a.resolvedBy} is not signed; gate ${gate} needs chant approve --sign`;
+  const seal = a.seal as { signer?: unknown; signature?: unknown };
+  if (typeof seal !== "object" || Array.isArray(seal) || typeof seal.signer !== "string" || typeof seal.signature !== "string") {
+    return `the seal on ${what} is malformed: it needs signer and signature`;
+  }
+  if (normalise(seal.signer) !== normalise(a.resolvedBy)) return `the seal on ${what} is by ${seal.signer}, and its approver is ${a.resolvedBy || "empty"}`;
+  const where = `${signers.signersPath} at base`;
+  const listed = signers.signers.filter((s) => normalise(s.principal) === normalise(a.resolvedBy));
+  if (listed.length === 0) return `${a.resolvedBy} has no key in ${where}, so the seal can't count`;
+  const keys = listed.filter((s) => namespaceAllowed(s.namespaces, GATE_SEAL_NAMESPACE)).map((s) => Buffer.from(s.key.split(" ")[1] ?? "", "base64"));
+  const r = verifySshSignatureWith(seal.signature, gateSealPayload(a), GATE_SEAL_NAMESPACE, keys);
+  return r.ok ? null : `the seal does not verify for ${a.resolvedBy} against ${where}: ${r.reason}`;
+}

package/src/workspace/identity.ts

@@ -26,11 +26,12 @@
  */
 
 import type { Declaration, SignedGate } from "./declaration";
-import { classesOf, coreClassRegistry, principalClass, type ClassRegistry } from "./principal-classes";
+import { admitApprover } from "./identity-gate-rule";
+import { classesOf, coreClassRegistry, roleGrants, type ClassRegistry } from "./principal-classes";
 import type { ReasonCode } from "./reason-codes";
 import { normalisePrincipal } from "./records";
 import type { TrustPolicy } from "./trust/policy";
-import { checkGateSeal, type SealedGateApproval } from "./trust/seal";
+import type { SealedGateApproval } from "./trust/gate-seal";
 import { scopeSource } from "./write-scope";
 
 /** The forges a forge identity can name. */
@@ -152,27 +153,16 @@ export interface GateRuleSource extends IdentitySource {
  * approval counts only when its seal verifies for its approver against the
  * signers at base and, when the rule names a class, the approver's role
  * grants at base put it in that class. A class no pinned package supplies
- * lets nothing through.
+ * lets nothing through. The judge is {@link admitApprover}, which
+ * `@intentius/chant/gate-decision` also judges with (#3862). The policy is
+ * the one at base, never a returned work's copy.
  */
 export function gateAdmissionFrom(source: GateRuleSource, gate: string): GateAdmission | null {
   const requirement = source.declaration?.identity?.gates[gate];
   if (!requirement) return null;
   const { policy, classes } = source;
-  return {
-    requirement,
-    refuses(a) {
-      const want = requirement.class;
-      if (want !== null && classes.get(want) === undefined) {
-        return `identity.gates.${gate} names the class ${want}, which no pinned package supplies, so no approval can show it is in that class (known classes: ${classes.names().join(", ")})`;
-      }
-      if (!policy.active) return `gate ${gate} needs a signed approval, and there is no signers file (${policy.signersPath}) at base to check one against`;
-      const seal = checkGateSeal(policy, a);
-      if (seal.attested !== true) return a.seal === undefined || a.seal === null ? `the approval by ${a.resolvedBy} is not signed; gate ${gate} needs chant approve --sign` : seal.message;
-      if (want === null) return null;
-      const inClass = want === "human" ? principalClass(policy, a.resolvedBy, classes) === "human" : classesOf(classes, policy, a.resolvedBy).includes(want);
-      return inClass ? null : `${a.resolvedBy} is not in the class ${want} that gate ${gate} needs: no role grant at base puts them there`;
-    },
-  };
+  const rule = { gate, class: requirement.class, signers: policy, roles: roleGrants(policy), classes: classes.all() };
+  return { requirement, refuses: (a) => admitApprover(rule, a) };
 }
 
 /**

package/src/workspace/kinds.ts

@@ -20,7 +20,7 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
-import schema from "./workspace-kinds.schema.json";
+import schema from "./workspace-kinds.schema.json" with { type: "json" };
 import type { WorkspaceTree } from "./tree";
 import { joinPath, skippedDir } from "./tree";
 import { checkPinIntegrity } from "./pin-integrity";

package/src/workspace/lineage-migrations.ts

@@ -25,6 +25,7 @@ import { pathToFileURL } from "node:url";
 import { z } from "zod";
 import { LockError, type Lineage } from "./lineage-lock";
 import { compareVersions, formatVersion, parseVersion, satisfies, validateRange, VersionRangeError, type Version } from "./lineage-version";
+import { ensureTypeScriptLoader } from "../ts-loader";
 
 /** Where a template keeps its migrations, relative to the template's directory. */
 export const MIGRATIONS_DIR = ".chant/migrations";
@@ -281,6 +282,7 @@ export async function runMigration(m: LoadedMigration, opts: RunMigrationOptions
       mkdirSync(dirname(abs), { recursive: true });
       writeFileSync(abs, data);
     }
+    ensureTypeScriptLoader();
     const mod = (await import(pathToFileURL(file).href)) as { default?: unknown };
     if (typeof mod.default !== "function") throw new MigrationError(`${migration.id}: ${body.module} has no default export function`);
     await (mod.default as (ctx: { dir: string }) => unknown)({ dir: opts.dir });

package/src/workspace/points.ts

@@ -35,7 +35,7 @@
 import { createHash } from "node:crypto";
 import { createRequire } from "node:module";
 import { dirname, posix, relative, resolve, sep } from "node:path";
-import schema from "./decision-points.schema.json";
+import schema from "./decision-points.schema.json" with { type: "json" };
 import type { ReasonCode } from "./reason-codes";
 import type { RecordSource } from "./record-source";
 import type { LoadedRecordKind, ReadRecordsOptions, RecordEntry } from "./records";

package/src/workspace/principal-classes.ts

@@ -26,19 +26,17 @@ import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { join, posix } from "node:path";
 import { kindsExportTarget, pinnedPackageDir, type KindLoadProblem, type PinLike } from "./kinds";
-import { normalisePrincipal } from "./records";
-import schema from "./workspace-principals.schema.json";
+import schema from "./workspace-principals.schema.json" with { type: "json" };
 import type { TrustPolicy } from "./trust/policy";
 import { joinPath, type WorkspaceTree } from "./tree";
+import { CORE_CLASSES, CORE_PRINCIPAL_CLASSES, grantedClasses, type PrincipalClass } from "./identity-gate-rule";
 
 export const PRINCIPALS_SCHEMA_ID = schema.$id;
 
 /** The subpath a package publishes its principal classes at. */
 export const PRINCIPALS_SUBPATH = "./workspace-principals";
 
-/** The core classes, in the order a principal's roles are tried; `human` holds no role and is the rest. */
-export const CORE_PRINCIPAL_CLASSES = ["human", "agent", "runner", "service"] as const;
-export type CorePrincipalClass = (typeof CORE_PRINCIPAL_CLASSES)[number];
+export { CORE_CLASSES, CORE_PRINCIPAL_CLASSES, type CorePrincipalClass, type PrincipalClass } from "./identity-gate-rule";
 
 /** A class name: a core class, or a domain class a pinned package supplies. */
 export type PrincipalClassName = string;
@@ -46,23 +44,6 @@ export type PrincipalClassName = string;
 /** The grammar of a class name, as `workspace-principals.schema.json` and the declaration's writeScope keys say it. */
 export const CLASS_NAME = /^(?!x-)[a-z][a-z0-9-]{0,39}$/;
 
-export interface PrincipalClass {
-  name: string;
-  /** One line saying who is in the class. */
-  description: string;
-  /** The role whose grant at base puts a principal in the class, or null for `human`, the rest. */
-  role: string | null;
-  /** `core`, or the pin (package name or path) that supplies the class. */
-  source: string;
-}
-
-export const CORE_CLASSES: readonly PrincipalClass[] = [
-  { name: "human", description: "a principal holding none of the roles of another class", role: null, source: "core" },
-  { name: "agent", description: "a principal holding the agent role, or a write naming an agent session", role: "agent", source: "core" },
-  { name: "runner", description: "a principal holding the runner role, such as a CI job's signing identity", role: "runner", source: "core" },
-  { name: "service", description: "a principal holding the service role", role: "service", source: "core" },
-];
-
 const CORE_ROLES = new Set(CORE_CLASSES.map((c) => c.role).filter((r): r is string => r !== null));
 
 export interface ClassRegistry {
@@ -100,16 +81,10 @@ export function roleGrants(policy: TrustPolicy): Record<string, string[]> {
 /**
  * Every class `principal`'s role grants at base put it in, in registry order
  * (core first). Empty for a principal in no class but `human`, and for null.
- * Names compare as {@link normalisePrincipal} folds them.
+ * Names compare as `normalisePrincipal` (`./records.ts`) folds them.
  */
 export function classesOf(classes: ClassRegistry, policy: TrustPolicy, principal: string | null): string[] {
-  if (principal === null) return [];
-  const name = normalisePrincipal(principal);
-  const grants = roleGrants(policy);
-  return classes
-    .all()
-    .filter((c) => c.role !== null && (grants[c.role] ?? []).some((p) => normalisePrincipal(p) === name))
-    .map((c) => c.name);
+  return grantedClasses(classes.all(), roleGrants(policy), principal);
 }
 
 /** The class write scope judges `principal` as: the first class its grants put it in, or `human`. */