@intentius/chant 0.104.3 → 0.105.0

package/src/codegen/generate-runtime-index.test.ts

@@ -25,9 +25,9 @@ describe("generateRuntimeIndex", () => {
     const result = generateRuntimeIndex(resources, properties, baseConfig);
 
     // Resources sorted: Alarm before Bucket
-    expect(result).toContain('export const Alarm = createResource("AWS::CloudWatch::Alarm", "test", {});');
-    expect(result).toContain('export const Bucket = createResource("AWS::S3::Bucket", "test", {"arn":"Arn"});');
-    expect(result).toContain('export const Bucket_Versioning = createProperty("AWS::S3::Bucket.VersioningConfiguration", "test");');
+    expect(result).toContain('export const Alarm = /* @__PURE__ */ createResource("AWS::CloudWatch::Alarm", "test", {});');
+    expect(result).toContain('export const Bucket = /* @__PURE__ */ createResource("AWS::S3::Bucket", "test", {"arn":"Arn"});');
+    expect(result).toContain('export const Bucket_Versioning = /* @__PURE__ */ createProperty("AWS::S3::Bucket.VersioningConfiguration", "test");');
 
     // Alarm should come before Bucket in the output
     const alarmIdx = result.indexOf("Alarm");

package/src/codegen/generate-runtime-index.ts

@@ -2,7 +2,9 @@
  * Generic runtime index generator for lexicon packages.
  *
  * Produces the `index.ts` file containing factory constructor exports
- * (`createResource`, `createProperty`) and collision-safe re-exports.
+ * (`createResource`, `createProperty`) and collision-safe re-exports. Each
+ * factory call is marked pure, so a bundler drops the classes a caller does
+ * not import instead of keeping every one.
  */
 
 export interface RuntimeIndexConfig {
@@ -55,7 +57,7 @@ export function generateRuntimeIndex(
   for (const { tsName, resourceType, attrs } of sortedResources) {
     const attrsStr = JSON.stringify(attrs);
     lines.push(
-      `export const ${tsName} = createResource(${JSON.stringify(resourceType)}, ${JSON.stringify(config.lexiconName)}, ${attrsStr});`,
+      `export const ${tsName} = /* @__PURE__ */ createResource(${JSON.stringify(resourceType)}, ${JSON.stringify(config.lexiconName)}, ${attrsStr});`,
     );
   }
 
@@ -65,7 +67,7 @@ export function generateRuntimeIndex(
   const sortedProperties = [...properties].sort((a, b) => a.tsName.localeCompare(b.tsName));
   for (const { tsName, resourceType } of sortedProperties) {
     lines.push(
-      `export const ${tsName} = createProperty(${JSON.stringify(resourceType)}, ${JSON.stringify(config.lexiconName)});`,
+      `export const ${tsName} = /* @__PURE__ */ createProperty(${JSON.stringify(resourceType)}, ${JSON.stringify(config.lexiconName)});`,
     );
   }
 

package/src/op/activities/factory.ts

@@ -370,7 +370,7 @@ async function commitAll(worktree: string, subject: string, item: string, kindNa
 
 // ── the activities ───────────────────────────────────────────────────────────
 
-/** Which work items are buildable now (#3406 rule 1). */
+/** Which work items are buildable now (#3406 rule 1): those that name a contract, asks and intent builds (#3503). */
 export async function factoryPick(args: FactoryPickArgs = {}): Promise<FactoryPickResult> {
   const cwd = args.cwd ?? process.cwd();
   const { pickable, readyKey } = await import("../../workspace/factory-rules");

package/src/op/factory.e2e.test.ts

@@ -1,7 +1,9 @@
 /**
  * The factory reference Op (#3406, ws-087), run through the local executor
  * with stub hooks on a small workspace that carries the reference
- * workspace's decision, work and answer kinds and its points: one item from
+ * workspace's decision, work, answer and contract kinds and its points, its
+ * work kind linked to the contracts, as the factory builds only an item that
+ * names a contract, an ask or an intent build (#3503): one item from
  * pick to done, one retry after a failed build, and one ask the understand
  * point refuses. The rules themselves are tested in
  * ../workspace/factory-rules.test.ts.
@@ -53,10 +55,19 @@ function workspace(dir: string): void {
   git(["config", "user.email", "t@chant.dev"], dir);
   git(["config", "user.name", "T"], dir);
   git(["config", "commit.gpgsign", "false"], dir);
-  for (const d of ["decisions", "work", "answers"]) mkdirSync(join(dir, d), { recursive: true });
+  for (const d of ["decisions", "work", "answers", "contracts"]) mkdirSync(join(dir, d), { recursive: true });
   for (const f of ["decisions/decision.kind.mjs", "decisions/decision.schema.json", "decisions/points.json", "work/work.kind.mjs", "work/work.schema.json", "answers/answer.kind.mjs", "answers/answer.schema.json"]) {
     cpSync(join(REF, f), join(dir, f));
   }
+  for (const f of ["contract.kind.mjs", "contract.schema.json"]) cpSync(join(REF, "design", "contracts", f), join(dir, "contracts", f));
+  const kindFile = join(dir, "work", "work.kind.mjs");
+  const answers = 'answers: "../answers/answer.kind.mjs",';
+  if (!readFileSync(kindFile, "utf-8").includes(answers)) throw new Error("the reference work kind no longer names its answer kind as the fixture expects");
+  writeFileSync(kindFile, readFileSync(kindFile, "utf-8").replace(answers, `${answers}\n    contract: { field: "contract", kind: "../contracts/contract.kind.mjs" },`));
+  writeFileSync(
+    join(dir, "contracts", "C-001-the-feature.md"),
+    `---\n${JSON.stringify({ schema: 1, id: "C-001", title: "The feature", state: "approved", criteria: [{ id: "AC-1", text: "the feature exists" }], checks: [], reviews: [], approved_by: "alice" }, null, 2)}\n---\n\n# The feature\n`,
+  );
   writeFileSync(
     join(dir, "chant.workspace.json"),
     JSON.stringify({
@@ -71,8 +82,8 @@ function workspace(dir: string): void {
   mkdirSync(join(dir, "hooks"), { recursive: true });
   writeFileSync(join(dir, "hooks", "builder.cjs"), BUILDER);
   writeFileSync(join(dir, "hooks", "check.cjs"), CHECK);
-  writeFileSync(join(dir, "work", "W-101-the-feature.md"), item("W-101", { acceptance: [{ id: "AC-1", text: "app/W-101.txt exists", verification: "unit" }] }));
-  writeFileSync(join(dir, "work", "W-102-the-retried-one.md"), item("W-102", { acceptance: [{ id: "AC-1", text: "app/W-102.txt exists", verification: "unit" }] }));
+  writeFileSync(join(dir, "work", "W-101-the-feature.md"), item("W-101", { contract: "C-001", acceptance: [{ id: "AC-1", text: "app/W-101.txt exists", verification: "unit" }] }));
+  writeFileSync(join(dir, "work", "W-102-the-retried-one.md"), item("W-102", { contract: "C-001", acceptance: [{ id: "AC-1", text: "app/W-102.txt exists", verification: "unit" }] }));
   writeFileSync(join(dir, "work", "W-103-an-ask.md"), item("W-103", { state: "proposed", source: { ask: { said: "Make the page purple.", by: "alice", via: "hud" } } }));
   git(["add", "-A"], dir);
   git(["commit", "-q", "-m", "the workspace"], dir);
@@ -177,7 +188,7 @@ describe("the factory Op's seams for an orchestrator (studio#382)", () => {
       // The prepare hook writes W-110 in the checkout and leaves it uncommitted; the others are taken out of the way.
       writeFileSync(
         join(dir, "hooks", "prepare.cjs"),
-        `require("node:fs").writeFileSync("work/W-110-prepared.md", ${JSON.stringify(item("W-110", { acceptance: [{ id: "AC-1", text: "one", verification: "unit" }, { id: "AC-2", text: "two", verification: "unit" }] }))});`,
+        `require("node:fs").writeFileSync("work/W-110-prepared.md", ${JSON.stringify(item("W-110", { contract: "C-001", acceptance: [{ id: "AC-1", text: "one", verification: "unit" }, { id: "AC-2", text: "two", verification: "unit" }] }))});`,
       );
       for (const id of ["W-101", "W-102"]) writeFileSync(join(dir, ".fail-" + id), "");
       git(["add", "-A"], dir);

package/src/vendor/js-yaml-load.ts

@@ -29,7 +29,10 @@
  * timestamp, omap, pairs, set), the snippet renderer, the schema classes and
  * the loader's option handling are gone. The reader always runs in json mode
  * (a repeated mapping key takes the last value) and takes its type list from
- * the caller. The parsing code itself is unchanged. It is kept in one file
+ * the caller. With the options fixed, the branches only another setting
+ * reached (the duplicate key error, the legacy line break check) and the
+ * warnings, which nothing listened to, are gone too. The parsing code itself
+ * is otherwise unchanged. It is kept in one file
  * because js-yaml's ES module wraps each of its files in an init function a
  * bundler cannot shake, so importing it costs the whole library.
  */
@@ -214,7 +217,6 @@ const CHOMPING_KEEP = 3
 
 // eslint-disable-next-line no-control-regex
 const PATTERN_NON_PRINTABLE = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F-\x84\x86-\x9F\uFFFE\uFFFF]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?:[^\uD800-\uDBFF]|^)[\uDC00-\uDFFF]/
-const PATTERN_NON_ASCII_LINE_BREAKS = /[\x85\u2028\u2029]/
 // eslint-disable-next-line no-useless-escape
 const PATTERN_FLOW_INDICATORS = /[,\[\]{}]/
 // eslint-disable-next-line no-useless-escape
@@ -338,12 +340,8 @@ for (let i = 0; i < 256; i++) {
 function State (input, types) {
   this.input = input
 
-  this.filename = null
   this.implicitTypes = types.implicit
   this.typeMap = compileTypes(types.implicit, types.explicit)
-  // json mode: a duplicate mapping key takes the last value
-  this.json = true
-  this.legacy = false
   this.maxDepth = 100
   this.maxTotalMergeKeys = 10000
 
@@ -364,7 +362,6 @@ function State (input, types) {
 
   /*
   this.version;
-  this.checkLineBreaks;
   this.tagMap;
   this.anchorMap;
   this.tag;
@@ -375,7 +372,7 @@ function State (input, types) {
 
 function generateError (state, message) {
   const mark = {
-    name: state.filename,
+    name: null,
     buffer: state.input.slice(0, -1), // omit trailing \0
     position: state.position,
     line: state.line,
@@ -389,8 +386,6 @@ function throwError (state, message) {
   throw generateError(state, message)
 }
 
-function throwWarning () {}
-
 function storeAnchor (state, name, value) {
   const transactions = state.anchorMapTransactions
 
@@ -489,18 +484,12 @@ const directiveHandlers = {
     }
 
     const major = parseInt(match[1], 10)
-    const minor = parseInt(match[2], 10)
 
     if (major !== 1) {
       throwError(state, 'unacceptable YAML version of the document')
     }
 
     state.version = args[0]
-    state.checkLineBreaks = (minor < 2)
-
-    if (minor !== 1 && minor !== 2) {
-      throwWarning(state, 'unsupported YAML version of the document')
-    }
   },
 
   TAG: function handleTagDirective (state, name, args) {
@@ -585,8 +574,7 @@ function mergeMappings (state, destination, source, overridableKeys) {
   }
 }
 
-function storeMappingPair (state, _result, overridableKeys, keyTag, keyNode, valueNode,
-  startLine, startLineStart, startPos) {
+function storeMappingPair (state, _result, overridableKeys, keyTag, keyNode, valueNode) {
   // The output is a plain object here, so keys can only be strings.
   // We need to convert keyNode to a string, but doing so can hang the process
   // (deeply nested arrays that explode exponentially using aliases).
@@ -630,15 +618,7 @@ function storeMappingPair (state, _result, overridableKeys, keyTag, keyNode, val
       mergeMappings(state, _result, valueNode, overridableKeys)
     }
   } else {
-    if (!state.json &&
-        !_hasOwnProperty.call(overridableKeys, keyNode) &&
-        _hasOwnProperty.call(_result, keyNode)) {
-      state.line = startLine || state.line
-      state.lineStart = startLineStart || state.lineStart
-      state.position = startPos || state.position
-      throwError(state, 'duplicated mapping key')
-    }
-
+    // json mode: a repeated key takes the last value.
     setProperty(_result, keyNode, valueNode)
     delete overridableKeys[keyNode]
   }
@@ -699,10 +679,6 @@ function skipSeparationSpace (state, allowComments, checkIndent) {
     }
   }
 
-  if (checkIndent !== -1 && lineBreaks !== 0 && state.lineIndent < checkIndent) {
-    throwWarning(state, 'deficient indentation')
-  }
-
   return lineBreaks
 }
 
@@ -956,8 +932,6 @@ function readDoubleQuotedScalar (state, nodeIndent) {
 function readFlowCollection (state, nodeIndent) {
   let readNext = true
   let _line
-  let _lineStart
-  let _pos
   const _tag = state.tag
   let _result
   const _anchor = state.anchor
@@ -1023,8 +997,6 @@ function readFlowCollection (state, nodeIndent) {
     }
 
     _line = state.line // Save the current line.
-    _lineStart = state.lineStart
-    _pos = state.position
     composeNode(state, nodeIndent, CONTEXT_FLOW_IN, false, true)
     keyTag = state.tag
     keyNode = state.result
@@ -1041,9 +1013,9 @@ function readFlowCollection (state, nodeIndent) {
     }
 
     if (isMapping) {
-      storeMappingPair(state, _result, overridableKeys, keyTag, keyNode, valueNode, _line, _lineStart, _pos)
+      storeMappingPair(state, _result, overridableKeys, keyTag, keyNode, valueNode)
     } else if (isPair) {
-      _result.push(storeMappingPair(state, null, overridableKeys, keyTag, keyNode, valueNode, _line, _lineStart, _pos))
+      _result.push(storeMappingPair(state, null, overridableKeys, keyTag, keyNode, valueNode))
     } else {
       _result.push(keyNode)
     }
@@ -1274,9 +1246,6 @@ function readBlockSequence (state, nodeIndent) {
 
 function readBlockMapping (state, nodeIndent, flowIndent) {
   let allowCompact
-  let _keyLine
-  let _keyLineStart
-  let _keyPos
   const _tag = state.tag
   const _anchor = state.anchor
   const _result = {}
@@ -1313,7 +1282,7 @@ function readBlockMapping (state, nodeIndent, flowIndent) {
     if ((ch === 0x3F/* ? */ || ch === 0x3A/* : */) && isWsOrEol(following)) {
       if (ch === 0x3F/* ? */) {
         if (atExplicitKey) {
-          storeMappingPair(state, _result, overridableKeys, keyTag, keyNode, null, _keyLine, _keyLineStart, _keyPos)
+          storeMappingPair(state, _result, overridableKeys, keyTag, keyNode, null)
           keyTag = keyNode = valueNode = null
         }
 
@@ -1335,10 +1304,6 @@ function readBlockMapping (state, nodeIndent, flowIndent) {
     // Implicit notation case. Flow-style node as the key first, then ":", and the value.
     //
     } else {
-      _keyLine = state.line
-      _keyLineStart = state.lineStart
-      _keyPos = state.position
-
       if (!composeNode(state, flowIndent, CONTEXT_FLOW_OUT, false, true)) {
         // Neither implicit nor explicit notation.
         // Reading is done. Go to the epilogue.
@@ -1360,7 +1325,7 @@ function readBlockMapping (state, nodeIndent, flowIndent) {
           }
 
           if (atExplicitKey) {
-            storeMappingPair(state, _result, overridableKeys, keyTag, keyNode, null, _keyLine, _keyLineStart, _keyPos)
+            storeMappingPair(state, _result, overridableKeys, keyTag, keyNode, null)
             keyTag = keyNode = valueNode = null
           }
 
@@ -1389,12 +1354,6 @@ function readBlockMapping (state, nodeIndent, flowIndent) {
     // Common reading code for both explicit and implicit notations.
     //
     if (state.line === _line || state.lineIndent > nodeIndent) {
-      if (atExplicitKey) {
-        _keyLine = state.line
-        _keyLineStart = state.lineStart
-        _keyPos = state.position
-      }
-
       if (composeNode(state, nodeIndent, CONTEXT_BLOCK_OUT, true, allowCompact)) {
         if (atExplicitKey) {
           keyNode = state.result
@@ -1404,7 +1363,7 @@ function readBlockMapping (state, nodeIndent, flowIndent) {
       }
 
       if (!atExplicitKey) {
-        storeMappingPair(state, _result, overridableKeys, keyTag, keyNode, valueNode, _keyLine, _keyLineStart, _keyPos)
+        storeMappingPair(state, _result, overridableKeys, keyTag, keyNode, valueNode)
         keyTag = keyNode = valueNode = null
       }
 
@@ -1425,7 +1384,7 @@ function readBlockMapping (state, nodeIndent, flowIndent) {
 
   // Special case: last mapping's node contains only the key in explicit notation.
   if (atExplicitKey) {
-    storeMappingPair(state, _result, overridableKeys, keyTag, keyNode, null, _keyLine, _keyLineStart, _keyPos)
+    storeMappingPair(state, _result, overridableKeys, keyTag, keyNode, null)
   }
 
   // Expose the resulting mapping.
@@ -1807,12 +1766,10 @@ function composeNode (state, parentIndent, nodeContext, allowToSeek, allowCompac
 }
 
 function readDocument (state) {
-  const documentStart = state.position
   let hasDirectives = false
   let ch
 
   state.version = null
-  state.checkLineBreaks = state.legacy
   state.tagMap = Object.create(null)
   state.anchorMap = Object.create(null)
 
@@ -1864,10 +1821,9 @@ function readDocument (state) {
 
     if (ch !== 0) readLineBreak(state)
 
+    // An unknown directive is ignored.
     if (_hasOwnProperty.call(directiveHandlers, directiveName)) {
       directiveHandlers[directiveName](state, directiveName, directiveArgs)
-    } else {
-      throwWarning(state, 'unknown document directive "' + directiveName + '"')
     }
   }
 
@@ -1886,11 +1842,6 @@ function readDocument (state) {
   composeNode(state, state.lineIndent - 1, CONTEXT_BLOCK_OUT, false, true)
   skipSeparationSpace(state, true, -1)
 
-  if (state.checkLineBreaks &&
-      PATTERN_NON_ASCII_LINE_BREAKS.test(state.input.slice(documentStart, state.position))) {
-    throwWarning(state, 'non-ASCII line breaks are interpreted as content')
-  }
-
   state.documents.push(state.result)
 
   if (state.position === state.lineStart && testDocumentSeparator(state)) {

package/src/workspace/agent-cli.ts

@@ -3,7 +3,8 @@
  * an agent session reloads from, read from the repository alone.
  *
  * A session is declared in the declaration's `agents` list and bound to one
- * member. This prints the session, its member, its write scope (the files
+ * member or several (ws-101). This prints the session, its members, its
+ * write scope (the files
  * and the record kinds, with their verbs, it may write) and the spec: the
  * `spec` block `chant workspace records --current --json` prints (#2546). An
  * agent that resumes needs nothing else: no memory of an earlier run, no
@@ -45,6 +46,13 @@ export interface AgentKindScope {
   verbs: WriteVerb[];
 }
 
+/** A member an agent session is bound to. */
+export interface AgentMember {
+  name: string;
+  dir: string;
+  kind: string;
+}
+
 interface Head {
   $schema: string;
   contract: number;
@@ -54,11 +62,18 @@ interface Head {
 export type AgentDocument =
   | (Head & {
       workspace: { name: string; root: string; scopeFrom: "base" | "working-tree" };
-      agent: { name: string; member: { name: string; dir: string; kind: string }; principals: string[] };
+      agent: {
+        name: string;
+        /** The first member the session is bound to, kept for readers of a one-member session. */
+        member: AgentMember;
+        /** Every member the session is bound to, in the order it names them (ws-101). */
+        members: AgentMember[];
+        principals: string[];
+      };
       scope: {
-        /** The one member whose files the session writes. */
+        /** The members whose files the session writes. */
         members: string[];
-        /** Every declared kind in reach: the workspace's own and the member's. */
+        /** Every declared kind in reach: the workspace's own, then each member's. */
         records: AgentKindScope[];
         /** The paths writeScope.agent.protected keeps the session from writing, with the JSON keys each still allows (#3146). */
         protected: { path: string; except: string[] }[];
@@ -81,13 +96,14 @@ export async function agentSession(q: { cwd: string; name: string }): Promise<Ag
     const decl = source.declaration;
     const writer = resolveWriter(decl, source.policy, { agent: q.name }, source.classes);
     const agent = writer.agent!;
-    const member = decl.members.find((m) => m.name === agent.member)!;
+    const bound = agent.members.map((name) => decl.members.find((m) => m.name === name)!);
+    const members: AgentMember[] = bound.map((m) => ({ name: m.name, dir: m.dir, kind: m.kind }));
     const scope = scopeOf(decl, writer)!;
     const rules = scope.records;
     // The spec query, over every declared kind in the working tree.
     const set = await queryDeclaredRecords(declaredKindFiles(q.cwd), { cwd: q.cwd, current: true });
     const loadedName = new Map(set.kinds.map((k) => [k.declared.path, "error" in k ? null : k.kind.name]));
-    const records: AgentKindScope[] = [...decl.records, ...member.records].map((d) => {
+    const records: AgentKindScope[] = [...decl.records, ...bound.flatMap((m) => m.records)].map((d) => {
       const kind = loadedName.get(d.path) ?? null;
       const names = [kind, d.name].filter((n): n is string => n !== null);
       const verbs = rules === null ? [...WRITE_VERBS] : WRITE_VERBS.filter((v) => names.some((n) => (rules[n] ?? []).includes(v)));
@@ -96,8 +112,8 @@ export async function agentSession(q: { cwd: string; name: string }): Promise<Ag
     return {
       ...head,
       workspace: { name: decl.name, root: source.root ?? ".", scopeFrom: source.from },
-      agent: { name: agent.name, member: { name: member.name, dir: member.dir, kind: member.kind }, principals: agent.principals },
-      scope: { members: [member.name], records, protected: scope.protected.map((p) => ({ path: p.path, except: [...p.except] })) },
+      agent: { name: agent.name, member: members[0], members, principals: agent.principals },
+      scope: { members: members.map((m) => m.name), records, protected: scope.protected.map((p) => ({ path: p.path, except: [...p.except] })) },
       spec: set.spec ?? { kinds: [], records: [] },
       reload: [`chant workspace agent ${agent.name} --json`, "chant workspace records --current --json"],
     };
@@ -127,7 +143,8 @@ export async function runWorkspaceAgent(ctx: CommandContext): Promise<number> {
   }
   if (args.json || args.format === "json") return 0;
   const out: string[] = [];
-  out.push(`agent     ${doc.agent.name}, bound to member ${doc.agent.member.name} (${doc.agent.member.dir}), scope read from ${doc.workspace.scopeFrom}`);
+  const bound = doc.agent.members.map((m) => `${m.name} (${m.dir})`).join(", ");
+  out.push(`agent     ${doc.agent.name}, bound to ${doc.agent.members.length === 1 ? "member" : "members"} ${bound}, scope read from ${doc.workspace.scopeFrom}`);
   for (const r of doc.scope.records) out.push(`records   ${r.name ?? r.kind ?? r.path} (${r.path}): ${r.verbs.length > 0 ? r.verbs.join(", ") : "not writable"}`);
   for (const p of doc.scope.protected) out.push(`protected ${p.path}${p.except.length > 0 ? ` (except ${p.except.join(", ")})` : ""}`);
   out.push(`spec      ${doc.spec.records.length} current records of ${doc.spec.kinds.length} spec kinds`);

package/src/workspace/agent.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://intentius.io/chant/schemas/workspace/agent/v1/agent.schema.json",
   "title": "chant workspace agent output",
-  "description": "What `chant workspace agent <name> --json` prints (#2524 D20, #2548, ws-067): an agent session, the one member it is bound to, its write scope and the spec, read from the repository alone, so a session that resumes rebuilds its context from this and nothing else. The session and its scope are read from the declaration at base, as the write paths and check --changes read them; the spec from the working tree. Readers ignore fields they do not know; a field is only ever added within a version. The error codes are a closed list, and every one is in the one closed list of `reason-codes.ts`. Contract version 1; this document was added to it by #2548.",
+  "description": "What `chant workspace agent <name> --json` prints (#2524 D20, #2548, ws-067): an agent session, the members it is bound to (one, or several since ws-101), its write scope and the spec, read from the repository alone, so a session that resumes rebuilds its context from this and nothing else. The session and its scope are read from the declaration at base, as the write paths and check --changes read them; the spec from the working tree. Readers ignore fields they do not know; a field is only ever added within a version. The error codes are a closed list, and every one is in the one closed list of `reason-codes.ts`. Contract version 1; this document was added to it by #2548.",
   "oneOf": [
     {
       "$ref": "#/$defs/result"
@@ -72,23 +72,16 @@
               "type": "string"
             },
             "member": {
-              "type": "object",
-              "required": [
-                "name",
-                "dir",
-                "kind"
-              ],
-              "properties": {
-                "name": {
-                  "type": "string"
-                },
-                "dir": {
-                  "type": "string"
-                },
-                "kind": {
-                  "type": "string"
-                }
-              }
+              "$ref": "#/$defs/member",
+              "description": "The first member the session is bound to, the only one for a session that names one member."
+            },
+            "members": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "$ref": "#/$defs/member"
+              },
+              "description": "Added in contract 1 by #3505. Every member the session is bound to, in the order its declaration names them (ws-101); the first is member."
             },
             "principals": {
               "type": "array",
@@ -111,11 +104,11 @@
               "items": {
                 "type": "string"
               },
-              "description": "The one member whose files the session writes."
+              "description": "The members whose files the session writes: every member it is bound to, in the order its declaration names them."
             },
             "records": {
               "type": "array",
-              "description": "Every declared record kind in the session's reach: the workspace's own kinds, then the member's.",
+              "description": "Every declared record kind in the session's reach: the workspace's own kinds, then each member's, in the order of members.",
               "items": {
                 "type": "object",
                 "required": [
@@ -168,7 +161,7 @@
             },
             "protected": {
               "type": "array",
-              "description": "Added in contract 1 by #3146. The paths writeScope.agent.protected keeps the session from writing even inside its member, each a glob from the workspace root that also covers everything under a directory it matches, with the top-level keys of a JSON file a write may still change in except. Empty when none is listed. check --changes reports a write to one with write-scope-protected.",
+              "description": "Added in contract 1 by #3146. The paths writeScope.agent.protected keeps the session from writing even inside its members, each a glob from the workspace root that also covers everything under a directory it matches, with the top-level keys of a JSON file a write may still change in except. Empty when none is listed. check --changes reports a write to one with write-scope-protected.",
               "items": {
                 "type": "object",
                 "required": [
@@ -337,6 +330,25 @@
         "scope": false
       }
     },
+    "member": {
+      "type": "object",
+      "required": [
+        "name",
+        "dir",
+        "kind"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "dir": {
+          "type": "string"
+        },
+        "kind": {
+          "type": "string"
+        }
+      }
+    },
     "asset": {
       "type": "object",
       "required": [

package/src/workspace/broker-protocol.schema.json

@@ -35,14 +35,16 @@
     },
     "declarationReport": {
       "type": "object",
-      "description": "POST /api/box/declaration: the capabilities chant workspace status --json lists for the box's block, sent by the box's steward with the box's own token. At most 32 KB. Each report replaces the last.",
+      "description": "POST /api/box/declaration: the capabilities chant workspace status --json lists for the box's block, sent by the box's steward with the box's own token, and, optionally, the box's listing and this month's spend (#3508, ws-102). At most 32 KB. Each report replaces the last.",
       "required": ["capabilities"],
       "properties": {
         "capabilities": {
           "type": "array",
           "maxItems": 20,
           "items": { "$ref": "#/$defs/capability" }
-        }
+        },
+        "listing": { "$ref": "#/$defs/listing" },
+        "spend": { "$ref": "#/$defs/spend" }
       }
     },
     "declarationKept": {
@@ -63,9 +65,49 @@
           }
         },
         "at": { "type": "string", "minLength": 1, "description": "An ISO 8601 time." },
-        "payer": { "$ref": "#/$defs/payer" }
+        "payer": { "$ref": "#/$defs/payer" },
+        "listing": { "$ref": "#/$defs/listing", "description": "The report's listing, when the broker keeps one." },
+        "spend": { "$ref": "#/$defs/spend", "description": "The report's spend, when the broker keeps one." }
+      }
+    },
+    "listing": {
+      "type": "object",
+      "description": "Optional in a report, added within version 1 by #3508 (ws-102). The box block's listing (ws-077) as chant workspace status --json prints it, less the cover: what a broker that lists boxes lists this one under. The bounds are the ones chant workspace box listing set writes with. A broker that lists no boxes ignores it.",
+      "required": ["title", "line"],
+      "properties": {
+        "published": { "type": "boolean", "description": "Whether the box is listed for people other than its owner. Absent means true." },
+        "title": { "type": "string", "maxLength": 60, "pattern": "^[^\\u0000-\\u001f\\u007f]*$" },
+        "line": { "type": "string", "maxLength": 140, "pattern": "^[^\\u0000-\\u001f\\u007f]*$" }
+      }
+    },
+    "spend": {
+      "type": "object",
+      "description": "Optional in a report, added within version 1 by #3508 (ws-102). What the box's run records (chant workspace runs --json, ws-076) say it spent in one calendar month, by each run's startedAt: the month's totals, and the same per principal the runs worked for. Only USD costs are summed: a run with no USD cost is counted in unpriced, never as zero. spendFromRuns in broker-protocol.ts computes it. A broker that reports no spend ignores it.",
+      "required": ["month", "usd", "runs", "unpriced", "byPrincipal"],
+      "properties": {
+        "month": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "description": "The month, YYYY-MM, in UTC." },
+        "usd": { "$ref": "#/$defs/spendUsd" },
+        "runs": { "$ref": "#/$defs/spendCount" },
+        "unpriced": { "$ref": "#/$defs/spendCount" },
+        "byPrincipal": {
+          "type": "array",
+          "maxItems": 50,
+          "description": "Per principal, as the run records' by names them (ws-080's form), at most 50; principal is null for the runs that name none.",
+          "items": {
+            "type": "object",
+            "required": ["principal", "usd", "runs", "unpriced"],
+            "properties": {
+              "principal": { "type": ["string", "null"], "minLength": 1, "maxLength": 200 },
+              "usd": { "$ref": "#/$defs/spendUsd" },
+              "runs": { "$ref": "#/$defs/spendCount" },
+              "unpriced": { "$ref": "#/$defs/spendCount" }
+            }
+          }
+        }
       }
     },
+    "spendUsd": { "type": "number", "minimum": 0, "exclusiveMaximum": 1000000000, "description": "The sum of the priced runs' USD costs." },
+    "spendCount": { "type": "integer", "minimum": 0, "exclusiveMaximum": 1000000000, "description": "A count of runs: all of them under runs, those with no USD cost under unpriced." },
     "payer": {
       "type": "object",
       "description": "Whose credential pays for the box's model calls (#3474, ws-098), when the broker says. shared: a credential neither the box's owner nor its visitor owns, such as a house or operator key. owner: the box owner's own. visitor: the credential a person brought for this box. principal is the payer in ws-080's form (github:<login>) when the broker knows them, else null. Optional: a broker that does not say leaves it out, and a box treats that as unknown. The same fact rides on each answer from /llm/anthropic and /decide as the chant-payer header.",