@intentius/chant 0.109.0 → 0.111.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.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/write-scope.ts

@@ -403,6 +403,23 @@ export function scopedKind(source: ScopeSource, kindName: string, kindFile: stri
   return { name: kindName, declaredName: null, member: dir.startsWith("..") ? null : memberHolding(dir === "" ? "." : dir, decl.members), declared: false };
 }
 
+/**
+ * The agent sessions as `chant workspace agent` and the write paths read
+ * them (#3615): the declaration at base, else the working tree's. Null when
+ * neither has a declaration. Lighter than {@link scopeSource}: no trust
+ * policy and no principal classes.
+ */
+export function declaredSessions(cwd: string): { agents: AgentDeclaration[]; from: "base" | "working-tree" } | null {
+  const top = gitRoot(cwd);
+  const base = top ? resolveBase(top) : null;
+  if (base?.commit) {
+    const atBase = readAt(cwd, base.commit);
+    if (atBase) return { agents: atBase.declaration.agents, from: "base" };
+  }
+  const here = readAt(cwd);
+  return here ? { agents: here.declaration.agents, from: "working-tree" } : null;
+}
+
 /**
  * Refuse a record write outside the writer's scope (#2548): throws a
  * {@link WriteScopeError}. `agent` is the session the write names

package/src/yaml.test.ts

@@ -26,6 +26,12 @@ describe("emitYAML", () => {
     expect(emitYAML([undefined, 1], 0)).toBe("\n- null\n- 1");
   });
 
+  test("an empty mapping in a list is an item, not nothing", () => {
+    expect(emitYAML([{}], 0)).toBe("\n- {}");
+    expect(emitYAML({ egress: [{}] }, 0)).toBe("\negress:\n  - {}");
+    expect(emitYAML([{ a: undefined }, { b: 1 }], 0)).toBe("\n- {}\n- b: 1");
+  });
+
   test("booleans", () => {
     expect(emitYAML(true, 0)).toBe("true");
     expect(emitYAML(false, 0)).toBe("false");

package/src/yaml.ts

@@ -127,6 +127,10 @@ export function emitYAML(value: unknown, indent: number): string {
               lines.push(`${prefix}  ${key}: ${emitted}`);
             }
           }
+        } else {
+          // An empty mapping is still an item: `egress: [{}]` allows all
+          // egress, and dropping it leaves an empty list.
+          lines.push(`${prefix}- {}`);
         }
       } else {
         lines.push(`${prefix}- ${emitYAML(item, indent + 1).trimStart()}`);