@intentius/chant 0.104.4 → 0.105.0

package/src/workspace/declaration.ts

@@ -119,7 +119,7 @@ export type WriteVerb = (typeof WRITE_VERBS)[number];
 
 /** One principal class's entry in the declaration's `writeScope` (#2548, ws-067). */
 export interface ClassScope {
-  /** The members whose files the class may write, or null for every path. Always null for the agent class: a session writes its own member. */
+  /** The members whose files the class may write, or null for every path. Always null for the agent class: a session writes the members it is bound to. */
   members: string[] | null;
   /** Kind name to the verbs the class may write it with, or null for every kind in reach with every verb. */
   records: Record<string, WriteVerb[]> | null;
@@ -164,9 +164,16 @@ export interface IdentityPolicy {
   gates: Record<string, SignedGate>;
 }
 
-/** An agent session the declaration names (#2524 D20, #2548): bound to one member. */
+/**
+ * An agent session the declaration names (#2524 D20, #2548): bound to the
+ * members it lists, one or more (ws-101). It writes the files of each, and
+ * the records of kinds any of them or the workspace declares.
+ */
 export interface AgentDeclaration {
   name: string;
+  /** The members the session is bound to, in file order: `members`, or the one `member` names. Never empty. */
+  members: string[];
+  /** The first of `members`, kept for readers of a one-member session. */
   member: string;
   /** Principals that write only as this session. */
   principals: string[];
@@ -952,8 +959,8 @@ function writeScopeOf(raw: unknown, members: Member[], at: (pointer: string, key
 
 /**
  * The `agents` list, already validated, with the rules the schema can't say
- * (#2548): names are unique, each names a declared member, and a principal
- * is listed by one session at most.
+ * (#2548, ws-101): names are unique, every member a session names is a
+ * declared member, and a principal is listed by one session at most.
  */
 /** The `identity` block, already validated by the schema (#3163). */
 function identityOf(raw: unknown): IdentityPolicy | null {
@@ -967,23 +974,30 @@ function identityOf(raw: unknown): IdentityPolicy | null {
 }
 
 function agentsOf(raw: unknown, members: Member[], at: (pointer: string, key?: boolean) => ErrorLocation): AgentDeclaration[] {
-  const agents = ((raw as { name: string; member: string; principals?: string[] }[] | undefined) ?? []).map((a, i) => ({
-    name: a.name,
-    member: a.member,
-    principals: [...(a.principals ?? [])],
-    pointer: `/agents/${i}`,
-  }));
+  const agents = ((raw as { name: string; member?: string; members?: string[]; principals?: string[] }[] | undefined) ?? []).map((a, i) => {
+    // The schema requires exactly one of member and members (ws-101).
+    const bound = a.members !== undefined ? [...a.members] : [a.member!];
+    return {
+      name: a.name,
+      members: bound,
+      member: bound[0],
+      principals: [...(a.principals ?? [])],
+      pointer: `/agents/${i}`,
+      listed: a.members !== undefined,
+    };
+  });
   const byName = new Map<string, AgentDeclaration>();
   const byPrincipal = new Map<string, AgentDeclaration>();
-  for (const a of agents) {
+  for (const { listed, ...a } of agents) {
     const first = byName.get(a.name);
     if (first) throw new WorkspaceReadError("declaration-invalid", `the agent name ${JSON.stringify(a.name)} is already used by the agent at ${first.pointer}`, at(`${a.pointer}/name`));
     byName.set(a.name, a);
-    if (!members.some((m) => m.name === a.member)) {
+    for (const [i, name] of a.members.entries()) {
+      if (members.some((m) => m.name === name)) continue;
       throw new WorkspaceReadError(
         "declaration-invalid",
-        `agent ${a.name} is bound to ${JSON.stringify(a.member)}, which is not a declared member; an agent session is bound to one member, not an example group`,
-        at(`${a.pointer}/member`),
+        `agent ${a.name} is bound to ${JSON.stringify(name)}, which is not a declared member; an agent session is bound to members, not an example group`,
+        at(listed ? `${a.pointer}/members/${i}` : `${a.pointer}/member`),
       );
     }
     for (const [i, p] of a.principals.entries()) {
@@ -992,7 +1006,7 @@ function agentsOf(raw: unknown, members: Member[], at: (pointer: string, key?: b
       byPrincipal.set(p, a);
     }
   }
-  return agents;
+  return [...byName.values()];
 }
 
 /** The `changes` block, already validated, with its defaults (#2773). */

package/src/workspace/export.ts

@@ -414,9 +414,16 @@ export async function exportWorkspace(o: ExportOptions): Promise<ExportResult> {
           return keep.length > 0 ? { ...rest, links: keep } : rest;
         });
     } else if (key === "agents") {
-      const agents = value as { name: string; member: string }[];
-      for (const a of agents) if (!names.has(a.member)) dropped.agents.push(a.name);
-      outDecl.agents = agents.filter((a) => names.has(a.member));
+      // A session bound to several members (ws-101) keeps those that go, and is dropped when none does.
+      const agents = value as { name: string; member?: string; members?: string[] }[];
+      const kept: Record<string, unknown>[] = [];
+      for (const a of agents) {
+        const bound = a.members ?? (a.member !== undefined ? [a.member] : []);
+        const going = bound.filter((m) => names.has(m));
+        if (going.length === 0) dropped.agents.push(a.name);
+        else kept.push(a.members !== undefined ? { ...a, members: going } : a);
+      }
+      outDecl.agents = kept;
     } else if (key === "pins") {
       const pins = value as { path?: string; package?: string }[];
       for (const p of pins) if (p.path !== undefined) dropped.pins.push(p.path);

package/src/workspace/factory-rules.test.ts

@@ -8,7 +8,7 @@ import { describe, expect, test } from "vitest";
 import { isAsk, pickable, retryState, doneVerdict, proposeImplements, understandOutcome, type FactoryContext, type FactoryItem } from "./factory-rules";
 
 describe("the factory's rules", () => {
-  const base: FactoryItem = { id: "W-1", state: "open", openState: "open", proposedState: "proposed", ready: true, data: {}, tier: null, contract: null, warnings: [], answers: [], leased: false };
+  const base: FactoryItem = { id: "W-1", state: "open", openState: "open", proposedState: "proposed", ready: true, data: {}, tier: null, contract: { id: "C-1", state: "approved" }, warnings: [], answers: [], leased: false };
   const ctx: FactoryContext = { intentDecided: null, claims: [], attempts: { exhausted: false }, branch: null, questions: { tier: null, understand: null } };
   const hold = (i: Partial<FactoryItem>, c: Partial<FactoryContext> = {}) => {
     const v = pickable({ ...base, ...i }, { ...ctx, ...c });
@@ -19,6 +19,11 @@ describe("the factory's rules", () => {
     expect(hold({})).toBe("ok");
     expect(hold({}, { intentDecided: false })).toBe("intent-undecided");
     expect(hold({ ready: false })).toBe("not-ready");
+    // Only an item that names a contract, an ask or an intent build is the factory's (#3503).
+    expect(hold({ contract: null })).toBe("no-contract");
+    expect(hold({ contract: null, data: { source: { kind: "finding", finding: "F-1" } } })).toBe("no-contract");
+    expect(hold({ contract: null, data: { source: { ask: { said: "x", by: "a" } } } })).toBe("ok");
+    expect(hold({ contract: null, data: { source: { intent: { answer: "x" } } } })).toBe("ok");
     expect(hold({ ready: false, state: "proposed", data: { source: { ask: { said: "x", by: "a" } } } })).toBe("ok");
     expect(hold({ contract: { id: "C-1", state: "draft" }, warnings: ["work-contract-undecided"] })).toBe("contract-not-approved");
     expect(hold({}, { branch: { state: "done", applied: false } })).toBe("built-not-applied");

package/src/workspace/factory-rules.ts

@@ -4,8 +4,11 @@
  * reference Op (`../op/factory.ts`) runs them; an orchestrator supplies only
  * execution (the builder, the context, the check).
  *
- * - Readiness ({@link pickable}): on top of the work kind's `ready`, the box's
- *   intent is decided, a contract the item builds is approved and in force,
+ * - Readiness ({@link pickable}): the item names a contract, or is an ask or
+ *   the box's first build from its intent ({@link isAsk}); a work item a
+ *   person wrote by hand or a finding's triage item stays with its author
+ *   (#3503). On top of the work kind's `ready`, the box's intent is decided,
+ *   a contract the item builds is approved and in force,
  *   the item is under its attempt limit, it is not done and waiting to be
  *   applied on its branch, its slice-tier and understand questions are not
  *   open, an understand answer of redraft or ask holds it, and a failed last
@@ -37,6 +40,7 @@ export type UnderstandAnswer = (typeof UNDERSTAND_ANSWERS)[number];
 /** Why an item is not picked. Closed. */
 export const FACTORY_HOLDS = [
   "not-ready",
+  "no-contract",
   "intent-undecided",
   "contract-not-approved",
   "attempts-exhausted",
@@ -133,7 +137,9 @@ export function understandOutcome(answer: unknown): "dropped" | "redraft" | "ask
 const OPEN = new Set(["escalated", "proposed"]);
 
 /**
- * Whether the factory picks `item` now, or why not. Asks are candidates while
+ * Whether the factory picks `item` now, or why not. The factory builds an
+ * item that names a contract, an ask, or an intent build, as studio's queue
+ * did (#3503); any other item is its author's. Asks are candidates while
  * proposed as well as open; any other item only when the work kind reads it
  * ready.
  */
@@ -142,6 +148,7 @@ export function pickable(item: FactoryItem, ctx: FactoryContext): { ok: true } |
   if (ctx.intentDecided === false) return no("intent-undecided", "the box's intent is not decided yet, so nothing is picked");
   if (item.leased) return no("leased", `${item.id} is leased`);
   const ask = isAsk(item.data);
+  if (!item.contract && !ask) return no("no-contract", `${item.id} names no contract and is not an ask or an intent build, so it is left to its author`);
   const candidate = item.ready || (ask && item.proposedState !== null && item.state === item.proposedState);
   if (!candidate) return no("not-ready", `${item.id} is ${item.state ?? "in no state"} and not ready`);
   if (item.contract && (item.warnings.includes("work-contract-undecided") || item.warnings.includes("work-contract-unknown"))) {

package/src/workspace/reason-codes.ts

@@ -141,7 +141,7 @@ export const REASONS = {
   "write-lock-timeout": "Another write held the working tree's write lock for longer than the write waits (CHANT_WRITE_LOCK_WAIT_MS); the refusal names the holder. Run the write again.",
   "write-lock-not-held": "CHANT_WRITE_LOCK names a batch's lock token that no longer holds the working tree's write lock: the batch released it, or it expired and another writer took it.",
   // Write scope (#2548): a records write that is refused, and a commit check --changes reports, outside the writer's scope.
-  "write-scope-member": "The write is to a file, or to a record kind, of a member outside the writer's scope: an agent session writes only its own member, and writeScope.<class>.members leaves the member out.",
+  "write-scope-member": "The write is to a file, or to a record kind, of a member outside the writer's scope: an agent session writes only the members it is bound to, and writeScope.<class>.members leaves the member out.",
   "write-scope-kind": "The write is to a record kind writeScope.<class>.records does not list, with a verb it does not list for the kind, or deletes a record.",
   "write-scope-protected": "The write is to a file writeScope.<class>.protected lists, or one under a directory it lists, outside the top-level keys or JSON Pointers the entry's except allows (#3146, #3308).",
   "write-scope-class-unknown": "The declaration's writeScope at base names a principal class no pinned package supplies, and the writer is judged human, so it may be in that class; the write is refused until the package is installed at the pinned version or the entry removed (#3080).",

package/src/workspace/write-scope.test.ts

@@ -127,6 +127,9 @@ describe("the declaration's writeScope and agents (#2548)", () => {
     ["a principal two sessions list", declaration(SCOPE, [{ name: "a", member: "app", principals: ["p"] }, { name: "b", member: "design", principals: ["p"] }]), /already listed by agent a/],
     ["two sessions with one name", declaration(SCOPE, [{ name: "a", member: "app" }, { name: "a", member: "design" }]), /already used/],
     ["a members list on the agent class", declaration({ agent: { members: ["app"] } }), /members/],
+    ["an agent naming an undeclared member among several", declaration(SCOPE, [{ name: "a", members: ["app", "nowhere"] }]), /"nowhere", which is not a declared member/],
+    ["an agent with both member and members", declaration(SCOPE, [{ name: "a", member: "app", members: ["design"] }]), /oneOf|exactly one|must match/],
+    ["an agent with an empty members list", declaration(SCOPE, [{ name: "a", members: [] }]), /fewer than 1|minItems|members/],
     ["an unknown verb", declaration({ agent: { records: { decision: ["delete"] } } }), /must be equal to one of the allowed values|delete/],
   ])("refuse %s", (_, text, message) => {
     let err: unknown;
@@ -210,6 +213,19 @@ describe("judging a write", () => {
     expect(judgeRecord(decl, human, screen, "delete")).toEqual({ ok: true });
   });
 
+  test("an agent bound to several members writes in any of them, and its scope is their union (ws-101)", () => {
+    const d = parseDeclaration(declaration(SCOPE, [...AGENTS, { name: "factory", members: ["app", "design"] }]), "chant.workspace.json");
+    expect(d.agents.find((a) => a.name === "factory")).toMatchObject({ members: ["app", "design"], member: "app" });
+    expect(d.agents.find((a) => a.name === "app-agent")).toMatchObject({ members: ["app"], member: "app" });
+    const factory = resolveWriter(d, policy, { agent: "factory" });
+    expect(judgePath(d, factory, "app/server.mjs")).toEqual({ ok: true });
+    expect(judgePath(d, factory, "design/spec.md")).toEqual({ ok: true });
+    expect(judgePath(d, factory, "chant.workspace.json")).toMatchObject({ ok: false, code: "write-scope-member", message: expect.stringContaining("agent session factory, bound to members app, design,") });
+    expect(judgeRecord(d, factory, screen, "new")).toEqual({ ok: true });
+    expect(judgeRecord(d, factory, ws, "new")).toEqual({ ok: true });
+    expect(judgeRecord(d, factory, screen, "amend")).toMatchObject({ ok: false, code: "write-scope-kind" });
+  });
+
   test("the declared name of a kind is a key for its records rule too", () => {
     const d = parseDeclaration(declaration({ agent: { records: { screen: ["new"] } } }), "chant.workspace.json");
     const design = resolveWriter(d, policy, { agent: "design-agent" });
@@ -335,7 +351,8 @@ describe("chant workspace agent: what a session reloads from (#2548)", () => {
     agent.expectValid(doc);
     if ("error" in doc) throw new Error(doc.error.message);
     expect(doc.workspace).toEqual({ name: "studio", root: ".", scopeFrom: "base" });
-    expect(doc.agent).toEqual({ name: "design-agent", member: { name: "design", dir: "design", kind: "other" }, principals: [] });
+    const design = { name: "design", dir: "design", kind: "other" };
+    expect(doc.agent).toEqual({ name: "design-agent", member: design, members: [design], principals: [] });
     expect(doc.scope).toEqual({
       members: ["design"],
       records: [

package/src/workspace/write-scope.ts

@@ -1,14 +1,16 @@
 /**
  * Write scope per member and record kind, for each principal class, and the
- * agent sessions bound to one member (#2524 D5, D20; #2548; ws-067).
+ * agent sessions bound to the members they name (#2524 D5, D20; #2548;
+ * ws-067, ws-101).
  *
  * The declaration's `writeScope` block gives a restricted class the members
  * whose files it may write and the record kinds it may write, with which
  * verbs (`new`, `amend`, `review`, `close`). A class with no entry is not
  * restricted. The declaration's `agents` list names agent sessions, each
- * bound to one member: a session writes that member's files, and the records
- * of kinds that member or the workspace declares, as `writeScope.agent`
- * allows. An agent's members can't be widened.
+ * bound to one member or several (ws-101): a session writes the files of any
+ * of its members, and the records of kinds any of them or the workspace
+ * declares, as `writeScope.agent` allows. The scope is the union of its
+ * members, and `writeScope.agent` can't widen it.
  *
  * Two places apply it, both reading the scope from the base revision so a
  * change can't widen its own scope (#2524 threat model):
@@ -170,7 +172,7 @@ export function unknownClassVerdict(declaration: Declaration | null, writer: Wri
   };
 }
 
-/** The scope that applies to `writer`, or null when its class is not restricted. An agent is always restricted to its member. */
+/** The scope that applies to `writer`, or null when its class is not restricted. An agent is always restricted to its members. */
 export function scopeOf(declaration: Declaration | null, writer: Writer): ClassScope | null {
   const entry = declaration?.writeScope?.[writer.class];
   if (writer.class === "agent") return { members: null, records: entry?.records ?? null, protected: entry?.protected ?? [], pointer: entry?.pointer ?? "/agents" };
@@ -185,14 +187,17 @@ export type RecordVerdict = { ok: true } | { ok: false; code: Exclude<WriteScope
 const OK = { ok: true } as const;
 
 function who(writer: Writer): string {
-  if (writer.agent) return `agent session ${writer.agent.name}, bound to member ${writer.agent.member},`;
+  if (writer.agent) {
+    const bound = writer.agent.members;
+    return `agent session ${writer.agent.name}, bound to ${bound.length === 1 ? "member" : "members"} ${bound.join(", ")},`;
+  }
   const name = writer.principal !== null ? `${writer.principal} (${writer.class})` : `a ${writer.class} writer`;
   return writer.class === "agent" ? `${name}, which no agent session lists,` : name;
 }
 
-/** Whether `writer` may write in `member` (null: a path in no member). */
+/** Whether `writer` may write in `member` (null: a path in no member). An agent session may write in any member it is bound to (ws-101). */
 function memberAllowed(writer: Writer, scope: ClassScope, member: string | null): boolean {
-  if (writer.class === "agent") return member !== null && member === writer.agent?.member;
+  if (writer.class === "agent") return member !== null && (writer.agent?.members.includes(member) ?? false);
   return scope.members === null || (member !== null && scope.members.includes(member));
 }
 
@@ -219,7 +224,7 @@ export function judgeRecord(declaration: Declaration | null, writer: Writer, kin
     return {
       ok: false,
       code: "write-scope-member",
-      message: `${who(writer)} may not write ${kind.name} records, which are ${where}: ${writer.class === "agent" ? "an agent session writes only its own member" : `writeScope.${writer.class}.members leaves it out`}`,
+      message: `${who(writer)} may not write ${kind.name} records, which are ${where}: ${writer.class === "agent" ? "an agent session writes only the members it is bound to" : `writeScope.${writer.class}.members leaves it out`}`,
     };
   }
   if (verb === "delete") {
@@ -319,7 +324,7 @@ export function judgePath(declaration: Declaration | null, writer: Writer, path:
     return {
       ok: false,
       code: "write-scope-member",
-      message: `${who(writer)} may not write ${path}, which ${where}: ${writer.class === "agent" ? "an agent session writes only its own member" : `writeScope.${writer.class}.members leaves it out`}`,
+      message: `${who(writer)} may not write ${path}, which ${where}: ${writer.class === "agent" ? "an agent session writes only the members it is bound to" : `writeScope.${writer.class}.members leaves it out`}`,
     };
   }
   const guarded = protectedEntry(scope.protected, path);