@intentius/chant 0.124.46 → 0.124.49

package/src/pr-loop.ts

@@ -49,6 +49,7 @@
 
 import type { ChangeSetAction, ChangeSetDocument } from "./change-set";
 import type { PrRequireOutcome } from "./pr-requires";
+import { renderMigrationLines, type PrMigrationFile } from "./pr-migrations";
 import { GITHUB_COMMENT_LIMIT, groupChangeSet, renderPlanSummaryMarkdown } from "./plan-summary";
 
 /** The schema a pull-request report names in `$schema`. */
@@ -84,6 +85,9 @@ export const PR_REPORT_POLICY_FLOOR = "0.124.41";
 /** The first chant whose apply report can carry `beforeMerge` and the `requires-unmet` and `before-merge-off` refusals (#4301, ws-106). */
 export const PR_REPORT_BEFORE_MERGE_FLOOR = "0.124.42";
 
+/** The first chant whose plan report can carry `migrations` (#4407). */
+export const PR_REPORT_MIGRATIONS_FLOOR = "0.124.49";
+
 /** The gate a pull request's apply waits on, unless the pipeline names another. */
 export const PR_APPLY_GATE = "pr-apply";
 
@@ -436,6 +440,13 @@ export interface PrReport {
    * {@link PR_REPORT_OVERDUE_FLOOR}.
    */
   overdue?: PrOverdue[];
+  /**
+   * Plan stage (#4407): the migration files the pull request adds in a
+   * migration-directory workspace member, each statement classified offline.
+   * Absent when it adds none. Added within contract 1 by chant
+   * {@link PR_REPORT_MIGRATIONS_FLOOR}.
+   */
+  migrations?: PrMigrationFile[];
   /** Component names: which changed, which run because they depend on one, and what the change touched that no component deploys. */
   selection: {
     changed: string[];
@@ -690,6 +701,7 @@ export function renderPrNote(report: PrReport, options: { limit?: number; approv
     out.push("", `Hooks: ${passed} passed${other.length > 0 ? `; ${other.join("; ")}` : ""}.`);
   }
   out.push(...policyLines(report));
+  out.push(...renderMigrationLines(report.migrations));
   if (report.selection.unclaimed.length > 0) {
     out.push("", `Changed, and deployed by no component: ${report.selection.unclaimed.map(code).join(", ")}.`);
   }

package/src/pr-migrations.ts

@@ -0,0 +1,97 @@
+/**
+ * The migration files a pull request adds, classified for the plan note
+ * (#4407). This is the "check" adoption level: each new migration in a
+ * migration-directory workspace member (goose, golang-migrate,
+ * clickhouse-migrations, Flyway) is read offline and its statements are given
+ * the class the lexicon's classifier gives the same change. Nothing is applied
+ * and no server is contacted.
+ *
+ * Core holds the shapes and the note's lines. The classes come from a
+ * lexicon's `classifyMigrations` (`./lexicon.ts`), the way a lexicon's
+ * `classifyDisruption` supplies the disruption of an update. Pure: it imports
+ * nothing, so `./pr-loop.ts` can render it.
+ */
+
+/** One change a statement makes, under one classifier rule. */
+export interface MigrationChange {
+  rule: string;
+  /** The rule's class, e.g. `rebuild`, `concurrently`, `metadata`. */
+  class: string;
+  /** The class as a report names it, e.g. `REBUILD`. */
+  label: string;
+  title: string;
+  /** Postgres: the lock the rule names. */
+  lock?: string;
+  destructive?: boolean;
+  note?: string;
+}
+
+/** What one statement came to: `undecided` lists `candidates`; `unclassified` and `data` say why in `note`. */
+export interface MigrationStatement {
+  /** 1-based position among the file's up statements. */
+  index: number;
+  /** The statement's first line, cut to 120 characters. */
+  sql: string;
+  outcome: "classified" | "undecided" | "unclassified" | "data";
+  changes: MigrationChange[];
+  candidates?: MigrationChange[];
+  note?: string;
+}
+
+/** What a lexicon answers for one new migration file. */
+export interface MigrationFileClassification {
+  /** The file, relative to the workspace root. */
+  file: string;
+  statements: MigrationStatement[];
+  /** Set when the file could not be read (a Flyway placeholder with no value): why. */
+  error?: string;
+}
+
+/** A new migration file in the report's `migrations`. */
+export interface PrMigrationFile extends MigrationFileClassification {
+  /** The workspace member whose directory holds it. */
+  member: string;
+  /** The reader that listed it: `goose-dir`, `golang-migrate-dir`, `clickhouse-migrations-dir` or `flyway-dir`. */
+  reader: string;
+  version: string;
+  name: string;
+  type: "versioned" | "repeatable" | "baseline" | "undo";
+  dialect: string;
+}
+
+/** One line of plain text: the report is read from a file the head's job wrote, so nothing in it breaks the note's layout. */
+const line = (s: string): string => s.replace(/\s+/g, " ").trim();
+
+const code = (s: string): string => `\`${line(s).replace(/`/g, "'")}\``;
+
+const changeText = (c: MigrationChange): string => `${c.label} (${c.rule}${c.lock ? `, ${c.lock}` : ""})${c.destructive ? ", removes data" : ""}`;
+
+/** The statement's row in the note. */
+function statementText(s: MigrationStatement): string {
+  if (s.outcome === "classified") return s.changes.map(changeText).join("; ") + (s.note ? `. ${line(s.note)}` : "");
+  if (s.outcome === "undecided") {
+    const decided = s.changes.length > 0 ? `${s.changes.map(changeText).join("; ")}; ` : "";
+    return `${decided}undecided between ${(s.candidates ?? []).map((c) => `${c.rule} ${c.label}`).join(" and ")}${s.note ? `: ${line(s.note)}` : ""}`;
+  }
+  if (s.outcome === "unclassified") return `no class${s.note ? `: ${line(s.note)}` : ""}`;
+  return `data, not schema${s.note ? `: ${line(s.note)}` : ""}`;
+}
+
+/**
+ * The note's section: one heading line per new file and a list of its
+ * statements with their classes. Empty when the pull request adds none.
+ */
+export function renderMigrationLines(files: readonly PrMigrationFile[] | undefined): string[] {
+  if (!files || files.length === 0) return [];
+  const out: string[] = ["", `New migration files (${files.length}), classified offline. Nothing is applied and no server is contacted.`];
+  for (const f of files) {
+    out.push("", `${code(f.file)} (member ${code(f.member)}, ${f.dialect}${f.type === "versioned" ? "" : `, ${f.type}`})`);
+    if (f.error) {
+      out.push(`- not read: ${line(f.error)}`);
+      continue;
+    }
+    if (f.statements.length === 0) out.push("- no up statements");
+    for (const s of f.statements) out.push(`- ${s.index}. ${code(s.sql)}: ${statementText(s)}`);
+  }
+  return out;
+}

package/src/pr-post-open.e2e.test.ts

@@ -0,0 +1,36 @@
+/**
+ * `chant components pr-post --open` refusals (#4328), through the CLI handler.
+ * Importing the handler loads the CLI's lexicon machinery, which runs past the
+ * unit-test budget (#2817), so this lives in the e2e project.
+ */
+
+import { describe, expect, test, vi } from "vitest";
+import type { CommandContext } from "./cli/registry";
+
+describe("chant components pr-post --open refuses what it cannot post for (#4328)", () => {
+  const run = async (args: Record<string, unknown>): Promise<number> => {
+    const { runComponentsPrPost } = await import("./cli/handlers/pr");
+    return runComponentsPrPost({ args } as unknown as CommandContext);
+  };
+
+  test("--pr or --head, a forge other than GitLab, and no branch are each refused", async () => {
+    const errors: string[] = [];
+    const spy = vi.spyOn(console, "error").mockImplementation((line: unknown) => void errors.push(String(line)));
+    try {
+      expect(await run({ open: true, pr: 7, env: "prod", forge: "gitlab" })).toBe(1);
+      expect(await run({ open: true, env: "prod", forge: "github" })).toBe(1);
+      const branch = process.env.CI_COMMIT_BRANCH;
+      delete process.env.CI_COMMIT_BRANCH;
+      try {
+        expect(await run({ open: true, env: "prod", forge: "gitlab" })).toBe(1);
+      } finally {
+        if (branch !== undefined) process.env.CI_COMMIT_BRANCH = branch;
+      }
+    } finally {
+      spy.mockRestore();
+    }
+    expect(errors.join("\n")).toMatch(/takes no --pr or --head/);
+    expect(errors.join("\n")).toMatch(/--forge gitlab/);
+    expect(errors.join("\n")).toMatch(/pass --branch <branch>/);
+  });
+});

package/src/pr-post.test.ts

@@ -8,9 +8,11 @@
 import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { afterAll, describe, expect, test } from "vitest";
-import { postPlanReport, readPlanReport } from "./pr-post";
-import { prNoteMarker, type PrReport } from "./pr-loop";
+import { afterAll, describe, expect, test, vi } from "vitest";
+import type { CommandContext } from "./cli/registry";
+import { parseArgs } from "./cli/parse-args";
+import { postOpenPlanReports, postPlanReport, readPlanReport } from "./pr-post";
+import { prNoteMarker, prStatusState, type PrReport } from "./pr-loop";
 import type { ForgeStatus, PrForge } from "./pr-forge";
 
 const FIXTURE = join(import.meta.dirname, "__fixtures__", "pr-loop", "pr-plan.golden.json");
@@ -139,3 +141,100 @@ describe("pr-post asks for overdue scheduled Ops itself (#4289, #4295)", () => {
     expect(quiet.notes[0]!.body).not.toContain("forged warning");
   });
 });
+
+describe("pr-post --open posts each open merge request's plan from a pipeline of the target branch (#4328)", () => {
+  const JOB_URL = (id: number) => `https://gitlab.com/acme/estate/-/jobs/${id}`;
+  const OTHER = "c".repeat(40);
+
+  /** A GitLab client with the merge requests' plan jobs, their artifacts and the statuses already posted. */
+  function gitlab(input: { jobs: Array<{ pr: number; head: string; id: number; status: string }>; artifacts: Record<number, string>; posted?: Record<string, string> }) {
+    const statuses: Array<{ sha: string; status: ForgeStatus; url?: string }> = [];
+    const notes: Array<{ pr: number; body: string }> = [];
+    const asked: Array<[string, string]> = [];
+    const reads: string[] = [];
+    let overdue = 0;
+    const forge = {
+      kind: "gitlab",
+      host: "gitlab.com",
+      async mergeRequestJobs(branch: string, job: string) {
+        asked.push([branch, job]);
+        return input.jobs.map((j) => ({ ...j, url: JOB_URL(j.id) }));
+      },
+      async jobArtifact(id: number, path: string) {
+        reads.push(`${id}:${path}`);
+        return input.artifacts[id];
+      },
+      async statusUrl(sha: string) {
+        return input.posted?.[sha];
+      },
+      async setStatus(this: PrForge, sha: string, status: ForgeStatus) {
+        statuses.push({ sha, status, ...(this.runUrl ? { url: this.runUrl } : {}) });
+      },
+      async upsertNote(pr: number, _marker: string, body: string) {
+        notes.push({ pr, body });
+        return "1";
+      },
+    } as unknown as PrForge;
+    const count = async () => {
+      overdue++;
+      return [{ op: "drift", cron: "0 * * * *", since: "2025-10-01T00:00:00Z", message: "Op `drift` is overdue" }];
+    };
+    return { forge, statuses, notes, asked, reads, overdue: count, overdueCalls: () => overdue };
+  }
+
+  test("a settled plan job's report is read from its artifacts and posted, linking the job; a running one waits", async () => {
+    const g = gitlab({
+      jobs: [
+        { pr: REPORT.pr!, head: HEAD, id: 101, status: "success" },
+        { pr: 8, head: OTHER, id: 102, status: "running" },
+      ],
+      artifacts: { 101: JSON.stringify(REPORT) },
+    });
+    const { posts, warnings } = await postOpenPlanReports({ forge: g.forge, branch: "main", job: "plan", artifactDir: ".chant/pr/", env: REPORT.env, overdue: g.overdue });
+    expect(warnings).toEqual([]);
+    expect(g.asked).toEqual([["main", "plan"]]);
+    expect(g.reads).toEqual(["101:.chant/pr/pr-plan.json"]);
+    expect(posts.map((p) => [p.pr, p.skipped ?? p.posted!.state])).toEqual([[REPORT.pr, prStatusState(REPORT)], [8, "the plan job is running"]]);
+    expect(g.statuses).toEqual([{ sha: HEAD, status: expect.objectContaining({ context: "chant/plan", state: prStatusState(REPORT), url: JOB_URL(101) }), url: JOB_URL(101) }]);
+    expect(g.notes.map((n) => n.pr)).toEqual([REPORT.pr]);
+    expect(g.notes[0]!.body).toContain("Op `drift` is overdue");
+  });
+
+  test("a job whose result is already posted is not posted again", async () => {
+    const g = gitlab({ jobs: [{ pr: REPORT.pr!, head: HEAD, id: 101, status: "success" }], artifacts: { 101: JSON.stringify(REPORT) }, posted: { [HEAD]: JOB_URL(101) } });
+    const { posts } = await postOpenPlanReports({ forge: g.forge, branch: "main", job: "plan", artifactDir: ".chant/pr", env: REPORT.env });
+    expect(posts).toEqual([{ pr: REPORT.pr, head: HEAD, skipped: "this plan job's result is already posted" }]);
+    expect(g.statuses).toEqual([]);
+  });
+
+  test("the pull request and head are GitLab's: a report for another head, a missing one and a failed job each fail the status", async () => {
+    const g = gitlab({
+      jobs: [
+        { pr: REPORT.pr!, head: OTHER, id: 101, status: "success" },
+        { pr: 8, head: HEAD, id: 102, status: "failed" },
+        { pr: 9, head: HEAD, id: 103, status: "failed" },
+      ],
+      artifacts: { 101: JSON.stringify(REPORT), 103: JSON.stringify({ ...REPORT, pr: 9 }) },
+    });
+    const { posts } = await postOpenPlanReports({ forge: g.forge, branch: "main", job: "plan", artifactDir: ".chant/pr", env: REPORT.env, overdue: g.overdue });
+    expect(posts.map((p) => [p.pr, p.posted!.state, p.posted!.refused ?? ""])).toEqual([
+      [REPORT.pr, "failure", expect.stringMatching(/the report is for head/)],
+      [8, "failure", "the plan job wrote no report"],
+      [9, "failure", ""],
+    ]);
+    expect(g.notes.map((n) => n.pr)).toEqual([9]);
+    // The check runs once, however many merge requests it posts for.
+    expect(g.overdueCalls()).toBe(1);
+  });
+
+  test("a forge that cannot list merge request jobs is refused", async () => {
+    await expect(postOpenPlanReports({ forge: fakeForge().forge, branch: "main", job: "plan", artifactDir: ".chant/pr", env: REPORT.env })).rejects.toThrow(/it is for GitLab/);
+  });
+});
+
+describe("chant components pr-post --open refuses what it cannot post for (#4328)", () => {
+
+  test("the flags parse", () => {
+    expect(parseArgs(["components", "pr-post", "--open", "--env", "prod", "--forge", "gitlab", "--branch", "main"])).toMatchObject({ open: true, env: "prod", forge: "gitlab", branch: "main" });
+  });
+});

package/src/pr-post.ts

@@ -14,9 +14,16 @@
  * every hidden HTML comment after its first line is defused, so a forged
  * marker cannot claim another environment's note. A plan job that failed
  * fails the status whatever its report says.
+ *
+ * On GitLab the post runs in a pipeline of the target branch (#4328): a
+ * merge request pipeline is built from the merge request's own files, so a
+ * job there that holds `CHANT_FORGE_TOKEN` runs whatever the change wrote.
+ * `pr-post --open` ({@link postOpenPlanReports}) asks GitLab for each open
+ * merge request's plan job and reads the report from its artifacts.
  */
 
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { prNoteMarker, prStatusContext, prStatusDescription, prStatusState, renderPrNote, type PrOverdue, type PrReport } from "./pr-loop";
 import { forgePrincipalOf, type PrForge } from "./pr-forge";
@@ -130,7 +137,7 @@ export async function postPlanReport(input: PlanPostInput): Promise<PlanPostResu
       state = prStatusState(report);
       description = prStatusDescription(report);
       // A member the change does not reach has nothing to say on the pull request (as pr-plan's own publish).
-      if (!(input.member && report.status === "nothing" && !report.overdue?.length)) note = planNoteFor(report, input.forge, prNoteMarker(input.env, input.member));
+      if (!(input.member && report.status === "nothing" && !report.overdue?.length && !report.migrations?.length)) note = planNoteFor(report, input.forge, prNoteMarker(input.env, input.member));
     } catch (err) {
       refused = `the plan report does not render: ${err instanceof Error ? err.message : String(err)}`;
       state = "failure";
@@ -157,3 +164,84 @@ export async function postPlanReport(input: PlanPostInput): Promise<PlanPostResu
   }
   return { state, description: cut(description), noted: note !== undefined, ...(refused ? { refused } : {}), warnings };
 }
+
+/** What {@link postOpenPlanReports} posts for. */
+export interface OpenPlanPostInput {
+  /** A GitLab client with {@link PrForge.mergeRequestJobs}, {@link PrForge.jobArtifact} and {@link PrForge.statusUrl}. */
+  forge: PrForge;
+  /** The branch the merge requests merge into: the pipeline's own. */
+  branch: string;
+  /** The plan job's name in the merge request pipeline: `plan`, or `<member>-plan`. */
+  job: string;
+  /** The report directory from the repository root, as the plan job kept it as its artifact. */
+  artifactDir: string;
+  env: string;
+  member?: string;
+  overdue?: () => Promise<PrOverdue[]>;
+}
+
+/** What {@link postOpenPlanReports} did for one merge request. */
+export interface OpenPlanPost {
+  pr: number;
+  head: string;
+  /** What was posted, or why nothing was: the plan job has not settled, or its result is already posted. */
+  posted?: PlanPostResult;
+  skipped?: string;
+}
+
+/**
+ * Post the plan note and status of every open merge request into `branch`
+ * whose plan job settled (#4328), from a pipeline of `branch`. GitLab says
+ * which merge requests are open, their heads, and their newest pipeline's
+ * plan job; the report is the one file `pr-plan.json` of that job's
+ * artifacts, read as data as {@link postPlanReport} reads any. The status
+ * links to the plan job, and a status that already links to it is the
+ * job's result posted, so a job is posted for once. The overdue check runs
+ * once for every merge request.
+ */
+export async function postOpenPlanReports(input: OpenPlanPostInput): Promise<{ posts: OpenPlanPost[]; warnings: string[] }> {
+  const { forge } = input;
+  if (!forge.mergeRequestJobs || !forge.jobArtifact || !forge.statusUrl) {
+    throw new Error(`pr-post --open reads the plan jobs of open merge requests, which ${forge.kind} cannot say; it is for GitLab`);
+  }
+  const context = prStatusContext("plan", input.member);
+  const warnings: string[] = [];
+  let overdue: Promise<PrOverdue[]> | undefined;
+  const overdueOnce = input.overdue ? () => (overdue ??= input.overdue!()) : undefined;
+  const posts: OpenPlanPost[] = [];
+  for (const job of await forge.mergeRequestJobs(input.branch, input.job)) {
+    const settled = job.status === "success" ? "success" : job.status === "failed" ? "failure" : job.status === "canceled" ? "cancelled" : undefined;
+    if (!settled) {
+      posts.push({ pr: job.pr, head: job.head, skipped: `the plan job is ${job.status}` });
+      continue;
+    }
+    try {
+      if (job.url && (await forge.statusUrl(job.head, context)) === job.url) {
+        posts.push({ pr: job.pr, head: job.head, skipped: "this plan job's result is already posted" });
+        continue;
+      }
+      const dir = mkdtempSync(join(tmpdir(), "chant-pr-post-"));
+      try {
+        const text = await forge.jobArtifact(job.id, `${input.artifactDir.replace(/\/+$/, "")}/${PR_PLAN_REPORT_FILE}`);
+        if (text !== undefined) writeFileSync(join(dir, PR_PLAN_REPORT_FILE), text);
+        const posted = await postPlanReport({
+          // The status links to the plan job it reports on, which is how the next run knows it is posted.
+          forge: job.url ? { ...forge, runUrl: job.url } : forge,
+          dir,
+          pr: job.pr,
+          head: job.head,
+          env: input.env,
+          ...(input.member ? { member: input.member } : {}),
+          result: settled,
+          ...(overdueOnce ? { overdue: overdueOnce } : {}),
+        });
+        posts.push({ pr: job.pr, head: job.head, posted });
+      } finally {
+        rmSync(dir, { recursive: true, force: true });
+      }
+    } catch (err) {
+      warnings.push(`!${job.pr}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  return { posts, warnings };
+}

package/src/read-filter.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+import { FilterError, matchesWhere, parseInstant, parseSince, parseWhere, type FilterFields } from "./read-filter";
+
+const fields: FilterFields = { name: "text", count: "number", ok: "boolean", at: "time", labels: "json", "unit.id": "text" };
+const now = new Date("2026-10-23T12:00:00.000Z");
+const keep = (rows: { name: string }[], ...where: string[]) => rows.filter((r) => matchesWhere(r, parseWhere(where, fields, now))).map((r) => r.name);
+
+describe("typed filters (#4363)", () => {
+  const rows = [
+    { name: "web", count: 3, ok: true, at: "2026-10-22T00:00:00.000Z", labels: { team: "core", size: 2 }, unit: { id: "W-1" } },
+    { name: "worker", count: 10, ok: false, at: "2026-10-01T00:00:00.000Z", labels: '{"team":"edge","size":12}', unit: null },
+    { name: "db", count: null, ok: true, at: null, labels: null, unit: { id: "W-2" } },
+  ];
+
+  it("filters each type with its operators, every clause holding", () => {
+    expect(keep(rows, "name=web")).toEqual(["web"]);
+    expect(keep(rows, "name~w")).toEqual(["web", "worker"]);
+    expect(keep(rows, "count>=3", "count<10")).toEqual(["web"]);
+    expect(keep(rows, "ok=false")).toEqual(["worker"]);
+    expect(keep(rows, "at>7d")).toEqual(["web"]);
+    expect(keep(rows, "at<2026-10-10")).toEqual(["worker"]);
+    expect(keep(rows, "unit.id=W-2")).toEqual(["db"]);
+  });
+
+  it("reads a key under a json field, parsing JSON text, as the type it holds", () => {
+    expect(keep(rows, "labels.team=edge")).toEqual(["worker"]);
+    expect(keep(rows, "labels.size>5")).toEqual(["worker"]);
+  });
+
+  it("matches null with = and !=, and a null field only with !=", () => {
+    expect(keep(rows, "count=null")).toEqual(["db"]);
+    expect(keep(rows, "count!=null")).toEqual(["web", "worker"]);
+    expect(keep(rows, "count!=3")).toEqual(["worker", "db"]);
+    expect(keep(rows, "count<100")).toEqual(["web", "worker"]);
+  });
+
+  it("refuses a field, operator or value that doesn't fit, before reading", () => {
+    expect(() => parseWhere(["nope=1"], fields)).toThrow(/no such field; this read filters on name, count/);
+    expect(() => parseWhere(["count=many"], fields)).toThrow(FilterError);
+    expect(() => parseWhere(["ok>true"], fields)).toThrow(/= or != only/);
+    expect(() => parseWhere(["count~1"], fields)).toThrow(/takes a text field/);
+    expect(() => parseWhere(["at=yesterday"], fields)).toThrow(/is a time/);
+    expect(() => parseWhere(["labels=x"], fields)).toThrow(/name a key under it/);
+    expect(() => parseWhere(["name>=null"], fields)).toThrow(/null takes = or != only/);
+    expect(() => parseWhere(["just-a-word"], fields)).toThrow(/<field><op><value>/);
+  });
+
+  it("reads --since as an ISO time or a span back from now", () => {
+    expect(parseSince("7d", now)).toBe("2026-10-16T12:00:00.000Z");
+    expect(parseSince("2026-10-01", now)).toBe("2026-10-01T00:00:00.000Z");
+    expect(parseInstant("90m", now)).toBe(now.getTime() - 90 * 60_000);
+    expect(() => parseSince("last week", now)).toThrow(FilterError);
+  });
+});

package/src/read-filter.ts

@@ -0,0 +1,193 @@
+/**
+ * Typed filters for the contract reads (#4363): `--where <field><op><value>`
+ * and `--since <time>`, in place of an embedded SQL engine.
+ *
+ * Each read declares the fields it can be filtered on and their types
+ * ({@link FilterFields}). A clause naming a field the read doesn't declare, an
+ * operator its type doesn't take, or a value that isn't of its type is a
+ * {@link FilterError} before anything is read, so a typo never filters to an
+ * empty answer. Several `--where` clauses all have to hold.
+ *
+ * Operators: `=` and `!=` for every type; `<`, `<=`, `>` and `>=` for
+ * numbers, times and text (text compares by code point); `~` for text, which
+ * holds when the field contains the value. The value `null` matches a field
+ * that is null or absent, with `=` and `!=` only.
+ *
+ * A field of type `json` holds an object: a clause can name a key under it
+ * with dots (`labels.team=core`), and the value is compared as the type it
+ * holds there (a number with a number, a boolean with `true` or `false`, any
+ * other value as text). A JSON text is parsed first, so a ledger row that
+ * keeps the object as text filters the same way.
+ *
+ * A null or absent field matches only `=null` and `!=` with a value other
+ * than null; the other operators never hold for it.
+ *
+ * Pure: no I/O, so a bundle that filters rows loads nothing else.
+ */
+
+export type FilterFieldType = "text" | "number" | "boolean" | "time" | "json";
+
+/** The fields a read can be filtered on, by name, with their types. */
+export type FilterFields = Readonly<Record<string, FilterFieldType>>;
+
+/** Every operator, longest first so `!=` is not read as `=`. */
+export const WHERE_OPERATORS = ["!=", "<=", ">=", "=", "<", ">", "~"] as const;
+export type WhereOperator = (typeof WHERE_OPERATORS)[number];
+
+/** One parsed `--where` clause. */
+export interface WhereClause {
+  /** The field as written, with any path under a `json` field. */
+  field: string;
+  /** The declared field the clause starts at. */
+  base: string;
+  /** The keys under a `json` field, or `[]`. */
+  path: string[];
+  type: FilterFieldType;
+  op: WhereOperator;
+  /** The value as written. */
+  raw: string;
+  /** The value read as the field's type: a number for `number` and `time` (epoch ms), a boolean, a string, or null. */
+  value: string | number | boolean | null;
+}
+
+/** A clause or a `--since` that can't be applied. The message is for a person. */
+export class FilterError extends Error {}
+
+const ORDERED: readonly WhereOperator[] = ["<", "<=", ">", ">="];
+
+/**
+ * An instant from an ISO 8601 date or time, or from a span back from `now`:
+ * `<n>m`, `<n>h`, `<n>d` or `<n>w`. Epoch milliseconds, or null when `text`
+ * is neither.
+ */
+export function parseInstant(text: string, now: Date = new Date()): number | null {
+  const span = /^(\d+)([mhdw])$/.exec(text.trim());
+  if (span) {
+    const unit = { m: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000 }[span[2] as "m" | "h" | "d" | "w"];
+    return now.getTime() - Number(span[1]) * unit;
+  }
+  if (!/^\d{4}-\d{2}-\d{2}/.test(text.trim())) return null;
+  const ms = Date.parse(text);
+  return Number.isNaN(ms) ? null : ms;
+}
+
+/** `--since <time>` as an ISO instant, or a {@link FilterError}. */
+export function parseSince(text: string, now: Date = new Date()): string {
+  const ms = parseInstant(text, now);
+  if (ms === null) throw new FilterError(`--since takes an ISO 8601 date or time, or a span back from now such as 24h or 7d, not ${JSON.stringify(text)}`);
+  return new Date(ms).toISOString();
+}
+
+/** The declared field a dotted name starts at: the whole name, or its longest declared `json` prefix. */
+function resolveField(name: string, fields: FilterFields): { base: string; path: string[]; type: FilterFieldType } | null {
+  if (Object.prototype.hasOwnProperty.call(fields, name)) return { base: name, path: [], type: fields[name] };
+  const parts = name.split(".");
+  for (let i = parts.length - 1; i > 0; i--) {
+    const base = parts.slice(0, i).join(".");
+    if (Object.prototype.hasOwnProperty.call(fields, base) && fields[base] === "json") return { base, path: parts.slice(i), type: "json" };
+  }
+  return null;
+}
+
+/** Parse each `--where` against the fields a read declares. Throws a {@link FilterError}. */
+export function parseWhere(exprs: readonly string[], fields: FilterFields, now: Date = new Date()): WhereClause[] {
+  const names = Object.keys(fields).join(", ");
+  return exprs.map((expr) => {
+    const m = /^([A-Za-z_][\w.-]*)\s*(!=|<=|>=|=|<|>|~)(.*)$/s.exec(expr);
+    if (!m) throw new FilterError(`--where takes <field><op><value>, with op one of ${WHERE_OPERATORS.join(" ")}, not ${JSON.stringify(expr)}`);
+    const [, field, op, rawValue] = m as unknown as [string, string, WhereOperator, string];
+    const raw = rawValue.trim();
+    const found = resolveField(field, fields);
+    if (!found) throw new FilterError(`--where ${field}: no such field; this read filters on ${names}`);
+    const { base, path, type } = found;
+    if (type === "json" && path.length === 0) throw new FilterError(`--where ${field}: holds an object; name a key under it, such as ${field}.<key>`);
+    const clause = (value: WhereClause["value"]): WhereClause => ({ field, base, path, type, op, raw, value });
+    if (raw === "null") {
+      if (op !== "=" && op !== "!=") throw new FilterError(`--where ${field}${op}null: null takes = or != only`);
+      return clause(null);
+    }
+    if (op === "~" && type !== "text" && type !== "json") throw new FilterError(`--where ${field}~: ~ (contains) takes a text field; ${field} is ${type}`);
+    switch (type) {
+      case "number": {
+        const n = Number(raw);
+        if (raw === "" || !Number.isFinite(n)) throw new FilterError(`--where ${field}: ${field} is a number, not ${JSON.stringify(raw)}`);
+        return clause(n);
+      }
+      case "boolean": {
+        if (ORDERED.includes(op)) throw new FilterError(`--where ${field}${op}: a boolean takes = or != only`);
+        if (raw !== "true" && raw !== "false") throw new FilterError(`--where ${field}: ${field} is true or false, not ${JSON.stringify(raw)}`);
+        return clause(raw === "true");
+      }
+      case "time": {
+        const ms = parseInstant(raw, now);
+        if (ms === null) throw new FilterError(`--where ${field}: ${field} is a time; give an ISO 8601 date or time, or a span back from now such as 24h or 7d, not ${JSON.stringify(raw)}`);
+        return clause(ms);
+      }
+      default:
+        return clause(raw);
+    }
+  });
+}
+
+/** The value at a clause's field in `row`, parsing a JSON text on the way into a `json` field. */
+function valueAt(row: unknown, c: WhereClause): unknown {
+  let v: unknown = row;
+  for (const key of c.base.split(".")) v = v !== null && typeof v === "object" ? (v as Record<string, unknown>)[key] : undefined;
+  for (const key of c.path) {
+    if (typeof v === "string") {
+      try {
+        v = JSON.parse(v);
+      } catch {
+        return undefined;
+      }
+    }
+    v = v !== null && typeof v === "object" && !Array.isArray(v) ? (v as Record<string, unknown>)[key] : undefined;
+  }
+  return v;
+}
+
+function compare(a: number | string, b: number | string, op: WhereOperator): boolean {
+  switch (op) {
+    case "=": return a === b;
+    case "!=": return a !== b;
+    case "<": return a < b;
+    case "<=": return a <= b;
+    case ">": return a > b;
+    case ">=": return a >= b;
+    case "~": return String(a).includes(String(b));
+  }
+}
+
+/** Whether one clause holds for `row`. */
+export function clauseHolds(row: unknown, c: WhereClause): boolean {
+  const v = valueAt(row, c);
+  if (c.value === null) return c.op === "=" ? v === null || v === undefined : v !== null && v !== undefined;
+  if (v === null || v === undefined) return c.op === "!=";
+  switch (c.type) {
+    case "number":
+      return typeof v === "number" && compare(v, c.value as number, c.op);
+    case "boolean":
+      return typeof v === "boolean" ? (c.op === "=") === (v === c.value) : false;
+    case "time": {
+      const ms = typeof v === "string" ? Date.parse(v) : typeof v === "number" ? v : NaN;
+      return !Number.isNaN(ms) && compare(ms, c.value as number, c.op);
+    }
+    case "text":
+      return typeof v === "string" && compare(v, c.value as string, c.op);
+    case "json": {
+      // Compared as the type the value holds there.
+      if (typeof v === "number" && c.op !== "~") {
+        const n = Number(c.raw);
+        return Number.isFinite(n) && compare(v, n, c.op);
+      }
+      if (typeof v === "boolean") return (c.raw === "true" || c.raw === "false") && (c.op === "=" || c.op === "!=") ? (c.op === "=") === (String(v) === c.raw) : false;
+      const s = typeof v === "string" ? v : JSON.stringify(v);
+      return compare(s, c.raw, c.op);
+    }
+  }
+}
+
+/** Whether every clause holds for `row`. */
+export function matchesWhere(row: unknown, clauses: readonly WhereClause[]): boolean {
+  return clauses.every((c) => clauseHolds(row, c));
+}

package/src/run-event.ts

@@ -58,7 +58,7 @@ export type RunEventStepStatus = "ok" | "failed" | "skipped" | "cached" | "gated
 export type RunEventSkipReason = "receipt" | "resumed" | "refused" | "not-run";
 
 /** How a gate's approval passed, when it was more than one person's approval of that gate. */
-export type RunEventGateVia = "quorum" | "policy" | "point" | "alias" | "empty";
+export type RunEventGateVia = "quorum" | "policy" | "point" | "alias" | "empty" | "workspace";
 
 /** The run every event of a stream names: the same on every line. */
 export interface RunEventRun {