@intentius/chant 0.110.0 → 0.112.0

package/src/workspace/member-write.schema.json

@@ -0,0 +1,193 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/member-write/v1/member-write.schema.json",
+  "title": "chant workspace member add|remove and host set output",
+  "description": "What `chant workspace member add <name> --from <file|->`, `member remove <name>` and `host set <name> --from <file|->` print (#3596): the entry before and after the write and the file it changed, or the reason it wrote nothing. Each write changes one entry of members or hosts in the declaration, in place, keeping the file's formatting and comments, and never commits. Readers ignore fields they do not know; a field is only ever added within a version. The error codes are a closed list, each in the one closed list of `reason-codes.ts`. Contract version 1 of this document is written by chant 0.110.0 and newer.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "description": "The entry was written, or would be with --dry-run, or the declaration already held it (changed false). Exit code 0.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "action",
+        "name",
+        "declaration",
+        "paths",
+        "changed",
+        "dryRun",
+        "previous",
+        "entry"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/member-write/v1/member-write.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string",
+          "description": "The chant that wrote it."
+        },
+        "action": {
+          "enum": [
+            "member add",
+            "member remove",
+            "host set"
+          ]
+        },
+        "name": {
+          "type": "string",
+          "description": "The member's or host's name."
+        },
+        "declaration": {
+          "type": "object",
+          "required": [
+            "path",
+            "sha256"
+          ],
+          "properties": {
+            "path": {
+              "type": "string",
+              "description": "The declaration file, relative to the repository root (the working directory outside git), with / separators."
+            },
+            "sha256": {
+              "type": "string",
+              "pattern": "^[0-9a-f]{64}$",
+              "description": "The sha256 of the declaration's bytes after the write, or as they would be with --dry-run."
+            }
+          }
+        },
+        "paths": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The declaration, relative to the repository root, when the write changed it or would with --dry-run; empty when it already held what was given."
+        },
+        "changed": {
+          "type": "boolean",
+          "description": "Whether the declaration changed: paths is not empty."
+        },
+        "dryRun": {
+          "type": "boolean",
+          "description": "True when --dry-run was given: nothing was written, and the document says what would have been."
+        },
+        "previous": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object"
+            }
+          ],
+          "description": "The entry before the write, as the declaration held it, x- keys included; null when member add or host set adds a new one."
+        },
+        "entry": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "name"
+              ],
+              "properties": {
+                "name": {
+                  "type": "string"
+                }
+              }
+            }
+          ],
+          "description": "The entry after the write, as the declaration holds it, with name first; null after member remove."
+        }
+      }
+    },
+    "failure": {
+      "type": "object",
+      "description": "Nothing was written. Exit code 1.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "action",
+        "name",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/member-write/v1/member-write.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "action": {
+          "enum": [
+            "member add",
+            "member remove",
+            "host set"
+          ]
+        },
+        "name": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "declaration-missing",
+                "declaration-ambiguous",
+                "declaration-unparseable",
+                "declaration-invalid",
+                "placement-invalid",
+                "reader-too-old",
+                "root-chant-required",
+                "not-a-git-repository",
+                "revision-unknown",
+                "write-usage-invalid",
+                "write-input-invalid",
+                "member-exists",
+                "member-unknown",
+                "box-isolation-collision",
+                "box-isolation-literal",
+                "write-scope-member",
+                "write-scope-protected",
+                "write-scope-class-unknown",
+                "agent-unknown",
+                "principal-unidentified",
+                "write-lock-timeout",
+                "write-lock-not-held"
+              ]
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/src/workspace/reason-codes.test.ts

@@ -40,7 +40,9 @@ import { PATCH_ERROR_CODES } from "./patch";
 import { AGENT_ERROR_CODES } from "./agent-cli";
 import { SCOPE_FINDING_CODES, WRITE_SCOPE_CODES } from "./write-scope";
 import { PLANTABLE_REASON_CODES } from "./box-factory";
+import { BOX_FACTORY_ERROR_CODES } from "./box-factory-write";
 import { BOX_LISTING_ERROR_CODES } from "./box-listing";
+import { DECLARATION_WRITE_ERROR_CODES } from "./declaration-write";
 import { BOX_PUBLISH_ERROR_CODES } from "./box-publish";
 import { WRITE_LOCK_ERROR_CODES } from "./write-lock-cli";
 import { WIP_ERROR_CODES, WIP_WRITE_ERROR_CODES } from "./wip";
@@ -108,6 +110,8 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   SCOPE_FINDING_CODES,
   PLANTABLE_REASON_CODES,
   BOX_LISTING_ERROR_CODES,
+  DECLARATION_WRITE_ERROR_CODES,
+  BOX_FACTORY_ERROR_CODES,
   BOX_PUBLISH_ERROR_CODES,
   WRITE_LOCK_ERROR_CODES,
   WIP_ERROR_CODES,

package/src/workspace/reason-codes.ts

@@ -260,6 +260,12 @@ export const REASONS = {
   "listing-member-unknown": "box listing set names a member the declaration does not declare.",
   "listing-box-missing": "box listing set names a member whose entry declares no box block, so it has no listing.",
   "listing-cover-invalid": "The cover can't be read, is not a PNG, JPEG or WebP picture, is larger than 5 MiB, has a path outside the workspace, or has an extension other than its picture format's.",
+  // A declaration's members and hosts written through chant (member add|remove, host set, #3596): why the write was refused. Nothing is written.
+  "member-exists": "member add names a member the declaration already has, with an entry other than the one given.",
+  "member-unknown": "member remove names a member the declaration does not declare.",
+  // A box's factory written through chant (box factory set, #3600): why the write was refused. Nothing is written.
+  "factory-member-unknown": "box factory set names a member the declaration does not declare.",
+  "factory-box-missing": "box factory set names a member whose entry declares no box block, so it has no factory.",
   // A box's work published through chant (box publish, #3165, ws-088): why the call printed no result.
   "publish-member-unknown": "box publish names a member the declaration does not declare.",
   "publish-none": "box publish names a member whose box block names no publisher, or which declares no box block.",

package/src/workspace/status-stewards.ts

@@ -4,7 +4,8 @@
  * its Ops with their schedules, and each Op's last run.
  *
  * The steward itself is read from its declaration, the same `*.op.ts` files
- * `chant operator --steward` reads (`../op/discover.ts`), and only for a member
+ * `chant operator --steward` reads (`../op/discover.ts`), through the index
+ * kept per tree (`./steward-index.ts`, #3636), and only for a member
  * of kind `chant` that is a chant project of its own (a `chant.config.ts` or
  * `.json` in its directory), so a member never lists a parent project's
  * steward. Everything
@@ -47,8 +48,7 @@
 
 import { existsSync, realpathSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
-import { discoverOps, discoverStewards } from "../op/discover";
-import { stewardBesideFor, stewardFormFor, stewardLeaseName, type StewardForm } from "../op/steward";
+import { 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";
@@ -56,7 +56,7 @@ import { readBlobBySha, readRefSha } from "../lifecycle/git";
 import { resolveMemberLedger } from "../lifecycle/member-ledger";
 import { listWorkLeases } from "../lifecycle/work-lease";
 import { stewardWorkHolder } from "../op/work-lease-run";
-import type { OpConfig } from "../op/types";
+import { readStewardIndex, type IndexedOp, type IndexedSteward, type StewardIndex } from "./steward-index";
 import type { OpRunRecord } from "../op/runtime";
 import { readInFlightRun } from "../op/run-live";
 import { approveCommand } from "./status-gates";
@@ -342,19 +342,14 @@ async function readLeaseRef(leaseName: string, memberDir: string, now: string):
 }
 
 /** 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);
+async function besideOf(steward: IndexedSteward, op: string, memberDir: string, now: string): Promise<StatusStewardOp["beside"]> {
+  const beside = steward.beside.find((b) => b.op === op);
   if (!beside) return null;
-  return { ready: beside.ready !== null && beside.ready !== undefined, lease: await readLeaseRef(op, memberDir, now) };
+  return { ready: beside.ready, 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[]> {
+async function readHeldWorkLeases(steward: string, op: IndexedOp, memberDir: string, now: string): Promise<StatusStewardWorkLease[]> {
   try {
     const kind = op.workLease?.kind;
     const cwd = kind ? dirname(resolve(memberDir, kind)) : memberDir;
@@ -378,7 +373,7 @@ export async function readMemberStewards(
   now: string,
   kind = "chant",
   box: { capabilities: { name: string; broker: string | null }[] } | null = null,
-  deps: { readQuestions?: ReadQuestionStates } = {},
+  deps: { readQuestions?: ReadQuestionStates; readIndex?: (memberDir: string) => Promise<StewardIndex> } = {},
 ): Promise<MemberStewards> {
   const reasons: MemberStewards["reasons"] = [];
   // Read once per member, and only when a run stopped on a question.
@@ -386,19 +381,18 @@ export async function readMemberStewards(
   const questionStates = () => (states ??= (deps.readQuestions ?? readQuestionStates)(memberDir));
   if (kind !== "chant" || !isChantProject(memberDir)) return { stewards: [], reasons };
 
-  let discovered: Awaited<ReturnType<typeof discoverStewards>>;
+  let index: StewardIndex;
   try {
-    discovered = await discoverStewards({ cwd: memberDir });
+    index = await (deps.readIndex ?? readStewardIndex)(memberDir);
   } catch (err) {
     reasons.push({ code: "stewards-unreadable", message: err instanceof Error ? err.message.split("\n")[0] : String(err) });
     return { stewards: [], reasons };
   }
-  const { stewards: found, errors, conflicts } = discovered;
-  for (const message of errors) reasons.push({ code: "stewards-unreadable", message });
-  for (const message of conflicts) reasons.push({ code: "stewards-conflict", message });
+  for (const message of index.errors) reasons.push({ code: "stewards-unreadable", message });
+  for (const message of index.conflicts) reasons.push({ code: "stewards-conflict", message });
 
   const stewards: StatusSteward[] = [];
-  for (const { declaration, filePath } of [...found.values()].sort((a, b) => a.declaration.name.localeCompare(b.declaration.name))) {
+  for (const declaration of [...index.stewards].sort((a, b) => a.name.localeCompare(b.name))) {
     const ops: StatusStewardOp[] = [];
     const waiting: StatusSteward["waiting"] = [];
     for (const op of declaration.ops) {
@@ -467,11 +461,11 @@ export async function readMemberStewards(
     }
     stewards.push({
       name: declaration.name,
-      file: relative(realpathSync(memberDir), realpathSync(filePath)).split("\\").join("/"),
+      file: relative(realpathSync(memberDir), realpathSync(declaration.filePath)).split("\\").join("/"),
       form: stewardFormFor(declaration, env),
       forms: { default: declaration.form.default, environments: { ...declaration.form.environments } },
-      vault: typeof declaration.vault === "string" ? declaration.vault : null,
-      capabilities: (Array.isArray(declaration.capabilities) ? declaration.capabilities : []).map((name) => {
+      vault: declaration.vault,
+      capabilities: declaration.capabilities.map((name) => {
         const declared = box?.capabilities.find((c) => c.name === name);
         return { name, broker: declared?.broker ?? null, declared: declared !== undefined };
       }),
@@ -480,7 +474,7 @@ export async function readMemberStewards(
       waiting,
     });
   }
-  if (stewards.length > 0) await addUndeclaredWaits(memberDir, stewards, found, reasons, now, questionStates);
+  if (stewards.length > 0 && index.otherOps) await addUndeclaredWaits(memberDir, stewards, index.otherOps, reasons, now, questionStates);
   return { stewards, reasons };
 }
 
@@ -489,26 +483,20 @@ export async function readMemberStewards(
  * 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`.
+ * `ops` are the member's Ops no steward lists, from the index; import
+ * failures are left out there, as discovering the stewards reported them as
+ * `stewards-unreadable`.
  */
 async function addUndeclaredWaits(
   memberDir: string,
   stewards: StatusSteward[],
-  found: Awaited<ReturnType<typeof discoverStewards>>["stewards"],
+  ops: IndexedOp[],
   reasons: MemberStewards["reasons"],
   now: string,
   questionStates: () => Promise<Map<string, string> | null>,
 ): 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))) {
+  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);

package/src/workspace/status.schema.json

@@ -7,6 +7,7 @@
   "$defs": {
     "boxShip": {
       "type": "object",
+      "patternProperties": { "^x-": { "description": "Added in contract 1 by #3595. An x- key the declaration holds on this object, with its value as written." } },
       "additionalProperties": false,
       "required": ["op", "gate", "env", "bookkeeping", "serving", "pending"],
       "properties": {
@@ -170,6 +171,7 @@
     },
     "member": {
       "type": "object",
+      "patternProperties": { "^x-": { "description": "Added in contract 1 by #3595. An x- key the declaration holds on this object, with its value as written." } },
       "required": ["name", "dir", "kind", "fields", "environments", "compare", "readable", "gateLedger", "gates", "box", "stewards", "stewardReasons"],
       "properties": {
         "name": { "type": "string" },
@@ -543,7 +545,11 @@
         "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." }
+        "decided_on": { "type": ["string", "null"], "description": "The day it was decided, or null while it is proposed." },
+        "approved": {
+          "type": "boolean",
+          "description": "Added in contract 1 by #3609. Whether the record's state counts as approved: the decision kind's approval rank for that state is above 0, the rule the factory's pick holds dispatch with. With chant's decision kind, decided, ratified and superseded are approved, and proposed and withdrawn are not. False when no decision record has the id, and for a kind that declares no approval ranks."
+        }
       }
     },
     "replication": {
@@ -583,6 +589,7 @@
     },
     "box": {
       "type": "object",
+      "patternProperties": { "^x-": { "description": "Added in contract 1 by #3595. An x- key the declaration holds on this object, with its value as written." } },
       "required": ["capabilities", "isolation", "intent", "services"],
       "properties": {
         "factory": {
@@ -681,6 +688,7 @@
     },
     "factory": {
       "type": "object",
+      "patternProperties": { "^x-": { "description": "Added in contract 1 by #3595. An x- key the declaration holds on this object, with its value as written." } },
       "required": ["builds", "check", "checks", "builders", "tiers", "builderFor", "publish"],
       "properties": {
         "builds": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "The members the factory builds, in declaration order. A work item a person asks for constrains member:<the first>." },
@@ -723,6 +731,7 @@
     },
     "listing": {
       "type": "object",
+      "patternProperties": { "^x-": { "description": "Added in contract 1 by #3595. An x- key the declaration holds on this object, with its value as written." } },
       "required": ["published", "title", "line", "cover"],
       "properties": {
         "published": { "type": "boolean", "description": "Whether the box is listed; true unless declared otherwise." },

package/src/workspace/status.ts

@@ -48,7 +48,7 @@ import { resolveBoxes, type ResolvedIsolation } from "./box-isolation";
 import { resolveBoxIntents, unresolvedIntent, type BoxIntent } from "./box-intent";
 import { loadKindRegistry, resolveMemberFields, type MemberFields } from "./kinds";
 import { factoryView, listingView, plantability, treeBytes, type FactoryView, type ListingView, type Plantable } from "./box-factory";
-import { declaredRecordKinds, readDeclaration, readerVersion, WorkspaceReadError, type Declaration, type ErrorLocation, type Member } from "./declaration";
+import { declaredRecordKinds, extensionsAt, readDeclaration, readerVersion, WorkspaceReadError, type Declaration, type ErrorLocation, type Member } from "./declaration";
 import type { ReasonCode } from "./reason-codes";
 import { gateAdmissionFrom } from "./identity";
 import { scopeSource } from "./write-scope";
@@ -320,6 +320,18 @@ export interface StatusQuery {
   readStewards?: typeof readMemberStewards;
 }
 
+/** A factory view with the declaration's x- keys on it and on its check, publish and tiers (#3595). */
+function factoryWithX(view: FactoryView | null, pointer: string, x: (pointer: string) => Record<string, unknown>): FactoryView | null {
+  if (view === null) return null;
+  return {
+    ...view,
+    check: view.check === null ? null : { ...view.check, ...x(`${pointer}/check`) },
+    tiers: view.tiers.map((t, i) => ({ ...t, ...x(`${pointer}/tiers/${i}`) })),
+    publish: view.publish === null ? null : { ...view.publish, ...x(`${pointer}/publish`) },
+    ...x(pointer),
+  };
+}
+
 class StatusError extends Error {
   constructor(
     readonly code: StatusErrorCode,
@@ -500,6 +512,10 @@ export async function workspaceStatus(query: StatusQuery): Promise<StatusDocumen
       const own = await hasMemberLedger(m, found.dir);
       const gates = await readMemberGates(own ? `${MEMBERS_DIR}/${m.name}/${GATES_DIR}` : GATES_DIR, own ? "members" : "flat", commit, envs, found.dir, now, query.readGates, rules);
       const stewards = await (query.readStewards ?? readMemberStewards)(resolve(found.dir, m.dir), query.env, now, m.kind, m.box);
+      // The declaration's x- keys go back on the objects that hold them (#3595).
+      const x = (pointer: string) => extensionsAt(declaration, pointer);
+      const bp = m.box?.pointer ?? "";
+      const withX = <T extends object>(view: T | null, pointer: string): T | null => (view === null ? null : { ...view, ...x(pointer) });
       members.push({
         name: m.name,
         dir: m.dir,
@@ -514,7 +530,7 @@ export async function workspaceStatus(query: StatusQuery): Promise<StatusDocumen
           m.box === null
             ? null
             : {
-                capabilities: m.box.capabilities.map((c) => ({ name: c.name, broker: c.broker, scope: [...c.scope] })),
+                capabilities: m.box.capabilities.map((c) => ({ name: c.name, broker: c.broker, scope: [...c.scope], ...x(c.pointer) })),
                 isolation: isolation.get(m.name) ?? null,
                 intent: intents.get(m.name) ?? null,
                 services: m.box.services.map((s) => ({
@@ -525,15 +541,18 @@ export async function workspaceStatus(query: StatusQuery): Promise<StatusDocumen
                   duration: s.duration,
                   health: s.health,
                   optional: s.optional,
+                  ...x(s.pointer),
                 })),
-                factory: factoryView(m.box.factory, declaration.members),
-                listing: listingView(m.box.listing, coverBytes),
+                factory: factoryWithX(factoryView(m.box.factory, declaration.members), `${bp}/factory`, x),
+                listing: withX(listingView(m.box.listing, coverBytes), `${bp}/listing`),
                 publisher: m.box.publisher,
-                ship: await shipView(m, found.dir, read),
-                replicate: m.box.replicate === null ? null : (({ box: _box, ...rest }) => rest)(policyView(m.name, m.box.replicate)),
+                ship: withX(await shipView(m, found.dir, read), `${bp}/ship`),
+                replicate: withX(m.box.replicate === null ? null : (({ box: _box, ...rest }) => rest)(policyView(m.name, m.box.replicate)), `${bp}/replicate`),
+                ...x(bp),
               },
         stewards: stewards.stewards,
         stewardReasons: stewards.reasons,
+        ...x(m.pointer),
       });
     }
     // Several members read from one flat ledger see the same records; say so.

package/src/workspace/steward-index.test.ts

@@ -0,0 +1,171 @@
+/**
+ * The steward index behind `chant workspace status` (#3636): discovered
+ * once per tree, read back while the tree is the same, discovered again
+ * after an edit, a new file or a commit, and never written into the
+ * checkout.
+ */
+
+import { existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, afterEach, beforeEach, describe, expect, test } from "vitest";
+import { cleanScratch, commitAll, git, repo, scratchDir } from "./__fixtures__/contract-repo";
+import { declareSteward } from "../op/steward";
+import type { OpConfig } from "../op/types";
+import { discoverStewardIndex, readStewardIndex, type StewardIndex } from "./steward-index";
+import { readMemberStewards } from "./status-stewards";
+
+afterAll(cleanScratch);
+
+let cache: string;
+let before: string | undefined;
+beforeEach(() => {
+  before = process.env.CHANT_CACHE_DIR;
+  cache = scratchDir("chant-steward-index-cache-");
+  process.env.CHANT_CACHE_DIR = cache;
+});
+afterEach(() => {
+  if (before === undefined) delete process.env.CHANT_CACHE_DIR;
+  else process.env.CHANT_CACHE_DIR = before;
+  delete process.env.CHANT_STEWARD_INDEX;
+});
+
+function op(name: string, extra: Partial<OpConfig> = {}): OpConfig {
+  return {
+    name,
+    overview: `${name} fixture`,
+    phases: [{ name: "only", steps: [{ kind: "activity", fn: "noop", args: {} }] }],
+    ...extra,
+  } as OpConfig;
+}
+
+/** A chant project whose one Op file declares a steward and exports another Op it doesn't list. */
+function project(): string {
+  const tick = op("tick", { schedule: { cron: "0 * * * *" }, labels: { Env: "box" } });
+  const build = op("build", { workLease: { item: "W-001", kind: "work/work.kind.mjs" }, changesCheckout: true });
+  const steward = declareSteward({
+    name: "box-steward",
+    ops: [tick],
+    beside: [{ op: build, ready: { kind: "activity", fn: "ready", args: {} } }],
+    form: { default: "local", environments: { k3d: "fountain" } },
+    capabilities: ["inference"],
+  });
+  return repo(
+    {
+      "chant.config.json": "{}\n",
+      "ops/steward.op.ts": `export const steward = ${JSON.stringify(steward)};\nexport const lonely = { props: ${JSON.stringify(op("lonely"))} };\n`,
+    },
+    true,
+  );
+}
+
+/** `readStewardIndex`, counting the discoveries it makes. */
+function counted(dir: string) {
+  let n = 0;
+  const discover = async (d: string): Promise<StewardIndex> => {
+    n++;
+    return discoverStewardIndex(d);
+  };
+  return { read: () => readStewardIndex(dir, { discover }), discoveries: () => n };
+}
+
+describe("the steward index (#3636)", () => {
+  test("holds what status reads of the stewards and Ops", async () => {
+    const root = project();
+    const index = await discoverStewardIndex(root);
+    expect(index.errors).toEqual([]);
+    expect(index.conflicts).toEqual([]);
+    expect(index.stewards).toHaveLength(1);
+    const [s] = index.stewards;
+    expect(s).toMatchObject({
+      name: "box-steward",
+      beside: [{ op: "build", ready: true }],
+      form: { default: "local", environments: { k3d: "fountain" } },
+      capabilities: ["inference"],
+      vault: null,
+    });
+    expect(s.filePath.endsWith(join("ops", "steward.op.ts"))).toBe(true);
+    expect(s.ops).toEqual([
+      { name: "tick", schedule: { cron: "0 * * * *" }, labels: { Env: "box" }, workLease: null, changesCheckout: false },
+      { name: "build", schedule: null, workLease: { kind: "work/work.kind.mjs" }, changesCheckout: true },
+    ]);
+    expect(index.otherOps).toEqual([{ name: "lonely", schedule: null, workLease: null, changesCheckout: false }]);
+  });
+
+  test("a second read of the same tree discovers nothing", async () => {
+    const root = project();
+    const c = counted(root);
+    const first = await c.read();
+    const second = await c.read();
+    expect(c.discoveries()).toBe(1);
+    expect(second).toEqual(JSON.parse(JSON.stringify(first)));
+  });
+
+  test("an edit, a new file or a commit discovers again", async () => {
+    const root = project();
+    const c = counted(root);
+    await c.read();
+    // A module already imported in this process isn't read again, so only the count is checked.
+    writeFileSync(join(root, "ops", "steward.op.ts"), "export const nothing = 1;\n");
+    await c.read();
+    expect(c.discoveries()).toBe(2);
+    await c.read();
+    expect(c.discoveries()).toBe(2);
+    mkdirSync(join(root, "lib"));
+    writeFileSync(join(root, "lib", "helper.ts"), "export const x = 1;\n");
+    await c.read();
+    expect(c.discoveries()).toBe(3);
+    commitAll(root);
+    await c.read();
+    expect(c.discoveries()).toBe(4);
+  });
+
+  test("an Op file that fails to import is not indexed, so the next read tries again", async () => {
+    const root = project();
+    writeFileSync(join(root, "ops", "broken.op.ts"), "throw new Error('not today');\n");
+    const c = counted(root);
+    expect((await c.read()).errors).toHaveLength(1);
+    expect((await c.read()).errors).toHaveLength(1);
+    expect(c.discoveries()).toBe(2);
+  });
+
+  test("CHANT_STEWARD_INDEX=0 discovers every time", async () => {
+    const root = project();
+    process.env.CHANT_STEWARD_INDEX = "0";
+    const c = counted(root);
+    await c.read();
+    await c.read();
+    expect(c.discoveries()).toBe(2);
+    expect(existsSync(join(cache, "workspace-stewards"))).toBe(false);
+  });
+
+  test("the index lives in the cache dir, never in the checkout", async () => {
+    const root = project();
+    const status = git(root, "status", "--porcelain", "--ignored");
+    await readStewardIndex(root);
+    expect(git(root, "status", "--porcelain", "--ignored")).toBe(status);
+    const [dir] = readdirSync(join(cache, "workspace-stewards"));
+    expect(readdirSync(join(cache, "workspace-stewards", dir)).filter((f) => f.endsWith(".json"))).toHaveLength(1);
+  });
+
+  test("the indexes of a checkout that is gone go on the next write", async () => {
+    const gone = project();
+    await readStewardIndex(gone);
+    rmSync(gone, { recursive: true, force: true });
+    await readStewardIndex(project());
+    expect(readdirSync(join(cache, "workspace-stewards"))).toHaveLength(1);
+  });
+
+  test("status lists the same stewards from the index as from discovery", async () => {
+    const root = project();
+    const now = "2027-01-01T00:00:00Z";
+    process.env.CHANT_STEWARD_INDEX = "0";
+    const discovered = await readMemberStewards(root, "k3d", now);
+    delete process.env.CHANT_STEWARD_INDEX;
+    await readMemberStewards(root, "k3d", now);
+    const indexed = await readMemberStewards(root, "k3d", now, "chant", null, {
+      readIndex: (d) => readStewardIndex(d, { discover: () => Promise.reject(new Error("should have been read from the index")) }),
+    });
+    expect(indexed).toEqual(discovered);
+    expect(indexed.stewards[0]).toMatchObject({ name: "box-steward", form: "fountain", file: "ops/steward.op.ts" });
+  });
+});