@intentius/chant 0.101.0 → 0.102.0

package/src/workspace/graph.schema.json

@@ -237,6 +237,10 @@
           "items": {
             "$ref": "#/$defs/record"
           }
+        },
+        "plantable": {
+          "description": "Added in contract 1 by #3146. Whether a host such as a studio's planter can plant the workspace as one box: exactly one member's box block declares services, read from the declaration at the revision read. Not a check: a records-only or infra workspace is valid and simply not plantable.",
+          "$ref": "#/$defs/plantable"
         }
       }
     },
@@ -372,6 +376,43 @@
               "description": "The nested workspace's links, naming its members as the nested side does."
             }
           }
+        },
+        "box": {
+          "description": "Added in contract 1 by #3146. The factory and listing the member's box block declares (ws-077), read from the declaration at the revision read, so --at gives them as they were. null when the box declares neither, or the member has no box block; the rest of the box block is in chant workspace status --json.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "factory",
+                "listing"
+              ],
+              "properties": {
+                "factory": {
+                  "oneOf": [
+                    {
+                      "type": "null"
+                    },
+                    {
+                      "$ref": "#/$defs/factory"
+                    }
+                  ]
+                },
+                "listing": {
+                  "oneOf": [
+                    {
+                      "type": "null"
+                    },
+                    {
+                      "$ref": "#/$defs/listing"
+                    }
+                  ]
+                }
+              }
+            }
+          ]
         }
       },
       "if": {
@@ -1019,6 +1060,212 @@
           }
         }
       }
+    },
+    "plantable": {
+      "type": "object",
+      "required": [
+        "plantable",
+        "box",
+        "reason"
+      ],
+      "properties": {
+        "plantable": {
+          "type": "boolean"
+        },
+        "box": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The member whose box block declares services, or null when the workspace isn't plantable."
+        },
+        "reason": {
+          "description": "Why the workspace isn't plantable, or null when it is.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "code",
+                "message"
+              ],
+              "properties": {
+                "code": {
+                  "enum": [
+                    "box-none",
+                    "box-several"
+                  ]
+                },
+                "message": {
+                  "type": "string"
+                }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "factory": {
+      "type": "object",
+      "required": [
+        "builds",
+        "check",
+        "checks",
+        "builders",
+        "publish"
+      ],
+      "properties": {
+        "builds": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string"
+          },
+          "description": "The members the factory builds, in declaration order. A work item a person asks for constrains member:<the first>."
+        },
+        "check": {
+          "description": "The verdict command, run from the workspace root, and what it is; null when none is declared.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "run",
+                "kind"
+              ],
+              "properties": {
+                "run": {
+                  "type": "string"
+                },
+                "kind": {
+                  "enum": [
+                    "test",
+                    "build",
+                    "lint",
+                    "plan",
+                    "conformance"
+                  ]
+                }
+              }
+            }
+          ]
+        },
+        "checks": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Where a work item's builder writes its check, from the workspace root, or null for the orchestrator's choice."
+        },
+        "builders": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The member that declares the builder agents, or null."
+        },
+        "publish": {
+          "description": "Where a finished build is published, or null when the factory doesn't publish past the box.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "forge",
+                "repo",
+                "base",
+                "branchPrefix",
+                "head"
+              ],
+              "properties": {
+                "forge": {
+                  "const": "github"
+                },
+                "repo": {
+                  "type": "string",
+                  "description": "owner/name: where the pull request is opened."
+                },
+                "base": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "The branch the pull request targets, or null for the repository's default branch."
+                },
+                "branchPrefix": {
+                  "type": "string",
+                  "description": "What the published branch's name starts with, before the work item's id. chant/work/ unless declared."
+                },
+                "head": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "owner/name of the fork the branch is pushed to, or null to push to repo."
+                }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "listing": {
+      "type": "object",
+      "required": [
+        "published",
+        "title",
+        "line",
+        "cover"
+      ],
+      "properties": {
+        "published": {
+          "type": "boolean",
+          "description": "Whether the box is listed; true unless declared otherwise."
+        },
+        "title": {
+          "type": "string",
+          "description": "Empty when not declared: a reader shows a name of its own."
+        },
+        "line": {
+          "type": "string",
+          "description": "Empty when not declared."
+        },
+        "cover": {
+          "description": "The cover image, or null when none is declared.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "path",
+                "sha256"
+              ],
+              "properties": {
+                "path": {
+                  "type": "string",
+                  "description": "From the workspace root."
+                },
+                "sha256": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "pattern": "^[0-9a-f]{64}$",
+                  "description": "The sha256 of the file's bytes at the revision read, or null when it can't be read."
+                }
+              }
+            }
+          ]
+        }
+      }
     }
   }
 }

package/src/workspace/identity.test.ts

@@ -0,0 +1,196 @@
+/**
+ * #3163, ws-080: person-attributed records and gate approvals rest on a forge
+ * identity or a signer key, and a gate the declaration names passes only on a
+ * signed approval from its class.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterEach, describe, expect, test } from "vitest";
+import { parseDeclaration, type Declaration } from "./declaration";
+import { forgePrincipal, gateAdmissionFrom, identify, IdentityError, parseForgeIdentity, refuseUnidentified } from "./identity";
+import { createClassRegistry, coreClassRegistry } from "./principal-classes";
+import { reviewRecord } from "./records-write";
+import { answerPoint } from "./decide";
+import { gatesInLedger } from "./status-gates";
+import { emptyPolicy, type TrustPolicy } from "./trust/policy";
+import { sealGateApproval } from "./trust/seal";
+import { hasSshKeygen, TestRepo, type Key } from "./trust/test-repo";
+import { evaluateGate, memoryGateLedgerPort } from "../op/gate";
+import type { GateResolutionRecord, PendingGateRecord } from "../lifecycle/gate-ledger";
+
+const decl = (identity: unknown): Declaration =>
+  parseDeclaration(JSON.stringify({ name: "acme", schema: 1, members: [], identity }), "chant.workspace.json", "0.102.0");
+
+const policyWith = (signers: { principal: string; key: string }[], roles: Record<string, string[]> = {}): TrustPolicy => ({
+  ...emptyPolicy("0".repeat(40)),
+  active: true,
+  signers: signers.map((s, i) => ({ ...s, line: i + 1 })),
+  roles,
+});
+
+const repos: TestRepo[] = [];
+afterEach(() => {
+  while (repos.length) repos.pop()!.cleanup();
+});
+
+describe("forge identities", () => {
+  test("github and gitlab name their own host; forgejo and gitea name one", () => {
+    expect(parseForgeIdentity("github:Alice")).toEqual({ forge: "github", host: "github.com", login: "alice" });
+    expect(parseForgeIdentity("gitlab:a.b_c")).toEqual({ forge: "gitlab", host: "gitlab.com", login: "a.b_c" });
+    expect(parseForgeIdentity("forgejo@codeberg.org:bob")).toEqual({ forge: "forgejo", host: "codeberg.org", login: "bob" });
+    expect(parseForgeIdentity("github@ghe.example.com:carol")).toEqual({ forge: "github", host: "ghe.example.com", login: "carol" });
+    expect(parseForgeIdentity("forgejo:bob")).toBeNull();
+    expect(parseForgeIdentity("alice")).toBeNull();
+    expect(parseForgeIdentity("alice@example.com")).toBeNull();
+    expect(parseForgeIdentity("github:")).toBeNull();
+    expect(parseForgeIdentity("bitbucket:alice")).toBeNull();
+    expect(forgePrincipal({ forge: "github", host: "github.com", login: "alice" })).toBe("github:alice");
+    expect(forgePrincipal({ forge: "forgejo", host: "codeberg.org", login: "bob" })).toBe("forgejo@codeberg.org:bob");
+  });
+
+  test("a principal is a signer, a forge identity, a role holder or a name", () => {
+    const policy = policyWith([{ principal: "github:alice", key: "ssh-ed25519 AAAA" }, { principal: "dana@example.test", key: "ssh-ed25519 BBBB" }], { runner: ["ci-bot"] });
+    expect(identify("GitHub:Alice", policy).form).toBe("signer");
+    expect(identify("dana@example.test", policy).form).toBe("signer");
+    expect(identify("github:bob", policy).form).toBe("forge");
+    expect(identify("ci-bot", policy).form).toBe("role");
+    expect(identify("alex", policy).form).toBe("name");
+    const d = parseDeclaration(
+      JSON.stringify({ name: "acme", schema: 1, members: [{ name: "app", dir: "app", kind: "chant" }], agents: [{ name: "builder", member: "app", principals: ["builder-bot"] }] }),
+      "chant.workspace.json",
+      "0.102.0",
+    );
+    expect(identify("builder-bot", emptyPolicy(null), d).form).toBe("role");
+  });
+});
+
+describe("identity.attribution", () => {
+  test("parses, and defaults to any", () => {
+    expect(decl({}).identity).toEqual({ attribution: "any", gates: {} });
+    expect(decl({ attribution: "identified", gates: { ship: { class: "operator" }, rollback: {} } }).identity).toEqual({
+      attribution: "identified",
+      gates: {
+        ship: { gate: "ship", class: "operator", pointer: "/identity/gates/ship" },
+        rollback: { gate: "rollback", class: null, pointer: "/identity/gates/rollback" },
+      },
+    });
+    expect(() => decl({ attribution: "verified" })).toThrow();
+    expect(() => decl({ gates: { ship: { by: "x" } } })).toThrow();
+  });
+
+  test("identified refuses a bare name and takes a forge identity or a signer", () => {
+    const source = { declaration: decl({ attribution: "identified" }), policy: policyWith([{ principal: "dana@example.test", key: "ssh-ed25519 AAAA" }]) };
+    expect(() => refuseUnidentified(source, ["github:alice", "dana@example.test"], "--by")).not.toThrow();
+    expect(() => refuseUnidentified(source, ["github:alice", "alex"], "--by")).toThrow(IdentityError);
+    // any, or no identity block, keeps every name: hud's roster names still work there.
+    expect(() => refuseUnidentified({ ...source, declaration: decl({}) }, ["alex"], "--by")).not.toThrow();
+    expect(() => refuseUnidentified({ ...source, declaration: null }, ["alex"], "--by")).not.toThrow();
+  });
+
+  test.skipIf(!hasSshKeygen)("records review and points answer refuse a roster name under identified at base", async () => {
+    const r = new TestRepo("identity-review");
+    repos.push(r);
+    const DECISIONS = join(import.meta.dirname, "..", "..", "..", "..", "docs", "design", "decisions");
+    r.write("decisions/decision.kind.mjs", readFileSync(join(DECISIONS, "decision.kind.mjs"), "utf-8"));
+    r.write("decisions/decision.schema.json", readFileSync(join(DECISIONS, "decision.schema.json"), "utf-8"));
+    r.write("decisions/ws-003-seal-scope.md", readFileSync(join(DECISIONS, "ws-003-seal-scope.md"), "utf-8"));
+    r.write("chant.workspace.json", JSON.stringify({ name: "acme", schema: 1, members: [], identity: { attribution: "identified" } }));
+    r.commit("base");
+    r.git(["checkout", "-q", "-b", "change"]);
+    const kind = "decisions/decision.kind.mjs";
+    const refused = await reviewRecord({ kind, id: "ws-003", verdict: "agree", by: "alex", cwd: r.dir, on: "2026-10-03", dryRun: true });
+    expect("error" in refused && refused.error.code).toBe("principal-unidentified");
+    const taken = await reviewRecord({ kind, id: "ws-003", verdict: "agree", by: "github:alex", cwd: r.dir, on: "2026-10-03", dryRun: true });
+    expect("error" in taken ? taken.error : null).toBeNull();
+    const answer = await answerPoint({ id: "P-1", answer: "yes", by: ["alex"], cwd: r.dir });
+    expect("error" in answer && answer.error.code).toBe("principal-unidentified");
+  });
+});
+
+describe.skipIf(!hasSshKeygen)("identity.gates", () => {
+  function keys(): { r: TestRepo; alice: Key; bob: Key; mallory: Key } {
+    const r = new TestRepo("identity-gates");
+    repos.push(r);
+    return { r, alice: r.key("alice"), bob: r.key("bob"), mallory: r.key("mallory") };
+  }
+
+  const approval = (resolvedBy: string, extra: Partial<GateResolutionRecord> = {}): GateResolutionRecord => ({
+    version: 1,
+    op: "web",
+    gate: "ship",
+    environment: "prod",
+    planDigest: "sha256:" + "a".repeat(64),
+    resolvedBy,
+    timestamp: "2026-10-03T12:00:00.000Z",
+    ...extra,
+  });
+  const signed = (key: Key, a: GateResolutionRecord): GateResolutionRecord => ({ ...a, seal: sealGateApproval(key.file, a) });
+
+  test("counts only an approval sealed by a listed signer in the class", () => {
+    const { alice, bob, mallory } = keys();
+    const policy = policyWith(
+      [
+        { principal: "github:alice", key: alice.pub },
+        { principal: "github:bob", key: bob.pub },
+      ],
+      { operator: ["github:alice"] },
+    );
+    const classes = createClassRegistry([{ name: "operator", description: "operators", role: "operator", source: "plugins/ops" }]);
+    const rule = gateAdmissionFrom({ declaration: decl({ gates: { ship: { class: "operator" } } }), policy, classes }, "ship")!;
+    expect(rule.requirement.class).toBe("operator");
+    expect(gateAdmissionFrom({ declaration: decl({ gates: { ship: {} } }), policy, classes }, "rollout")).toBeNull();
+
+    expect(rule.refuses(signed(alice, approval("github:alice")))).toBeNull();
+    // A hud roster name or an unsigned forge identity can't clear it.
+    expect(rule.refuses(approval("alex"))).toMatch(/not signed/);
+    expect(rule.refuses(approval("github:alice"))).toMatch(/not signed/);
+    // Signed by a listed signer outside the class.
+    expect(rule.refuses(signed(bob, approval("github:bob")))).toMatch(/not in the class operator/);
+    // Someone else's key under alice's name.
+    expect(rule.refuses(signed(mallory, approval("github:alice")))).toMatch(/does not verify/);
+    // A seal over another plan doesn't carry over.
+    const moved = { ...signed(alice, approval("github:alice")), planDigest: "sha256:" + "b".repeat(64) };
+    expect(rule.refuses(moved)).toMatch(/does not verify/);
+
+    // Any listed signer, when the rule names no class.
+    const anySigner = gateAdmissionFrom({ declaration: decl({ gates: { ship: {} } }), policy, classes }, "ship")!;
+    expect(anySigner.refuses(signed(bob, approval("github:bob")))).toBeNull();
+    // A class no pinned package supplies lets nothing through.
+    const unknown = gateAdmissionFrom({ declaration: decl({ gates: { ship: { class: "operator" } } }), policy, classes: coreClassRegistry() }, "ship")!;
+    expect(unknown.refuses(signed(alice, approval("github:alice")))).toMatch(/no pinned package supplies/);
+  });
+
+  test("a run and workspace status leave out approvals the rule refuses", async () => {
+    const { alice } = keys();
+    const policy = policyWith([{ principal: "github:alice", key: alice.pub }]);
+    const rule = gateAdmissionFrom({ declaration: decl({ gates: { ship: {} } }), policy, classes: coreClassRegistry() }, "ship")!;
+    const pending: PendingGateRecord = {
+      version: 1,
+      kind: "pending",
+      op: "web",
+      gate: "ship",
+      environment: "prod",
+      planDigest: "sha256:" + "a".repeat(64),
+      timestamp: "2026-10-03T11:00:00.000Z",
+      expiresAt: "2026-10-10T11:00:00.000Z",
+    };
+    const input = { op: "web", gate: "ship", environment: "prod", planDigest: pending.planDigest, now: "2026-10-03T13:00:00.000Z" };
+
+    const roster = memoryGateLedgerPort({ pending: [pending], resolutions: [approval("alex")] });
+    expect((await evaluateGate(roster, input)).satisfied).toBe(true);
+    expect((await evaluateGate({ ...roster, approvalRule: async () => rule }, input)).satisfied).toBe(false);
+    const sealed = memoryGateLedgerPort({ pending: [pending], resolutions: [approval("alex"), signed(alice, approval("github:alice"))] });
+    const check = await evaluateGate({ ...sealed, approvalRule: async () => rule }, input);
+    expect(check.satisfied && check.resolution.resolvedBy).toBe("github:alice");
+
+    const ledger = [pending, approval("alex")].map((l) => JSON.stringify(l)).join("\n");
+    const open = gatesInLedger("web", ledger, ["prod"], "2026-10-03T13:00:00.000Z", (g) => (g === "ship" ? rule : null)).gates[0];
+    expect(open.state).toBe("pending");
+    expect(open.signed).toEqual({ class: null });
+    expect(open.approve).toMatch(/--sign$/);
+    const plain = gatesInLedger("web", ledger, ["prod"], "2026-10-03T13:00:00.000Z").gates[0];
+    expect(plain.state).toBe("approved");
+    expect(plain.signed).toBeNull();
+  });
+});

package/src/workspace/identity.ts

@@ -0,0 +1,186 @@
+/**
+ * Who a person-attributed record or gate approval names (#3163, ws-080).
+ *
+ * chant never authenticates a person (ws-052): hud, studio or behold signs a
+ * person in and maps the session to one of the identities below, then passes
+ * it to chant's write commands (`--by`, `--actor`). chant records what it is
+ * given and says which form it is:
+ *
+ * - `signer`: a principal `.chant/allowed_signers` lists at base. A seal made
+ *   with that principal's key (`--sign`) attests it.
+ * - `forge`: a forge identity, `github:<login>`, `gitlab:<login>`, or
+ *   `<forge>@<host>:<login>` (forgejo, gitea, or a self-hosted github or
+ *   gitlab). The surface that signed the person in vouches for it; nothing
+ *   here checks it, and only a seal verified against the signers at base
+ *   attests it. The signers file and the role grants name people this way, so
+ *   one string is the person in the record, the key list and the classes.
+ * - `role`: a principal holding the agent, runner or service role at base, or
+ *   listed by a declared agent session: not a person, and named by a grant an
+ *   admin controls.
+ * - `name`: anything else, such as a hud roster name or `$USER`.
+ *
+ * The declaration's `identity` block, read at base, turns this into rules:
+ * `attribution: "identified"` refuses a `name` on every person-attributed
+ * write, and `gates.<gate>` lets a gate of that name pass only on an approval
+ * sealed by a signer, from a class when it names one.
+ */
+
+import type { Declaration, SignedGate } from "./declaration";
+import { classesOf, coreClassRegistry, principalClass, 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 { scopeSource } from "./write-scope";
+
+/** The forges a forge identity can name. */
+export const FORGES = ["github", "gitlab", "forgejo", "gitea"] as const;
+export type Forge = (typeof FORGES)[number];
+
+/** The host a forge identity means when it names none. Forgejo and gitea have no default: name the host. */
+const DEFAULT_HOST: Record<Forge, string | null> = { github: "github.com", gitlab: "gitlab.com", forgejo: null, gitea: null };
+
+/** A person's account on a forge. */
+export interface ForgeIdentity {
+  forge: Forge;
+  /** Lower-cased, such as `github.com` or `codeberg.org`. */
+  host: string;
+  /** Lower-cased: the forges compare logins without case. */
+  login: string;
+}
+
+const LABEL = "[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?";
+const FORGE_PRINCIPAL = new RegExp(`^(${FORGES.join("|")})(?:@(${LABEL}(?:\\.${LABEL})+))?:([a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9_])?)$`);
+
+/**
+ * Read `principal` as a forge identity, or null when it is not one. Case and
+ * surrounding space are folded as {@link normalisePrincipal} folds them.
+ */
+export function parseForgeIdentity(principal: string): ForgeIdentity | null {
+  const m = FORGE_PRINCIPAL.exec(normalisePrincipal(principal));
+  if (!m) return null;
+  const forge = m[1] as Forge;
+  const host = m[2] ?? DEFAULT_HOST[forge];
+  if (host === null) return null;
+  return { forge, host, login: m[3] };
+}
+
+/** The principal string of a forge identity: `<forge>:<login>` on the forge's default host, else `<forge>@<host>:<login>`. */
+export function forgePrincipal(id: ForgeIdentity): string {
+  return id.host === DEFAULT_HOST[id.forge] ? `${id.forge}:${id.login}` : `${id.forge}@${id.host}:${id.login}`;
+}
+
+export type IdentityForm = "signer" | "forge" | "role" | "name";
+
+export interface Identified {
+  principal: string;
+  form: IdentityForm;
+  /** Set whenever the principal reads as a forge identity, whatever its form. */
+  forge: ForgeIdentity | null;
+}
+
+const NON_PERSON_CLASSES = new Set(["agent", "runner", "service"]);
+
+/**
+ * What `principal` is, under the policy and declaration read at base. A
+ * principal the signers file lists is a `signer` even when it is also a
+ * forge identity, since a seal can attest it.
+ */
+export function identify(principal: string, policy: TrustPolicy, declaration: Declaration | null = null): Identified {
+  const name = normalisePrincipal(principal);
+  const forge = parseForgeIdentity(principal);
+  if (policy.active && policy.signers.some((s) => normalisePrincipal(s.principal) === name)) return { principal, form: "signer", forge };
+  if (forge) return { principal, form: "forge", forge };
+  const session = (declaration?.agents ?? []).some((a) => a.principals.some((p) => normalisePrincipal(p) === name));
+  if (session || classesOf(coreClassRegistry(), policy, principal).some((c) => NON_PERSON_CLASSES.has(c))) return { principal, form: "role", forge: null };
+  return { principal, form: "name", forge: null };
+}
+
+/** Why a write naming a person was refused. Closed. */
+export const IDENTITY_CODES = ["principal-unidentified"] as const satisfies readonly ReasonCode[];
+export type IdentityCode = (typeof IDENTITY_CODES)[number];
+
+export class IdentityError extends Error {
+  readonly code: IdentityCode = "principal-unidentified";
+  constructor(message: string) {
+    super(message);
+    this.name = "IdentityError";
+  }
+}
+
+/** What {@link refuseUnidentified} reads: the declaration and policy at base, as `scopeSource` gives them. */
+export interface IdentitySource {
+  declaration: Declaration | null;
+  policy: TrustPolicy;
+}
+
+/**
+ * Refuse a person-attributed write that names someone by a bare name, when
+ * the declaration at base sets `identity.attribution` to `identified`.
+ * `flag` names where the name came from (`--by`, `--actor`). A write in a
+ * declared agent session (`CHANT_AGENT`) names the session, not a person,
+ * and is not judged here. Throws an {@link IdentityError}.
+ */
+export function refuseUnidentified(source: IdentitySource, names: readonly string[], flag: string, opts: { agent?: string | null } = {}): void {
+  if (source.declaration?.identity?.attribution !== "identified") return;
+  if (opts.agent !== undefined && opts.agent !== null && source.declaration.agents.some((a) => a.name === opts.agent)) return;
+  for (const name of names) {
+    if (identify(name, source.policy, source.declaration).form !== "name") continue;
+    throw new IdentityError(
+      `${flag} ${JSON.stringify(name)} names no identity the workspace can check: chant.workspace.json at base sets identity.attribution to identified, so a person is named by a forge identity (github:<login>, gitlab:<login>, or <forge>@<host>:<login>) or by a principal ${source.policy.signersPath} lists at base`,
+    );
+  }
+}
+
+/** A gate approval as the rule judges it: the resolution line's own fields. */
+export type GateApprovalLike = SealedGateApproval;
+
+/** A gate the declaration names in `identity.gates`, and the judge for its approvals. */
+export interface GateAdmission {
+  requirement: SignedGate;
+  /** Why `approval` doesn't count toward the gate, or null when it does. */
+  refuses(approval: GateApprovalLike): string | null;
+}
+
+/** What {@link gateAdmissionFrom} reads: the declaration, policy and classes at base, as `scopeSource` gives them. */
+export interface GateRuleSource extends IdentitySource {
+  classes: ClassRegistry;
+}
+
+/**
+ * The rule for `gate`, or null when the declaration at base names none. An
+ * 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.
+ */
+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`;
+    },
+  };
+}
+
+/**
+ * The rule for `gate` in the workspace holding `cwd`, read at base (the
+ * target branch tip), or null when there is no declaration or it names none.
+ * What a run, `chant approve` and `workspace status` ask before counting an
+ * approval.
+ */
+export function gateAdmission(cwd: string, gate: string): GateAdmission | null {
+  return gateAdmissionFrom(scopeSource(cwd), gate);
+}