@intentius/chant 0.93.0 → 0.95.0

package/src/workspace/status-stewards.ts

@@ -16,19 +16,27 @@
  *   is the Op's own `labels.Env` or `local`;
  * - `waiting` lists the open decision points the steward waits on (#2749):
  *   each Op whose newest run is the steward's own and stopped on a question,
- *   as the run ledger records it. The question's state now is `points`'s;
+ *   as the run ledger records it. The question's state now is `points`'s.
+ *   A run is the steward's when its record names it (`steward`, written for
+ *   a run started in the steward's turn or under `CHANT_STEWARD`), so this
+ *   also covers the member's other Ops, those no steward lists, that such a
+ *   run belongs to, such as an Op the steward's process starts itself;
  * - `lease` is the local steward's own lease ref
  *   (`refs/chant/lease/[<prefix>]_stewards/<name>`), present while a
  *   `chant operator --steward` holds it or until it expires;
  * - an Op's `workLease.held` is the work leases its turns hold (#2748): those
  *   whose holder is `<steward>/<op>@...` (`stewardWorkHolder`), read from the
- *   ledger of the Op's work kind, or the member's own.
+ *   ledger of the Op's work kind, or the member's own;
+ * - an Op the steward runs beside its turns (#2861) has `beside`: whether it
+ *   declares a ready step, and the Op's own lease
+ *   (`refs/chant/lease/[<prefix>]<op>`), which a run of it holds while it runs.
+ *   Its waiting run and its work leases are listed as for any of its Ops.
  */
 
 import { existsSync, realpathSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
-import { discoverStewards } from "../op/discover";
-import { stewardFormFor, stewardLeaseName, type StewardForm } from "../op/steward";
+import { discoverOps, discoverStewards } from "../op/discover";
+import { stewardBesideFor, stewardFormFor, stewardLeaseName, type StewardForm } from "../op/steward";
 import { readRunLedger, runEnvOf } from "../lifecycle/run-ledger";
 import { readConvergeLedger, type ConvergeTickRecord } from "../lifecycle/converge-ledger";
 import { leaseRef } from "../lifecycle/lease";
@@ -119,6 +127,21 @@ export interface StatusStewardOp {
    * the steward's turns of this Op hold, a live one while a turn runs.
    */
   workLease: { kind: string | null; held: StatusStewardWorkLease[] } | null;
+  /**
+   * For an Op the steward runs beside its turns (#2861): whether a ready step
+   * says when to start it, and the Op's own lease, which a run of it holds
+   * while it runs (null when none has held it). Null for an Op run as one of
+   * the steward's turns.
+   */
+  beside: { ready: boolean; lease: StatusStewardLease | null } | null;
+}
+
+/** A lease ref as status reads it: locally, never fetched. `live` is false once `expiresAt` has passed. */
+export interface StatusStewardLease {
+  holder: string;
+  acquiredAt: string;
+  expiresAt: string;
+  live: boolean;
 }
 
 /** A work lease a steward's turn holds (#2748). */
@@ -148,11 +171,13 @@ export interface StatusSteward {
    */
   capabilities: { name: string; broker: string | null; declared: boolean }[];
   /** The local steward's own lease, or null when no local operator has held it. */
-  lease: { holder: string; acquiredAt: string; expiresAt: string; live: boolean } | null;
+  lease: StatusStewardLease | null;
   ops: StatusStewardOp[];
   /**
    * The open decision points the steward waits on (#2749): each Op whose
-   * newest run is the steward's own and stopped on a question.
+   * newest run is the steward's own and stopped on a question. Its declared
+   * Ops come first, in `ops` order, then any other Op of the member whose
+   * newest run names the steward, by Op name.
    */
   waiting: (StatusStewardWait & { op: string; run: string })[];
 }
@@ -200,10 +225,11 @@ function isChantProject(dir: string): boolean {
   return existsSync(join(dir, "chant.config.ts")) || existsSync(join(dir, "chant.config.json"));
 }
 
-async function readStewardLease(name: string, memberDir: string, now: string): Promise<StatusSteward["lease"]> {
+/** A lease ref of the member, by its lease name (`_stewards/<name>`, or an Op's). */
+async function readLeaseRef(leaseName: string, memberDir: string, now: string): Promise<StatusStewardLease | null> {
   try {
     const { prefix } = await resolveMemberLedger(memberDir);
-    const sha = await readRefSha(leaseRef(stewardLeaseName(name), prefix), { cwd: memberDir });
+    const sha = await readRefSha(leaseRef(leaseName, prefix), { cwd: memberDir });
     if (!sha) return null;
     const record = JSON.parse((await readBlobBySha(sha, { cwd: memberDir })) ?? "") as Record<string, unknown>;
     if (typeof record.holder !== "string" || typeof record.expiresAt !== "string" || typeof record.acquiredAt !== "string") return null;
@@ -218,6 +244,18 @@ async function readStewardLease(name: string, memberDir: string, now: string): P
   }
 }
 
+/** An Op's `beside` entry (#2861): null for an Op run as one of the steward's turns. */
+async function besideOf(
+  declaration: Parameters<typeof stewardBesideFor>[0],
+  op: string,
+  memberDir: string,
+  now: string,
+): Promise<StatusStewardOp["beside"]> {
+  const beside = stewardBesideFor(declaration, op);
+  if (!beside) return null;
+  return { ready: beside.ready !== null && beside.ready !== undefined, lease: await readLeaseRef(op, memberDir, now) };
+}
+
 /** The work leases `steward`'s turns of `op` hold, from the ledger of the Op's kind or the member's. */
 async function readHeldWorkLeases(steward: string, op: OpConfig, memberDir: string, now: string): Promise<StatusStewardWorkLease[]> {
   try {
@@ -308,6 +346,7 @@ export async function readMemberStewards(
         workLease: op.workLease
           ? { kind: op.workLease.kind ?? null, held: await readHeldWorkLeases(declaration.name, op, memberDir, now) }
           : null,
+        beside: await besideOf(declaration, op.name, memberDir, now),
       });
     }
     stewards.push({
@@ -320,10 +359,50 @@ export async function readMemberStewards(
         const declared = box?.capabilities.find((c) => c.name === name);
         return { name, broker: declared?.broker ?? null, declared: declared !== undefined };
       }),
-      lease: await readStewardLease(declaration.name, memberDir, now),
+      lease: await readLeaseRef(stewardLeaseName(declaration.name), memberDir, now),
       ops,
       waiting,
     });
   }
+  if (stewards.length > 0) await addUndeclaredWaits(memberDir, stewards, found, reasons);
   return { stewards, reasons };
 }
+
+/**
+ * The waiting runs of the member's Ops that no steward lists, each under the
+ * steward its record names. A steward's process can start an Op itself
+ * with `CHANT_STEWARD` set (studio#137), and the run ledger then records
+ * the run as the steward's though the declaration does not list the Op.
+ * Import failures are left out here: `discoverStewards` read the same files
+ * and reported them as `stewards-unreadable`.
+ */
+async function addUndeclaredWaits(
+  memberDir: string,
+  stewards: StatusSteward[],
+  found: Awaited<ReturnType<typeof discoverStewards>>["stewards"],
+  reasons: MemberStewards["reasons"],
+): Promise<void> {
+  const declared = new Set([...found.values()].flatMap(({ declaration }) => declaration.ops.map((op) => op.name)));
+  let ops: OpConfig[];
+  try {
+    ops = [...(await discoverOps({ cwd: memberDir })).ops.values()].map((d) => d.config).filter((op) => !declared.has(op.name));
+  } catch {
+    return;
+  }
+  const byName = new Map(stewards.map((s) => [s.name, s]));
+  for (const op of ops.sort((a, b) => a.name.localeCompare(b.name))) {
+    const opEnv = runEnvOf(op);
+    try {
+      const newest = (await readRunLedger(opEnv, op.name, { cwd: memberDir })).records.at(-1);
+      const steward = newest?.steward ? byName.get(newest.steward) : undefined;
+      if (steward && newest?.status === "waiting" && newest.point) {
+        steward.waiting.push({ op: op.name, run: newest.id, ...waitOf(newest.point) });
+      }
+    } catch (err) {
+      reasons.push({
+        code: "steward-runs-unreadable",
+        message: `${opEnv}/runs__${op.name}.jsonl: ${err instanceof Error ? err.message.split("\n")[0] : String(err)}`,
+      });
+    }
+  }
+}

package/src/workspace/status.schema.json

@@ -200,11 +200,11 @@
           ]
         },
         "ops": {
-          "description": "The Ops it runs, in declaration order.",
+          "description": "The Ops it runs, in declaration order: its turns' Ops, then those it runs beside its turns (#2861).",
           "type": "array",
           "items": {
             "type": "object",
-            "required": ["name", "schedule", "env", "lastRun", "lastTick", "changesCheckout", "workLease"],
+            "required": ["name", "schedule", "env", "lastRun", "lastTick", "changesCheckout", "workLease", "beside"],
             "properties": {
               "name": { "type": "string" },
               "schedule": {
@@ -330,12 +330,40 @@
                     }
                   }
                 ]
+              },
+              "beside": {
+                "description": "For an Op the steward runs beside its turns (#2861), in a process of its own under the Op's own lease: ready is whether a ready step says when the operator starts it, and lease is the Op's lease ref (refs/chant/lease/<op>), held by a run of it while it runs (holder <steward>/<op>@<operator> for a run the operator started), read locally and never fetched, or null when none has held it. live is false once expiresAt has passed. Null for an Op the steward runs as one of its turns.",
+                "oneOf": [
+                  { "type": "null" },
+                  {
+                    "type": "object",
+                    "required": ["ready", "lease"],
+                    "properties": {
+                      "ready": { "type": "boolean" },
+                      "lease": {
+                        "oneOf": [
+                          { "type": "null" },
+                          {
+                            "type": "object",
+                            "required": ["holder", "acquiredAt", "expiresAt", "live"],
+                            "properties": {
+                              "holder": { "type": "string" },
+                              "acquiredAt": { "type": "string" },
+                              "expiresAt": { "type": "string" },
+                              "live": { "type": "boolean" }
+                            }
+                          }
+                        ]
+                      }
+                    }
+                  }
+                ]
               }
             }
           }
         },
         "waiting": {
-          "description": "The open decision points the steward waits on (#2749): one for each of its Ops whose newest run is the steward's own and stopped on a question, in ops order. The state is the question's when the run stopped; `chant workspace points --open` has its state now, and hud asks a person there. The steward never answers one, and runs the Op again on the first round after it is answered.",
+          "description": "The open decision points the steward waits on (#2749): one for each Op whose newest run is the steward's own (its ledger record names the steward) and stopped on a question: the steward's own Ops in ops order, then any other Op of the member, such as one the steward's process starts itself (studio#137), by name. The state is the question's when the run stopped; `chant workspace points --open` has its state now, and hud asks a person there. The steward never answers one, and runs an Op it lists again on the first round after it is answered (an Op beside its turns, in a process of its own, #2861).",
           "type": "array",
           "items": {
             "allOf": [
@@ -362,10 +390,44 @@
         "since": { "type": "string", "description": "When the run stopped on it." }
       }
     },
+    "intent": {
+      "type": "object",
+      "required": ["id", "state", "question", "choice", "answer", "decided_by", "decided_on"],
+      "properties": {
+        "id": { "type": "string", "description": "The record's id, as the box block names it." },
+        "state": { "type": ["string", "null"], "description": "The record's state as written, such as proposed or decided, or null when no decision record has the id." },
+        "question": { "type": ["string", "null"], "description": "The question the record answers." },
+        "choice": { "description": "The record's choice as written, such as { option, reason }, or null while the record is proposed." },
+        "answer": { "type": ["string", "null"], "description": "The chosen option's label, from options[]'s entry whose id is choice.option, or null while no option is chosen (#2855). Added by chant 0.94.0." },
+        "decided_by": { "type": ["string", "null"], "description": "Who decided it, or null while it is proposed." },
+        "decided_on": { "type": ["string", "null"], "description": "The day it was decided, or null while it is proposed." }
+      }
+    },
     "box": {
       "type": "object",
-      "required": ["capabilities", "isolation"],
+      "required": ["capabilities", "isolation", "intent", "services"],
       "properties": {
+        "services": {
+          "description": "The services the box block declares (#2880), in declaration order, or empty when it declares none. A reader has them before any converge tick; a steward's ConvergeOp's lastTick carries each one's verdict. cmd is as declared: its ${VAR} references are left for the process that applies it to expand. Added by chant 0.95.0.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "cmd", "needs", "httpPort", "duration", "health", "optional"],
+            "properties": {
+              "name": { "type": "string" },
+              "cmd": { "type": "string", "description": "The command the supervisor runs, as declared." },
+              "needs": { "type": "array", "items": { "type": "string" }, "description": "Services of the same box that start first. Empty when none." },
+              "httpPort": { "type": ["integer", "null"], "description": "The port the supervisor routes the sprite's URL to, or null." },
+              "duration": { "type": ["string", "null"], "description": "How long the service must stay up after a create or start, such as 3s, or null for the supervisor's default." },
+              "health": { "type": ["string", "null"], "description": "A URL that answers 200 while the service works, or null when the supervisor's state decides." },
+              "optional": { "type": "boolean", "description": "True for a service something else creates by name, such as a site a release makes." }
+            }
+          }
+        },
+        "intent": {
+          "description": "The decision record the box block names as the box's intent (#2850), or null when it names none. A box starts as a question: the record is proposed with a null choice, and decided when the person who answered it amends it. Read from the working tree, from the declared record kinds named decision. When no decision record has the id, every field but id is null and chant workspace check fails (WSP126). Added by chant 0.94.0.",
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/intent" }]
+        },
         "isolation": {
           "description": "The box's isolation resolved from its identity, its host, the member's name and its slot (#2727), or null when the block declares no host. A runtime that plants or starts the box sets these values instead of choosing its own. The same for every environment.",
           "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/isolation" }]

package/src/workspace/status.ts

@@ -43,6 +43,7 @@ import { readReleasePlan, type ReleasePlan } from "../lifecycle/plan-ledger";
 import { listWorkLeases, type WorkLeaseState } from "../lifecycle/work-lease";
 import { findWorkspaceRoot } from "../project-root";
 import { resolveBoxes, type ResolvedIsolation } from "./box-isolation";
+import { resolveBoxIntents, unresolvedIntent, type BoxIntent } from "./box-intent";
 import { declaredRecordKinds, readDeclaration, readerVersion, WorkspaceReadError, type Declaration, type ErrorLocation, type Member } from "./declaration";
 import type { ReasonCode } from "./reason-codes";
 import { GATE_REASON_CODES, readMemberGates, type GateLedgerReader, type StatusGate, type StatusGateLedger } from "./status-gates";
@@ -178,6 +179,26 @@ export interface StatusBox {
   capabilities: { name: string; broker: string | null; scope: string[] }[];
   /** The box's ports, state paths and cookie names, resolved from its identity, or null when the block declares no host (#2727). */
   isolation: ResolvedIsolation | null;
+  /**
+   * The decision record the block names as the box's intent (#2850): its id,
+   * state, question, choice, answer (the chosen option's label), decided_by
+   * and decided_on. Null when the block names none; every field but the id
+   * is null when no decision record has the id (WSP126).
+   */
+  intent: BoxIntent | null;
+  /** The services the block declares (#2880), in file order, so a reader has them before any converge tick. Empty when it declares none. */
+  services: StatusBoxService[];
+}
+
+/** A declared box service as `status --json` prints it (#2880): every field present, null or false when not declared. */
+export interface StatusBoxService {
+  name: string;
+  cmd: string;
+  needs: string[];
+  httpPort: number | null;
+  duration: string | null;
+  health: string | null;
+  optional: boolean;
 }
 
 /**
@@ -377,6 +398,7 @@ export async function workspaceStatus(query: StatusQuery): Promise<StatusDocumen
     const now = query.now ?? new Date().toISOString();
 
     const isolation = new Map(resolveBoxes(declaration).map((b) => [b.member.name, b.isolation]));
+    const intents = new Map((await resolveBoxIntents(declaration, found.dir)).map((i) => [i.member, i.record?.intent ?? unresolvedIntent(i.id)]));
     const members: StatusMember[] = [];
     for (const m of declaration.members) {
       const environments: StatusEnvironment[] = [];
@@ -399,6 +421,16 @@ export async function workspaceStatus(query: StatusQuery): Promise<StatusDocumen
             : {
                 capabilities: m.box.capabilities.map((c) => ({ name: c.name, broker: c.broker, scope: [...c.scope] })),
                 isolation: isolation.get(m.name) ?? null,
+                intent: intents.get(m.name) ?? null,
+                services: m.box.services.map((s) => ({
+                  name: s.name,
+                  cmd: s.cmd,
+                  needs: [...s.needs],
+                  httpPort: s.httpPort,
+                  duration: s.duration,
+                  health: s.health,
+                  optional: s.optional,
+                })),
               },
         stewards: stewards.stewards,
         stewardReasons: stewards.reasons,

package/src/workspace/trust/record-seal.test.ts

@@ -199,7 +199,7 @@ describe.skipIf(!hasSshKeygen)("author seals under a signers file at base", () =
     const doc = await amend(r, { evidence: [] });
     if ("error" in doc) throw new Error(doc.error.message);
     expect(doc.changed).toEqual(["evidence", "seal"]);
-    expect(doc.sealDropped).toMatch(/ws-003 was sealed by lex00, and the amendment moves its digest, so the seal was removed: seal it again with records amend ws-003 --sign/);
+    expect(doc.sealDropped).toMatch(/ws-003 was sealed by lex00, and the amendment moves its digest or its state, so the seal was removed: seal it again with records amend ws-003 --sign/);
     expect(readFileSync(join(r.dir, FILE), "utf-8")).not.toMatch(/^seal:/m);
     // Changing only the reviews leaves the digest, so the seal stays.
     await amend(r, {}, lex);
@@ -215,6 +215,30 @@ describe.skipIf(!hasSshKeygen)("author seals under a signers file at base", () =
     expect(warningCodes(rec)).toContain("record-unattested");
   });
 
+  test("a move of state alone drops the seal, which signs the state though the digest leaves it out (#2873)", async () => {
+    const { r, lex } = workspace("state");
+    await amend(r, {}, lex);
+    const digest = (await record(r)).digest;
+    const doc = await amend(r, { state: "superseded" });
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(doc.changed).toEqual(["state", "seal"]);
+    expect(doc.sealDropped).toMatch(/moves its digest or its state/);
+    expect((await record(r)).digest).toBe(digest);
+  });
+
+  test("ratifying counts only verdicts whose seal verifies against the signers at base (#2873)", async () => {
+    const { r, alice, mallory } = workspace("ratify");
+    for (const k of [alice, mallory]) {
+      const by = k === alice ? "alice@example.test" : "mallory";
+      const doc = await reviewRecord({ kind: KIND, id: "ws-003", verdict: "agree", by, sign: k.file, cwd: r.dir });
+      if ("error" in doc) throw new Error(doc.error.message);
+    }
+    const refused = await amend(r, { state: "ratified" });
+    expect("error" in refused && refused.error.code).toBe("ratify-quorum-not-met");
+    expect("error" in refused && refused.error.message).toMatch(/needs 2 agreeing verdicts that count, and it has 1 \(not counted: mallory, review-unattested\)/);
+    expect(readFileSync(join(r.dir, FILE), "utf-8")).toMatch(/^state: "decided"$/m);
+  });
+
   test("a stale seal left by hand fails, and an edited state fails", async () => {
     const { r, lex } = workspace("stale");
     await amend(r, {}, lex);
@@ -308,7 +332,7 @@ describe.skipIf(!hasSshKeygen)("refusals", () => {
     expect("error" in from && from.error.code).toBe("write-input-invalid");
     expect(readFileSync(join(r.dir, FILE), "utf-8")).toBe(before);
 
-    await amend(r, { state: "ratified" });
+    await amend(r, { state: "superseded" });
     const closed = await amend(r, {}, lex);
     expect("error" in closed && closed.error.code).toBe("record-closed");
   });

package/src/workspace/work-evidence.schema.json

@@ -181,6 +181,7 @@
                 "record-closed",
                 "amend-supersede-instead",
                 "record-sign-failed",
+                "ratify-quorum-not-met",
                 "record-unparseable",
                 "record-schema-invalid",
                 "record-id-duplicate",

package/src/workspace/{work-readiness-chud.test.ts → work-readiness.test.ts}

@@ -1,11 +1,10 @@
 /**
- * The work kind's `ready`/`blockedBy` against chud's ready queue (ws-055,
- * #2734).
- *
- * chud's `readyQueue` (packages/runtime/src/ready.mjs at jhgaylor/chud
- * 43afcf1) puts a contract in the ready set once it is approved and in
- * force, every `depends_on` id is `met` (drivers.mjs's `memberState`), and no
- * unit is open against it; a contract that is itself met leaves the queue.
+ * The work kind's `ready`/`blockedBy` against a reference ready-queue rule
+ * (ws-055, #2734), ported from chud's `readyQueue`
+ * (packages/runtime/src/ready.mjs at jhgaylor/chud 43afcf1): a contract
+ * enters the ready set once it is approved and in force, every `depends_on`
+ * id is `met` (drivers.mjs's `memberState`), and no unit is open against it;
+ * a contract that is itself met leaves the queue.
  *
  * Of those rules, the work kind's `ready` and `blockedBy` (work.ts) can
  * express two directly, with no new field:
@@ -17,22 +16,21 @@
  *   retired contract does.
  * - a record that is itself already `done` (or `dropped`, or merely
  *   `in-progress`) is not `ready`: `ready` requires `state === "open"`, the
- *   same "already met/already running leaves the queue" rule ready.mjs
- *   states for a contract that is itself met.
+ *   same "already met/already running leaves the queue" rule the reference
+ *   rule states for a contract that is itself met.
  *
- * The rules ready.mjs adds on top -- approval before a dependency counts
- * (memberState's draft/failing cases), re-checking that a `met` dependency's
- * newest evidence still passes, and refusing a contract while a unit is open
- * against it -- have no equivalent in a `needs` link. The full table of
- * every ready.mjs rule and its home (a `needs` link, the runner, or "not
+ * The rules the reference rule adds on top -- approval before a dependency
+ * counts (memberState's draft/failing cases), re-checking that a `met`
+ * dependency's newest evidence still passes, and refusing a contract while a
+ * unit is open against it -- have no equivalent in a `needs` link. The full
+ * table of every rule and its home (a `needs` link, the runner, or "not
  * applicable") is on INTENTIUS/chant#2734.
  *
- * This fixture mirrors a small chud contract graph as work items and checks
- * `queryRecords`'s `ready`/`blockedBy` against a minimal, local
- * re-implementation of the expressible subset of ready.mjs's rule (met
- * depends_on, self not already met), so a regression in either the work
- * kind's readiness formula or this reading of ready.mjs's rule shows up as a
- * mismatch.
+ * This fixture mirrors a small reference contract graph as work items and
+ * checks `queryRecords`'s `ready`/`blockedBy` against a minimal, local
+ * re-implementation of the expressible subset of that rule (met depends_on,
+ * self not already met), so a regression in either the work kind's readiness
+ * formula or this reading of the reference rule shows up as a mismatch.
  */
 
 import { readFileSync } from "node:fs";
@@ -63,13 +61,13 @@ function work(id: string, fields: Record<string, unknown>): string {
 }
 
 /**
- * The expressible subset of ready.mjs's rule, on a graph shaped like
+ * The expressible subset of the reference rule, on a graph shaped like
  * `depends_on`: ready once the item is `open` (not already met, not already
- * running) and every dependency is `done` (chud's "met"). A dependency that
- * is `dropped` never becomes done, so it blocks forever -- the same effect
- * ready.mjs gets from a retired dependency.
+ * running) and every dependency is `done` (the reference rule's "met"). A
+ * dependency that is `dropped` never becomes done, so it blocks forever --
+ * the same effect the reference rule gets from a retired dependency.
  */
-function chudReadyIsh(items: { id: string; state: string; needs: string[] }[]): { ready: Set<string>; blockedBy: Map<string, string[]> } {
+function referenceReadyIsh(items: { id: string; state: string; needs: string[] }[]): { ready: Set<string>; blockedBy: Map<string, string[]> } {
   const stateOf = new Map(items.map((i) => [i.id, i.state]));
   const ready = new Set<string>();
   const blockedBy = new Map<string, string[]>();
@@ -90,13 +88,13 @@ beforeAll(() => {
     "decisions/decision.schema.json": readFileSync(join(REF, "decisions", "decision.schema.json"), "utf-8"),
     "work/work.kind.mjs": readFileSync(join(REF, "work", "work.kind.mjs"), "utf-8"),
     "work/work.schema.json": readFileSync(join(REF, "work", "work.schema.json"), "utf-8"),
-    // W-001: already done, so it leaves the ready queue -- ready.mjs's "a
-    // contract that is itself met is done, not ready".
+    // W-001: already done, so it leaves the ready queue -- the reference
+    // rule's "a contract that is itself met is done, not ready".
     "work/W-001-base.md": work("W-001", { state: "done", closed_on: "2026-09-24", evidence: [{ title: "shipped", url: "https://example.com/w1" }] }),
     // W-002: needs W-001, which is done -- both rules agree this is ready.
     "work/W-002-after-base.md": work("W-002", { needs: ["W-001"] }),
     // W-003: needs W-004, which is dropped and so never turns done -- blocked
-    // forever, the same as a retired dependency in ready.mjs.
+    // forever, the same as a retired dependency in the reference rule.
     "work/W-003-needs-dropped.md": work("W-003", { needs: ["W-004"] }),
     "work/W-004-dropped.md": work("W-004", { state: "dropped", closed_on: "2026-09-24" }),
     // W-005: needs W-002, which is open (not done yet) -- blocked.
@@ -111,22 +109,22 @@ beforeAll(() => {
 });
 afterAll(cleanScratch);
 
-describe("work kind ready/blockedBy vs. chud's ready queue, expressible rules (#2734)", () => {
+describe("work kind ready/blockedBy vs. a reference ready-queue rule, expressible rules (#2734)", () => {
   test("matches on every item, for the rules a needs link can express", async () => {
     const doc = await queryRecords({ kind: WORK, cwd: root });
     if ("error" in doc) throw new Error(doc.error.message);
     expect(doc.summary).toEqual({ total: 7, valid: 7, invalid: 0, superseded: 0 });
 
     const items = doc.records.map((r) => ({ id: r.id!, state: r.state!, needs: (r.data as { needs?: string[] }).needs ?? [] }));
-    const chud = chudReadyIsh(items);
+    const reference = referenceReadyIsh(items);
 
     for (const r of doc.records) {
       const id = r.id!;
-      expect(r.ready, `${id}.ready`).toBe(chud.ready.has(id));
+      expect(r.ready, `${id}.ready`).toBe(reference.ready.has(id));
       expect(
         (r.blockedBy ?? []).map((b) => b.id),
         `${id}.blockedBy`,
-      ).toEqual(chud.blockedBy.get(id));
+      ).toEqual(reference.blockedBy.get(id));
     }
   });
 

package/src/workspace/work.test.ts

@@ -370,6 +370,13 @@ describe("writing work items on a copy of the reference workspace (#2683)", () =
     expect("error" in doc && doc.error.code).toBe("record-schema-invalid");
   });
 
+  test("records new refuses an ask source with no said or by (#2851)", async () => {
+    const noSaid = await newRecord({ kind: "work/work.kind.mjs", fields: fresh({ source: { ask: { by: "morgan", at: "2026-09-25T10:00:00Z", via: "hud" } } }), dryRun: true, cwd: copy });
+    expect("error" in noSaid && noSaid.error.code).toBe("record-schema-invalid");
+    const noBy = await newRecord({ kind: "work/work.kind.mjs", fields: fresh({ source: { ask: { said: "Can we add a dark mode toggle?", at: "2026-09-25T10:00:00Z", via: "hud" } } }), dryRun: true, cwd: copy });
+    expect("error" in noBy && noBy.error.code).toBe("record-schema-invalid");
+  });
+
   test("records new with a fresh prefix takes --prefix W", async () => {
     const doc = await newRecord({ kind: "work/work.kind.mjs", fields: fresh(), prefix: "W", dryRun: true, cwd: copy });
     expect(doc).toMatchObject({ id: "W-004" });
@@ -388,4 +395,14 @@ describe("writing work items on a copy of the reference workspace (#2683)", () =
     const doc = await reviewRecord({ kind: "work/work.kind.mjs", id: "W-003", verdict: "agree", by: "alice", cwd: copy });
     expect("error" in doc && doc.error.code).toBe("review-unsupported");
   });
+
+  test("records new with an ask source round-trips through records --json (#2851)", async () => {
+    const ask = { said: "Can we add a dark mode toggle to the wireframe?", by: "morgan", at: "2026-09-25T10:00:00Z", via: "hud", session: "hud-9f2" };
+    const doc = await newRecord({ kind: resolveWriteKind("work", copy), fields: fresh({ source: { ask } }), cwd: copy });
+    if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+    const read = await queryRecords({ kind: "work/work.kind.mjs", cwd: copy });
+    records.expectValid(read);
+    if ("error" in read) throw new Error(read.error.message);
+    expect(read.records.find((r) => r.id === doc.id)).toMatchObject({ valid: true, data: { source: { ask } } });
+  });
 });

package/src/workspace/workspace-kinds.schema.json

@@ -72,6 +72,9 @@
             "maxLength": 255,
             "pattern": "^[^\\u0000-\\u001f]+$"
           }
+        },
+        "graph": {
+          "$ref": "#/$defs/graph"
         }
       },
       "patternProperties": {
@@ -128,6 +131,29 @@
       "type": "string",
       "description": "A file name, with no directory part. A * matches any run of characters.",
       "pattern": "^(?!\\.\\.?$)[^/\\\\]+$"
+    },
+    "graph": {
+      "type": "object",
+      "description": "How chant workspace graph reads a member of this kind (#2874). chant writes a reader project of its own outside the workspace, with a chant.config.json that declares lexicon and puts config under that lexicon's key, and runs the member's chant graph there. In every string key and value of config, {member} becomes the member's name, {dir} its absolute directory and {workspace} the absolute workspace root. Without this field a member of the kind is listed with kind-not-run.",
+      "required": [
+        "lexicon",
+        "config"
+      ],
+      "properties": {
+        "lexicon": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]{0,39}$",
+          "description": "The lexicon that reads the member, by name. The package that supplies the kind must be @intentius/chant-lexicon-<lexicon>, so the lexicon chant loads is the one the declaration pins."
+        },
+        "config": {
+          "type": "object",
+          "description": "The lexicon's config namespace for the reader project, such as terraform's roots. Placeholders are substituted; nothing else is interpreted."
+        }
+      },
+      "patternProperties": {
+        "^x-": true
+      },
+      "additionalProperties": false
     }
   }
 }