@intentius/chant 0.124.46 → 0.124.48

package/src/workspace/kind-link-readers.ts

@@ -19,12 +19,24 @@
  * `resolveLinks` (`./links.ts`) resolves the links beside the declared ones,
  * with origin `kind-reader`; WSP093 and WSP094 name the reader's file and line,
  * and WSP099 reports the gaps.
+ *
+ * A migration directory's reader (#4400) lists its migrations in order, in
+ * {@link KindLinkRead.migrations}, and returns no links: what the migrations
+ * produce comes from a replay.
+ *
+ * A reader may also return outputs (#3935): names the member's files state,
+ * which other members link to. A dbt project's models are outputs, read the
+ * same way as its sources. `resolveLinks` adds them to the member's handles
+ * (`withReaderOutputs`), so a link to one resolves, and goes missing when the
+ * file that states it is gone.
  */
 
 import type { Declaration, Member } from "./declaration";
 import { resolveMemberFields, type FieldValue, type KindLinkReaderName, type KindRegistry } from "./kinds";
 import type { WorkspaceTree } from "./tree";
 import { readDbtProject } from "./dbt-project-reader";
+import { readClickHouseMigrationsDir, readGolangMigrateDir, readGooseDir } from "./migration-dirs";
+import { readFlywayDir } from "./flyway-dir";
 
 /** One link a reader found in the member's files. */
 export interface KindReadLink {
@@ -54,18 +66,67 @@ export interface KindReadGap {
   file: string;
   line: number;
   message: string;
+  /**
+   * True when the gap leaves an output out of {@link KindLinkRead.outputs}
+   * (#3935): a link to a name the member does not list is then unresolved,
+   * not missing.
+   */
+  outputs?: boolean;
+}
+
+/** One output a reader found in the member's files: a name other members may link to. */
+export interface KindReadOutput {
+  name: string;
+  /** The file that states it, relative to the workspace root. */
+  file: string;
+  /** Its line, from 1. */
+  line: number;
+}
+
+/**
+ * One migration a migration-directory reader found (#4400), in the order the
+ * tool applies it. The reader lists files and never runs the tool, so the
+ * schema the migrations produce comes from a replay, not from here.
+ */
+export interface KindReadMigration {
+  /** 1-based position in the order the tool applies the migrations. */
+  position: number;
+  /** The version as the file name writes it, such as `00002`, `20240101120000` or `1.2`. */
+  version: string;
+  name: string;
+  /** `versioned` runs once; `repeatable` runs again when its checksum changes (Flyway); `baseline` and `undo` are Flyway's B and U files. */
+  type: "versioned" | "repeatable" | "baseline" | "undo";
+  /** The file with the up statements, relative to the workspace root. */
+  file: string;
+  /** The line the up statements start on, from 1. */
+  line: number;
+  /** The file that undoes it, or true when the same file does (goose), or false when none does. */
+  down: string | boolean;
+  /** The SQL dialect the migration is written in: the member's `dialect` field, or what the directory's own configuration names. */
+  dialect: string;
+  /** False when the file asks to run outside a transaction (`-- +goose NO TRANSACTION`). */
+  transaction?: boolean;
 }
 
 export interface KindLinkRead {
-  /** The reader that ran. */
-  reader: KindLinkReaderName;
+  /** The reader that ran: a kind's reader, or `lexicon <name>` for links a member's lexicon read from its declarations (#4397). */
+  reader: KindLinkReaderName | `lexicon${string}`;
   links: KindReadLink[];
   gaps: KindReadGap[];
+  /**
+   * The outputs the member exposes that its files state (#3935), beside the
+   * ones its kind lists. `resolveLinks` adds them to the member's handles, so
+   * another member can link to them. A gap flagged `outputs` makes the list
+   * incomplete.
+   */
+  outputs?: KindReadOutput[];
   /**
    * The member field that names the producer, for messages that ask the
    * author to set it when the files don't say (`sqlMember` for dbt).
    */
   producerField?: string;
+  /** The migrations of a migration directory (#4400), in the order they apply; unset for other readers. */
+  migrations?: KindReadMigration[];
 }
 
 /** What a reader gets: the member, its directory and resolved fields, and the tree read. */
@@ -83,6 +144,10 @@ export type KindLinkReader = (input: KindReaderInput) => KindLinkRead;
 /** Every reader chant ships, by the name a kinds file uses. */
 export const LINK_READERS: Record<KindLinkReaderName, KindLinkReader> = {
   "dbt-project": readDbtProject,
+  "goose-dir": readGooseDir,
+  "golang-migrate-dir": readGolangMigrateDir,
+  "clickhouse-migrations-dir": readClickHouseMigrationsDir,
+  "flyway-dir": readFlywayDir,
 };
 
 /**
@@ -102,7 +167,7 @@ export function readKindLinks(declaration: Declaration, tree: WorkspaceTree, kin
     try {
       out.set(m.name, LINK_READERS[kind.reader]({ member: m, dir, fields, tree }));
     } catch (err) {
-      out.set(m.name, { reader: kind.reader, links: [], gaps: [{ file: dir || ".", line: 1, message: `the ${kind.reader} reader failed: ${(err as Error).message}` }] });
+      out.set(m.name, { reader: kind.reader, links: [], gaps: [{ file: dir || ".", line: 1, message: `the ${kind.reader} reader failed: ${(err as Error).message}`, outputs: true }] });
     }
   }
   return out;

package/src/workspace/kinds.test.ts

@@ -61,10 +61,10 @@ function pkg(name: string, version: string, kinds: unknown[] | null, extra: Reco
 }
 
 describe("the built-in kinds (#2535)", () => {
-  test("are chant, workspace, design and other, and the group kind examples", () => {
-    expect(BUILTIN_KINDS.map((k) => `${k.name}:${k.shape}`)).toEqual(["chant:member", "workspace:member", "other:member", "design:member", "examples:group"]);
+  test("are chant, workspace, repo, design and other, and the group kind examples", () => {
+    expect(BUILTIN_KINDS.map((k) => `${k.name}:${k.shape}`)).toEqual(["chant:member", "workspace:member", "repo:member", "other:member", "design:member", "examples:group"]);
     const registry = builtinKindRegistry();
-    expect(registry.names()).toEqual(["chant", "design", "other", "workspace"]);
+    expect(registry.names()).toEqual(["chant", "design", "other", "repo", "workspace"]);
     expect(registry.get(EXAMPLES_KIND)?.shape).toBe("group");
   });
 
@@ -72,8 +72,13 @@ describe("the built-in kinds (#2535)", () => {
     const entry = declarationSchema.$defs.entry;
     expect(entry.if.properties.kind.const).toBe(EXAMPLES_KIND);
     expect(declarationSchema.$defs.group.properties.kind.const).toBe(EXAMPLES_KIND);
-    expect(declarationSchema.$defs.member.if.properties.kind.const).toBe("other");
-    expect(declarationSchema.$defs.member.then.required).toEqual(["because"]);
+    const [other, repo] = declarationSchema.$defs.member.allOf;
+    expect(other.if.properties.kind.const).toBe("other");
+    expect(other.then.required).toEqual(["because"]);
+    // A repo member (#3168) has repo and no dir; every other member has dir and no repo.
+    expect(repo.if.properties.kind.const).toBe("repo");
+    expect(repo.then.required).toEqual(["repo"]);
+    expect(repo.else?.required).toEqual(["dir"]);
   });
 
   test("a registry refuses a name twice", () => {
@@ -203,7 +208,7 @@ describe("loadKindRegistry: kinds from the pins", () => {
     const { registry, problems } = loadKindRegistry([{ package: "@acme/chant-lexicon-tf", version: "1.2.3", path: null }], root);
     expect(problems).toEqual([]);
     expect(registry.get("terraform")).toMatchObject({ source: "@acme/chant-lexicon-tf", precedence: 400 });
-    expect(registry.names()).toEqual(["chant", "design", "other", "terraform", "workspace"]);
+    expect(registry.names()).toEqual(["chant", "design", "other", "repo", "terraform", "workspace"]);
     expect(existsSync(join(root, "node_modules/@acme/chant-lexicon-tf/IMPORTED"))).toBe(false);
     expect((globalThis as { __chantKindsImported?: boolean }).__chantKindsImported).toBeUndefined();
   });
@@ -223,7 +228,7 @@ describe("loadKindRegistry: kinds from the pins", () => {
       ],
       root,
     );
-    expect(registry.names()).toEqual(["chant", "design", "other", "workspace"]);
+    expect(registry.names()).toEqual(["chant", "design", "other", "repo", "workspace"]);
     expect(problems).toEqual([
       { pin: 1, message: "pinned package absent is not installed; install it to read the kinds it supplies" },
       { pin: 2, message: "tf-kinds is pinned at 1.0.0, and 2.0.0 is installed" },

package/src/workspace/kinds.ts

@@ -25,6 +25,7 @@ import { joinPath, skippedDir } from "./tree";
 import { checkPinIntegrity } from "./pin-integrity";
 import { dataExportTarget, findInstalledPackage } from "./class-data";
 import { loadAjv2020 } from "./ajv2020";
+import yaml from "js-yaml";
 
 export const KINDS_SCHEMA_ID = schema.$id;
 
@@ -34,7 +35,9 @@ export const KINDS_SUBPATH = "./workspace-kinds";
 /**
  * The probe a package's kind carries (#2535, #2545). It passes when any of
  * its clauses does. A name in either clause may use `*`, which matches any
- * run of characters in one file name, so `*.tf` is every Terraform file.
+ * run of characters in one file name, so `*.tf` is every Terraform file, and
+ * `[0-9]` matches one digit (#4400), so `[0-9]*_*.sql` is a file that opens
+ * with a version number.
  */
 export interface FileProbe {
   /** A file matching one of these names sits directly in the directory. */
@@ -53,6 +56,13 @@ export interface FileProbe {
    * without claiming every Node package (#3151).
    */
   anyJsonKey?: { in: string[]; pointers: string[] };
+  /**
+   * A file directly in the directory whose name matches one of `in` has a
+   * line that starts, after leading space and ignoring case, with one of
+   * `starts` (#4400). This is how a goose directory is told from any other
+   * directory of `.sql` files: its files carry `-- +goose Up`.
+   */
+  anyLine?: { in: string[]; starts: string[] };
 }
 
 /** A string, integer or boolean field a kind declares for its members (#3151). */
@@ -81,7 +91,9 @@ export type KindProbe =
   /** The directory exists; nothing else is checked (`other`). */
   | { directory: true }
   /** The directory holds a chant project, as {@link holdsChantProject} says (`examples`). */
-  | { chantProject: true };
+  | { chantProject: true }
+  /** Nothing local: the member names another repository's workspace (`repo`, #3168). */
+  | { repo: true };
 
 /**
  * Which outputs a member of a kind exposes as link targets (#2524 D6,
@@ -135,15 +147,38 @@ export interface MemberKind {
    * entry states.
    */
   reader?: KindLinkReaderName;
+  /** A file every member of the kind has, and the JSON Schema it must pass (#3672); unset, the kind checks no member file. */
+  memberFile?: KindMemberFile;
+}
+
+/**
+ * A kind's member file (#3672): `path` in each member's directory must pass
+ * the JSON Schema at `schema` in the supplying package. `chant workspace
+ * check` reads and validates it (WSP012). The schema is read as data when the
+ * package's kinds are read, so a schema that is missing or doesn't compile is
+ * a load problem (WSP002), and `validate` is unset.
+ */
+export interface KindMemberFile {
+  /** The file, relative to the member's directory. */
+  path: string;
+  /** The schema, as the kinds file names it, relative to the package. */
+  schema: string;
+  /** The schema, absolute; unset until the package directory is known. */
+  schemaFile?: string;
+  /** The compiled schema; unset when it could not be read or compiled. */
+  validate?: MemberFileValidate;
 }
 
+/** A compiled member-file schema, in Ajv's shape. */
+export type MemberFileValidate = ((data: unknown) => boolean) & { errors?: { instancePath: string; message?: string; params?: Record<string, unknown> }[] | null };
+
 /**
  * The link readers chant ships (#3932). A kind names one in its kinds file as
  * `reader`. The readers are chant's own code, not the package's: a kinds file
  * stays data, and chant never imports the package that supplies it. Closed:
  * a kind naming another reader is kept without one, and the load reports it.
  */
-export const KIND_LINK_READERS = ["dbt-project"] as const;
+export const KIND_LINK_READERS = ["dbt-project", "goose-dir", "golang-migrate-dir", "clickhouse-migrations-dir", "flyway-dir"] as const;
 export type KindLinkReaderName = (typeof KIND_LINK_READERS)[number];
 
 export interface KindRegistry {
@@ -157,6 +192,9 @@ export interface KindRegistry {
 /** The group kind (ws-051). An entry of this kind is a group, not a member. */
 export const EXAMPLES_KIND = "examples";
 
+/** The member kind that names another repository's workspace by URL and pinned revision (#3168). */
+export const REPO_KIND = "repo";
+
 /** The data member kind that holds design artifacts (#2549, ws-062). */
 export const DESIGN_KIND = "design";
 
@@ -179,6 +217,15 @@ export const BUILTIN_KINDS: readonly MemberKind[] = [
     outputs: { from: "none" },
     source: "builtin",
   },
+  {
+    name: REPO_KIND,
+    description: "another repository's workspace, named by URL and pinned revision; chant reads it through that repository's own chant workspace graph and never writes there",
+    probe: { repo: true },
+    precedence: 0,
+    shape: "member",
+    outputs: { from: "none" },
+    source: "builtin",
+  },
   {
     name: "other",
     description: "a directory chant does not read; the entry says why in `because`",
@@ -232,7 +279,8 @@ export function builtinKindRegistry(): KindRegistry {
 export function probeKind(kind: MemberKind, tree: WorkspaceTree, dir: string): boolean {
   if ("directory" in kind.probe) return true;
   if ("chantProject" in kind.probe) return holdsChantProject(tree, dir);
-  const { anyFile, anyBlock, anyJsonKey } = kind.probe;
+  if ("repo" in kind.probe) return true;
+  const { anyFile, anyBlock, anyJsonKey, anyLine } = kind.probe;
   if (anyFile && filesMatching(tree, dir, anyFile).length > 0) return true;
   if (anyJsonKey) {
     for (const file of filesMatching(tree, dir, anyJsonKey.in)) {
@@ -244,6 +292,16 @@ export function probeKind(kind: MemberKind, tree: WorkspaceTree, dir: string): b
       }
     }
   }
+  if (anyLine) {
+    const starts = anyLine.starts.map((t) => t.toLowerCase());
+    for (const file of filesMatching(tree, dir, anyLine.in)) {
+      try {
+        if (tree.read(file).split(/\r?\n/).some((l) => starts.some((t) => l.trimStart().toLowerCase().startsWith(t)))) return true;
+      } catch {
+        // An unreadable file is no evidence either way.
+      }
+    }
+  }
   if (anyBlock) {
     const opener = new RegExp(`^\\s*(?:${anyBlock.blocks.map(escapeRegExp).join("|")})\\s*\\{`, "m");
     for (const file of filesMatching(tree, dir, anyBlock.in)) {
@@ -259,7 +317,7 @@ export function probeKind(kind: MemberKind, tree: WorkspaceTree, dir: string): b
 
 /** Whether a probe looks at the directory's files, and so can claim it. */
 function isFileProbe(probe: KindProbe): probe is FileProbe {
-  return !("directory" in probe) && !("chantProject" in probe);
+  return !("directory" in probe) && !("chantProject" in probe) && !("repo" in probe);
 }
 
 /**
@@ -274,7 +332,7 @@ function filesMatching(tree: WorkspaceTree, dir: string, names: readonly string[
     if (!name.includes("*") && tree.stat(joinPath(dir, name)) === "file") out.push(joinPath(dir, name));
   }
   if (globs.length > 0) {
-    const patterns = globs.map((g) => new RegExp(`^${g.split("*").map(escapeRegExp).join("[^/]*")}$`));
+    const patterns = globs.map((g) => new RegExp(`^${g.split("*").map((part) => escapeRegExp(part).replace(/\\\[0-9\\\]/g, "[0-9]")).join("[^/]*")}$`));
     for (const e of tree.list(dir) ?? []) {
       if (e.type === "file" && patterns.some((p) => p.test(e.name))) out.push(joinPath(dir, e.name));
     }
@@ -400,7 +458,7 @@ export function parseKindData(text: string, source: string): KindData {
   const problems: string[] = [];
   const kinds: MemberKind[] = [];
   const seen = new Set<string>();
-  for (const k of (raw as { kinds: { name: string; description: string; precedence: number; probe: FileProbe; outputs?: string[]; graph?: KindGraph; fields?: Record<string, KindField>; reader?: string }[] }).kinds) {
+  for (const k of (raw as { kinds: { name: string; description: string; precedence: number; probe: FileProbe; outputs?: string[]; graph?: KindGraph; fields?: Record<string, KindField>; reader?: string; memberFile?: { path: string; schema: string } }[] }).kinds) {
     if (BUILTIN_KIND_NAMES.includes(k.name)) {
       problems.push(`${source}: kind ${k.name} is built in and can't be supplied by a package`);
       continue;
@@ -417,6 +475,7 @@ export function parseKindData(text: string, source: string): KindData {
         ...(k.probe.anyFile ? { anyFile: [...k.probe.anyFile] } : {}),
         ...(k.probe.anyBlock ? { anyBlock: { in: [...k.probe.anyBlock.in], blocks: [...k.probe.anyBlock.blocks] } } : {}),
         ...(k.probe.anyJsonKey ? { anyJsonKey: { in: [...k.probe.anyJsonKey.in], pointers: [...k.probe.anyJsonKey.pointers] } } : {}),
+        ...(k.probe.anyLine ? { anyLine: { in: [...k.probe.anyLine.in], starts: [...k.probe.anyLine.starts] } } : {}),
       },
       precedence: k.precedence,
       shape: "member",
@@ -425,6 +484,7 @@ export function parseKindData(text: string, source: string): KindData {
       ...(k.graph ? { graph: { lexicon: k.graph.lexicon, config: structuredClone(k.graph.config) } } : {}),
       ...(k.fields ? { fields: structuredClone(k.fields) } : {}),
       ...(k.reader && (KIND_LINK_READERS as readonly string[]).includes(k.reader) ? { reader: k.reader as KindLinkReaderName } : {}),
+      ...(k.memberFile ? { memberFile: { path: k.memberFile.path, schema: k.memberFile.schema } } : {}),
     });
     if (k.reader && !(KIND_LINK_READERS as readonly string[]).includes(k.reader)) {
       problems.push(`${source}: kind ${k.name} names link reader ${k.reader}, which this chant does not have (it has ${KIND_LINK_READERS.join(", ")}); the kind is kept, and its members' links are only those their entries state`);
@@ -477,6 +537,10 @@ export function readPackageKinds(packageDir: string, source?: string): PackageKi
   const packageName = typeof pkg.name === "string" ? pkg.name : undefined;
   for (const k of data.kinds) {
     k.packageDir = packageDir;
+    if (k.memberFile) {
+      const problem = loadMemberFileSchema(k.memberFile, packageDir);
+      if (problem) data.problems.push(`${name}: kind ${k.name} ${problem}; members of the kind fail WSP012 until it is fixed`);
+    }
     if (k.graph && packageName !== lexiconPackageName(k.graph.lexicon)) {
       data.problems.push(
         `${name}: kind ${k.name} reads its members with lexicon ${k.graph.lexicon}, which is ${lexiconPackageName(k.graph.lexicon)}, ` +
@@ -488,6 +552,67 @@ export function readPackageKinds(packageDir: string, source?: string): PackageKi
   return { ...data, file };
 }
 
+/**
+ * Read and compile a kind's member-file schema from `packageDir` (#3672),
+ * setting `schemaFile` and `validate`. Returns why it can't be used, or
+ * undefined. The schema is a JSON file inside the package; it is data, so
+ * nothing is imported, and a `$ref` outside the file is not followed.
+ */
+export function loadMemberFileSchema(memberFile: KindMemberFile, packageDir: string): string | undefined {
+  const file = resolve(packageDir, ...memberFile.schema.split("/"));
+  memberFile.schemaFile = file;
+  const inside = relative(packageDir, file);
+  if (inside.startsWith("..") || isAbsolute(inside)) return `names member-file schema ${memberFile.schema}, which is outside the package`;
+  let doc: unknown;
+  try {
+    doc = JSON.parse(readFileSync(file, "utf-8"));
+  } catch (err) {
+    const missing = (err as NodeJS.ErrnoException).code === "ENOENT";
+    return missing ? `names member-file schema ${memberFile.schema}, which does not exist` : `names member-file schema ${memberFile.schema}, which is not JSON (${(err as Error).message})`;
+  }
+  if (doc === null || typeof doc !== "object" || Array.isArray(doc)) return `names member-file schema ${memberFile.schema}, which is not a JSON Schema object`;
+  try {
+    const Ajv = loadAjv2020() as new (opts: object) => { compile(s: object): MemberFileValidate };
+    memberFile.validate = new Ajv({ allErrors: true, strict: false }).compile(doc);
+  } catch (err) {
+    return `names member-file schema ${memberFile.schema}, which does not compile as a draft 2020-12 schema (${(err as Error).message})`;
+  }
+  return undefined;
+}
+
+/** One reason a member's file fails its kind's schema (#3672): a JSON Pointer into the file, and why. */
+export interface MemberFileProblem {
+  pointer: string;
+  message: string;
+}
+
+/**
+ * Check a member's file text against its kind's schema (#3672). `file` is the
+ * file's name, which picks the parser: YAML for `.yml` and `.yaml`, JSON
+ * otherwise. The kind's schema must have loaded; when it didn't, WSP002 has
+ * already said why, and this returns nothing.
+ */
+export function checkMemberFile(memberFile: KindMemberFile, file: string, text: string): MemberFileProblem[] {
+  if (!memberFile.validate) return [];
+  let data: unknown;
+  try {
+    data = /\.ya?ml$/i.test(file) ? yaml.load(text) : JSON.parse(text);
+  } catch (err) {
+    return [{ pointer: "", message: `is not ${/\.ya?ml$/i.test(file) ? "YAML" : "JSON"} (${(err as Error).message.split("\n")[0]})` }];
+  }
+  if (memberFile.validate(data)) return [];
+  const seen = new Set<string>();
+  const out: MemberFileProblem[] = [];
+  for (const e of memberFile.validate.errors ?? []) {
+    const extra = e.params && typeof e.params.additionalProperty === "string" ? ` (${e.params.additionalProperty})` : "";
+    const message = `${e.instancePath || "the file"} ${e.message ?? "is invalid"}${extra}`;
+    if (seen.has(message)) continue;
+    seen.add(message);
+    out.push({ pointer: e.instancePath, message });
+  }
+  return out;
+}
+
 /** The package a lexicon name resolves to. */
 export function lexiconPackageName(lexicon: string): string {
   return `@intentius/chant-lexicon-${lexicon}`;

package/src/workspace/ledger.schema.json

@@ -0,0 +1,158 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/ledger/v1/ledger.schema.json",
+  "title": "chant ledger output",
+  "description": "What `chant ledger <table> --json` prints (#4363): the rows of one ledger on the local chant/lifecycle branch, filtered with typed filters instead of SQL. The tables and columns are the ones `chant query` loads (schema version 1 of its tables); a column chant query keeps as JSON text is an object or array here, and `signed` and `empty` are booleans. It reads the local branch and never fetches. Version 1 of the read contract. Readers ignore fields they do not know; a field is only ever added within a version. The codes are a closed list, each in the one closed list of `reason-codes.ts`.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "type": "object",
+      "description": "The rows that every filter matched. Exit code 0.",
+      "required": [
+        "$schema",
+        "contract",
+        "table",
+        "columns",
+        "at",
+        "filter",
+        "total",
+        "rows",
+        "malformed"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/ledger/v1/ledger.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "table": {
+          "enum": [
+            "resources",
+            "snapshots",
+            "runs",
+            "gates",
+            "deploys",
+            "releases",
+            "cuts"
+          ],
+          "description": "The table read: resources and snapshots from each lexicon's snapshots, runs from the Op run ledgers, gates from _gates/, deploys from <env>/releases.jsonl, releases and cuts from _releases/."
+        },
+        "columns": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The table's columns, in order. Every row has each of them."
+        },
+        "at": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The revision of chant/lifecycle read (--at), as given, or null for the branch tip."
+        },
+        "filter": {
+          "type": "object",
+          "required": [
+            "where",
+            "since"
+          ],
+          "properties": {
+            "where": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Each --where clause, <field><op><value>, as given. Every one held for each row listed."
+            },
+            "since": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "description": "--since as the ISO instant it was read as, or null. The rows whose time column (observed_at, started or timestamp) is at or after it are listed."
+            }
+          }
+        },
+        "total": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Rows in the table before the filter."
+        },
+        "rows": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/row"
+          }
+        },
+        "malformed": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Lines and files of this table that could not be read as their kind, left out of total and rows."
+        }
+      }
+    },
+    "row": {
+      "type": "object",
+      "description": "One row, keyed by column. Every row starts with member: the workspace member whose ledger it came from, or null outside a workspace. A value is a string, a number, a boolean, an object or array (a JSON column), or null.",
+      "required": [
+        "member"
+      ],
+      "additionalProperties": {
+        "type": [
+          "string",
+          "number",
+          "boolean",
+          "object",
+          "array",
+          "null"
+        ]
+      }
+    },
+    "failure": {
+      "type": "object",
+      "description": "Nothing was read. Exit code 1.",
+      "required": [
+        "$schema",
+        "contract",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/ledger/v1/ledger.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "filter-invalid",
+                "table-unknown",
+                "revision-unknown",
+                "ledger-unreadable"
+              ]
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}