@intentius/chant 0.124.11 → 0.124.13

package/src/meta/lexicon-typescript-import.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from "vitest";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Lexicon source takes the TypeScript compiler API from
+ * `@intentius/chant/lint/typescript`, never from `typescript` (chant #3864).
+ *
+ * A bare `typescript` import in a published lexicon resolves to the project's
+ * copy. On TypeScript 7 that copy has no JS compiler API, so every sql lint
+ * rule threw `ts.isImportDeclaration is not a function` and `chant graph`
+ * refused the project. Core parses with its own 5.x, and a rule has to test
+ * nodes with that same module. Tests are exempt: they run in this repo, where
+ * `typescript` is 5.x.
+ */
+const repoRoot = fileURLToPath(new URL("../../../../", import.meta.url));
+const lexiconsDir = join(repoRoot, "lexicons");
+
+function sourceFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const name of readdirSync(dir)) {
+    const path = join(dir, name);
+    if (statSync(path).isDirectory()) out.push(...sourceFiles(path));
+    else if (/\.(ts|mts|js|mjs)$/.test(name) && !/\.test\.ts$/.test(name)) out.push(path);
+  }
+  return out;
+}
+
+const BARE_TYPESCRIPT = /^\s*(import|export)\b[^;]*?\bfrom\s+["']typescript["']|\b(require|import)\(\s*["']typescript["']\s*\)/m;
+
+describe("lexicon source imports TypeScript through chant (#3864)", () => {
+  test("no lexicon src file imports `typescript` directly", () => {
+    const offenders = readdirSync(lexiconsDir)
+      .map((name) => join(lexiconsDir, name, "src"))
+      .filter((dir) => statSync(dir, { throwIfNoEntry: false })?.isDirectory())
+      .flatMap(sourceFiles)
+      .filter((file) => BARE_TYPESCRIPT.test(readFileSync(file, "utf-8")))
+      .map((file) => relative(repoRoot, file));
+    expect(offenders, 'import { ts } from "@intentius/chant/lint/typescript" instead').toEqual([]);
+  });
+});

package/src/op/gate-review.ts

@@ -70,23 +70,9 @@ export function bothRules(a: GateApprovalRule | null, b: GateApprovalRule | null
 
 // ── pr-review ─────────────────────────────────────────────────────────────
 
-/** The digests each wave planned at one commit, recorded for a review of it to approve. */
-export interface HeadPlans {
-  version: 1;
-  /** The Op waves spec's name. */
-  name: string;
-  /** The commit the waves were planned at: a pull request's head. */
-  head: string;
-  timestamp: string;
-  waves: Array<{ wave: number; name: string; digest: string }>;
-}
+// The record and its reader live apart, so a bundle can import them without git (#3865).
+export { HEAD_PLANS_DIR, headPlansPath, type HeadPlans } from "../lifecycle/wave-plans";
 
-/** Where {@link HeadPlans} for `head` live on `chant/lifecycle`: `_wave-plans/<name>/<head>.json`. */
-export const HEAD_PLANS_DIR = "_wave-plans";
-
-export function headPlansPath(name: string, head: string): { dir: string; file: string } {
-  return { dir: `${HEAD_PLANS_DIR}/${name}`, file: `${head}.json` };
-}
 
 /** The merged pull request's review, as a `pr-review` gate reads it. */
 export interface MergedReview {

package/src/op/op-waves-point.test.ts

@@ -254,6 +254,7 @@ describe("a wave gate that asks a decision point (#3836)", () => {
       members,
       description: "wave 1 of 1: vpc, nat",
       neverOverMcp: true,
+      approvalMode: "ledger",
       answer: { point: "prod-apply" },
     });
     expect(waiting.decision?.pendingFact).toMatchObject({ commit: "c".repeat(40), neverOverMcp: true });

package/src/op/op-waves-run.ts

@@ -130,7 +130,7 @@ export interface OpWavePlansFile {
 /** Pending-fact keys chant writes itself, which a plans file's `pending` may not set (#3821). */
 export const OP_WAVE_PENDING_RESERVED = [
   "version", "kind", "op", "gate", "timestamp", "expiresAt", "planDigest", "runId", "url", "resume",
-  "environment", "origin", "neverOverMcp", "approval", "answer",
+  "environment", "origin", "neverOverMcp", "approval", "approvalMode", "answer",
 ] as const;
 
 /** What chant writes to `{runs}` for a wave-level command or a hook (#3762). */
@@ -1068,7 +1068,7 @@ async function settleOtherGate(ctx: WaveContext, hold: OtherGateHold): Promise<O
     description: hold.request.description ?? `wave ${k} (${wave.name}) of ${spec.name} is held on it by ${hold.label}`,
     now,
     // #3839: the wave a hold belongs to, as a field, whatever the hook's own description says.
-    fields: { ...hold.request.pending, wave: { number: k, name: wave.name, op: spec.name } },
+    fields: { ...hold.request.pending, approvalMode: rules.approval, wave: { number: k, name: wave.name, op: spec.name } },
     ...(neverOverMcp ? { neverOverMcp: true } : {}),
   });
   const base = { op, gate: hold.request.gate, digest: hold.request.digest, hook: hold.label };
@@ -1633,7 +1633,8 @@ async function settleGate(options: RunOpWaveOptions, ctx: WaveContext, decision:
     description: (typeof decision.pending?.description === "string" ? decision.pending.description : undefined) ?? `wave ${k} (${wave.name}): ${members.length} run${members.length === 1 ? "" : "s"}, gate ${policy}, approval ${approval}${held}`,
     now,
     ...(spent ? { spent } : {}),
-    ...(decision.pending ? { fields: decision.pending } : {}),
+    // #3861: the approval mode the wave asked under, for readers deciding which approvals count.
+    fields: { ...decision.pending, approvalMode: approval },
     ...(decision.neverOverMcp ? { neverOverMcp: true } : {}),
   });
   if (check.satisfied) {
@@ -1697,7 +1698,7 @@ async function settlePointGate(options: RunOpWaveOptions, ctx: WaveContext, deci
     planDigest: digest,
     ...(options.now ? { now: options.now } : {}),
     // #3863: the plans file's pending fields and the spec's neverOverMcp, as settleGate passes them.
-    ...(decision.pending ? { fields: decision.pending } : {}),
+    fields: { ...decision.pending, approvalMode: decision.approval },
     ...(decision.neverOverMcp ? { neverOverMcp: true } : {}),
   });
   if (check.satisfied) {
@@ -2088,17 +2089,10 @@ async function approveByReview(
 }
 
 async function readHeadPlans(name: string, head: string, cwd: string): Promise<HeadPlans | null> {
-  const { readBlobFromPath, requireLifecycleLedger } = await import("../lifecycle/git");
-  const { headPlansPath } = await import("./gate-review");
+  const { gitLedgerReadPort, requireLifecycleLedger } = await import("../lifecycle/git");
+  const { readHeadPlans: read } = await import("../lifecycle/wave-plans");
   await requireLifecycleLedger({ cwd });
-  const { dir, file } = headPlansPath(name, head);
-  const text = await readBlobFromPath(dir, file, { cwd });
-  if (!text) return null;
-  try {
-    return JSON.parse(text) as HeadPlans;
-  } catch {
-    return null;
-  }
+  return read(gitLedgerReadPort({ cwd }), name, head);
 }
 
 export interface RecordHeadPlansOptions {

package/src/op/op-waves.test.ts

@@ -739,8 +739,22 @@ describe("a product's wave gate moved onto the waves (#3821)", () => {
     const result = await runOpWave({ spec: tg, specFile: "waves.json", wave: 1, cwd: h.cwd, exec: h.exec, show: () => ({ sha: "b".repeat(40), text: JSON.stringify({ ...tg, neverOverMcp: true }) }), gates });
     expect(result.exitCode).toBe(3);
     expect(gates.appended[0]).toMatchObject({ commit: "c".repeat(40), members, description: "wave 1 of 3: vpc, dns, nat", neverOverMcp: true, gate: "wave-1", op: "tf-apply" });
+    // #3861: the approval mode the wave asked under, and a plans file may not set it.
+    expect(gates.appended[0]).toMatchObject({ approvalMode: "ledger" });
     h.done();
 
+    const mode = harness(plans, { pending: { approvalMode: "sealed" } });
+    await expect(runOpWave({ spec: tg, specFile: "waves.json", wave: 1, cwd: mode.cwd, exec: mode.exec, show: mode.show, gates: memoryGateLedgerPort() })).rejects.toThrow(/sets approvalMode, which chant writes itself/);
+    mode.done();
+
+    // A sealed spec at base records "sealed".
+    const sealedSpec: OpWavesSpec = { ...tg, waves: [{ ...tg.waves[0]!, approval: "sealed" }] };
+    const sh = harness(plans, {}, sealedSpec);
+    const sealedGates = memoryGateLedgerPort();
+    await runOpWave({ spec: sealedSpec, specFile: "waves.json", wave: 1, cwd: sh.cwd, exec: sh.exec, show: () => ({ sha: "b".repeat(40), text: JSON.stringify(sealedSpec) }), gates: sealedGates });
+    expect(sealedGates.appended[0]).toMatchObject({ approvalMode: "sealed" });
+    sh.done();
+
     const bad = harness(plans, { pending: { gate: "other" } });
     await expect(runOpWave({ spec: tg, specFile: "waves.json", wave: 1, cwd: bad.cwd, exec: bad.exec, show: bad.show, gates: memoryGateLedgerPort() })).rejects.toThrow(/sets gate, which chant writes itself/);
     bad.done();

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/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 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`. */