@intentius/chant 0.100.0 → 0.101.0

package/src/workspace/checks/live.ts

@@ -0,0 +1,113 @@
+/**
+ * The live link checks, WSP141 and WSP142 (#2549; #2524 D6, ws-062).
+ *
+ * `chant workspace check --live --env <env>` resolves each declared member
+ * link against what its producer's estate publishes now. It reads the live
+ * graph the way `chant workspace graph --live --env <env>` does: each `chant`
+ * member runs `chant graph --live` under its own toolchain, and the outputs of
+ * the live graph (the stack outputs a lexicon's live read reports) are the
+ * names a link may match, exactly. That is the one place this command reaches
+ * a network, through the member's own chant, with the member's own
+ * credentials. Without `--live` none of this runs, and the source checks
+ * (`./links.ts`) stay offline.
+ *
+ * | Id | Fails when |
+ * |---|---|
+ * | WSP141 | the producer was read live and publishes no output of that name |
+ * | WSP142 | the link could not be resolved live: the producer's kind is not read live, its read failed, or the read returned no outputs at all |
+ *
+ * Only declared links of kind `output` are resolved live. A `telemetry` link
+ * names a collector's pipeline or exporter, which the graph reports from the
+ * member's source, so it is not part of this check.
+ */
+
+import type { WorkspaceCheck, WorkspaceDiagnostic } from "../checks";
+import type { Declaration } from "../declaration";
+import type { KindRegistry } from "../kinds";
+import { DEFAULT_LINK_KIND, irMemberHandles, resolveLinks, type LinkRow } from "../links";
+
+/** What a live read of the workspace found, for the live link checks. */
+export interface LiveLinkFacts {
+  env: string;
+  /** Every declared `output` link, resolved against the live outputs. */
+  rows: LinkRow[];
+}
+
+const describeLink = (row: LinkRow) => `${row.consumer}'s link to ${row.producer} output ${row.output}`;
+
+/**
+ * Read the live graph of the workspace at `cwd` for `env` and resolve the
+ * declared links against it. `onStderr` gets each member's stderr, which is
+ * where a lexicon's live read reports an account it could not reach.
+ */
+export async function gatherLiveLinkFacts(cwd: string, declaration: Declaration, kinds: KindRegistry, env: string, onStderr?: (text: string) => void): Promise<LiveLinkFacts> {
+  const { workspaceGraph } = await import("../graph-cli");
+  const { doc } = await workspaceGraph({ cwd, args: { live: true, env }, noCache: true, ...(onStderr ? { onStderr } : {}) });
+  if ("error" in doc) {
+    return { env, rows: unreadRows(declaration, `the live graph could not be read: ${doc.error.code}: ${doc.error.message}`) };
+  }
+  const read = new Map(doc.members.map((m) => [m.name, m]));
+  const composed = doc.members.filter((m) => m.status === "composed").map((m) => m.name);
+  const handles = irMemberHandles({ composed, exports: doc.exports, imports: doc.imports });
+  const table = resolveLinks(declaration, handles);
+  const rows: LinkRow[] = [];
+  for (const r of table) {
+    if (r.status === "ambiguous" || r.origin !== "declared" || r.kind !== DEFAULT_LINK_KIND) continue;
+    const row: LinkRow = { ...r, resolves: "live" };
+    if (row.status !== "invalid") {
+      const producer = read.get(row.producer);
+      const kind = kinds.get(declaration.members.find((m) => m.name === row.producer)?.kind ?? "");
+      if (!producer || producer.status !== "composed") {
+        row.status = "unresolved";
+        row.reason =
+          producer?.reason?.message ??
+          (kind ? `${row.producer} is kind ${kind.name}, which chant does not read live` : `${row.producer} was not read live`);
+      } else if (row.status === "missing" && !doc.exports.some((e) => e.member === row.producer)) {
+        row.status = "unresolved";
+        row.reason = `the live read of ${row.producer} returned no outputs: the account may be unreachable, or its lexicon reports none`;
+      } else if (row.status === "missing") {
+        row.reason = row.reason?.replace(/^(\S+) has no output/, "$1 publishes no output") ?? row.reason;
+      }
+    }
+    rows.push(row);
+  }
+  return { env, rows };
+}
+
+/** Every declared output link as unresolved, when the live graph could not be read at all. */
+function unreadRows(declaration: Declaration, reason: string): LinkRow[] {
+  return resolveLinks(declaration, new Map())
+    .filter((r): r is LinkRow => r.status !== "ambiguous" && r.origin === "declared" && r.kind === DEFAULT_LINK_KIND)
+    .map((r) => ({ ...r, resolves: "live", ...(r.status === "invalid" ? {} : { status: "unresolved" as const, reason }) }));
+}
+
+function liveFinding(check: WorkspaceCheck, row: LinkRow, message: string): WorkspaceDiagnostic {
+  return { checkId: check.id, severity: check.severity, message, entity: row.consumer, pointer: `${row.pointer}/output` };
+}
+
+export const LIVE_CHECKS: readonly WorkspaceCheck[] = [
+  {
+    id: "WSP141",
+    name: "link-live-missing",
+    description: "With --live, a member link names an output its producer's estate publishes now, matched exactly. A producer whose declared output isn't deployed yet, or was renamed in the estate, fails this for every consumer.",
+    severity: "warning",
+    configurable: true,
+    check(ctx) {
+      return (ctx.facts?.live?.rows ?? [])
+        .filter((r) => r.status === "missing")
+        .map((r) => liveFinding(this, r, `${describeLink(r)} does not resolve live in ${ctx.facts!.live!.env}: ${r.reason}`));
+    },
+  },
+  {
+    id: "WSP142",
+    name: "link-live-unresolved",
+    description: "With --live, a member link that could not be resolved against a live read is kept, unresolved, and reported: the producer's kind is not read live, its read failed, or the read returned no outputs.",
+    severity: "info",
+    configurable: true,
+    check(ctx) {
+      return (ctx.facts?.live?.rows ?? [])
+        .filter((r) => r.status === "unresolved")
+        .map((r) => liveFinding(this, r, `${describeLink(r)} is kept unresolved in ${ctx.facts!.live!.env}: ${r.reason}`));
+    },
+  },
+];

package/src/workspace/checks.test.ts

@@ -75,7 +75,7 @@ describe("the WSP catalog", () => {
     expect(list.filter((id) => /^WSP(07|08|09|10)\d$/.test(id))).toEqual([
       "WSP071", "WSP072", "WSP073",
       "WSP081", "WSP082", "WSP083",
-      "WSP091", "WSP092", "WSP093", "WSP094", "WSP095", "WSP096", "WSP097",
+      "WSP091", "WSP092", "WSP093", "WSP094", "WSP095", "WSP096", "WSP097", "WSP098",
       "WSP101", "WSP102", "WSP103", "WSP104", "WSP105", "WSP106",
     ]);
   });
@@ -111,7 +111,7 @@ describe("declaration checks (#2535)", () => {
         column: 15,
         ruleId: "WSP003",
         severity: "error",
-        message: "member infra has kind terraform, which no built-in kind or pinned package supplies; known kinds: chant, other, workspace",
+        message: "member infra has kind terraform, which no built-in kind or pinned package supplies; known kinds: chant, design, other, workspace",
         entity: "infra",
       },
     ]);

package/src/workspace/checks.ts

@@ -24,7 +24,7 @@
  * | WSP001 to WSP011 | the declaration and member kinds (this file) |
  * | WSP071, WSP072 | member ledgers |
  * | WSP081 to WSP083 | recorded pipelines |
- * | WSP091 to WSP097 | member links (#2539) |
+ * | WSP091 to WSP098 | member links (#2539, #2558) |
  * | WSP101 to WSP106 | generated files |
  * | WSP111 to WSP114 | records read with `--kind` (#2549) |
  * | WSP115 | the record kinds the declaration names (#2680) |
@@ -34,6 +34,7 @@
  * | WSP123, WSP124 | box isolation: no shared port, state path or cookie, no literal machine path (#2727) |
  * | WSP125 | boxes: a fountain Box declares the callback token fountain gives its sandbox (#2780) |
  * | WSP126, WSP127 | box intent: the decision record a box names exists, and constrains a member or path of this workspace (#2850, #2857) |
+ * | WSP141, WSP142 | member links resolved against a live read, with `--live` (#2549) |
  * | WSP131 to WSP133 | diagram artifacts: source and render exist, a recorded source hash still matches (#2764) |
  */
 
@@ -47,10 +48,11 @@ import { parseJsonText, pointerToken, type TextLocation } from "./jsonc";
 import { loadKindRegistry, probeKind, resolveKind, type KindLoadProblem, type KindRegistry } from "./kinds";
 import { gitTop, workingTree, type WorkspaceTree } from "./tree";
 import { LINK_CHECKS, linkTable } from "./checks/links";
-import type { LinkTableRow } from "./links";
+import type { LinkRow, LinkTableRow } from "./links";
 import { gatherGeneratedFacts, GENERATED_CHECKS, type GeneratedFileFacts } from "./checks/generated";
 import { gatherLedgerFacts, LEDGER_CHECKS, type MemberLedgerFacts } from "./checks/ledgers";
 import { gatherPipelineFacts, PIPELINE_CHECKS, type MemberPipelineFacts } from "./checks/pipelines";
+import { gatherLiveLinkFacts, LIVE_CHECKS, type LiveLinkFacts } from "./checks/live";
 import { RECORD_CHECKS, type RecordFacts } from "./checks/records";
 import { BOX_CHECKS } from "./checks/boxes";
 import { DIAGRAM_CHECKS } from "./checks/diagrams";
@@ -73,6 +75,8 @@ export interface WorkspaceFacts {
   records?: RecordFacts;
   /** The record kinds the declaration names, each loaded, or only looked for under `--at` (#2680). */
   declaredKinds?: readonly DeclaredKind[];
+  /** The declared links resolved against a live read, with `--live` (#2549). */
+  live?: LiveLinkFacts;
   /** The decision record each box's intent names, read from the working tree (#2850). */
   boxIntents?: readonly ResolvedBoxIntent[];
 }
@@ -137,6 +141,8 @@ export interface DeclarationCheckReport {
   suppressed: SuppressedFinding[];
   /** The member links, declared and inferred, as resolved in source (#2539). */
   links: LinkTableRow[];
+  /** With `--live`, the declared links as resolved against a live read of `env` (#2549). */
+  live?: { env: string; links: LinkRow[] };
   /** Whether an error-severity finding is active. */
   ok: boolean;
 }
@@ -319,7 +325,7 @@ export const WORKSPACE_CHECKS: readonly WorkspaceCheck[] = [
   ...LEDGER_CHECKS,
   // Recorded pipelines (#2542).
   ...PIPELINE_CHECKS,
-  // Member links (#2539), WSP091 to WSP097.
+  // Member links (#2539, #2558), WSP091 to WSP098.
   ...LINK_CHECKS,
   // Generated files (#2541).
   ...GENERATED_CHECKS,
@@ -329,6 +335,8 @@ export const WORKSPACE_CHECKS: readonly WorkspaceCheck[] = [
   ...BOX_CHECKS,
   // Diagram artifacts (#2764).
   ...DIAGRAM_CHECKS,
+  // Links resolved against a live read, with --live (#2549), WSP141 and WSP142.
+  ...LIVE_CHECKS,
 ];
 
 const BY_ID = new Map(WORKSPACE_CHECKS.map((c) => [c.id, c]));
@@ -406,6 +414,13 @@ export interface DeclarationCheckOptions {
   tree?: WorkspaceTree;
   /** The records read with `--kind`, in the same tree (#2549). Given with or without `tree`. */
   records?: RecordFacts;
+  /**
+   * Resolve the declared links against a live read of this environment
+   * (`--live --env`, #2549). Each `chant` member runs `chant graph --live`, so
+   * this reaches whatever those reach. Not with `tree`: a live read is of the
+   * account now. `onStderr` gets each member's stderr.
+   */
+  live?: { env: string; onStderr?: (text: string) => void };
 }
 
 /**
@@ -480,6 +495,7 @@ export async function runDeclarationChecks(
     ...(options.records ? { records: options.records } : {}),
     ...(declaredKinds ? { declaredKinds } : {}),
     ...(boxIntents ? { boxIntents } : {}),
+    ...(options.live && !options.tree ? { live: await gatherLiveLinkFacts(root, declaration, registry, options.live.env, options.live.onStderr) } : {}),
   };
   const ctx: WorkspaceCheckContext = { declaration, tree, groups, kinds: registry, kindProblems: problems, facts };
   const findings = runWorkspaceChecks(ctx);
@@ -507,6 +523,7 @@ export async function runDeclarationChecks(
     diagnostics,
     suppressed: suppressed.map((s) => ({ ...toFinding(s), reason: s.reason })).sort(order),
     links: linkTable(ctx),
+    ...(facts.live ? { live: { env: facts.live.env, links: facts.live.rows } } : {}),
     ok: !diagnostics.some((d) => d.severity === "error"),
   };
 }

package/src/workspace/compose-graph.test.ts

@@ -146,3 +146,50 @@ describe("the links section (#2539)", () => {
     ]);
   });
 });
+
+describe("collectors (#2559)", () => {
+  const topology = {
+    pipelines: [{ id: "traces", signal: "traces", receivers: ["otlp"], processors: ["batch"], exporters: ["otlphttp/honeycomb"] }],
+    components: [
+      { id: "otlp", kind: "receiver", type: "otlp", builtin: true, endpoints: ["0.0.0.0:4317"], protocols: ["grpc"], pipelines: ["traces"] },
+      { id: "otlphttp/honeycomb", kind: "exporter", type: "otlphttp", builtin: true, endpoints: ["https://api.honeycomb.io"], protocols: ["http/protobuf"], pipelines: ["traces"] },
+    ],
+    exporters: [{ id: "otlphttp/honeycomb", type: "otlphttp", endpoints: ["https://api.honeycomb.io"], pipelines: ["traces"], signals: ["traces"] }],
+    edges: [],
+    semconv: [],
+  };
+  const withMeta = (meta: Record<string, unknown>): GraphIR => ({ ...structuredClone(db), meta });
+
+  test("lifts a member's meta.collector into a section and keeps the rest of its meta", () => {
+    const inputs = [
+      { member: member("web", "web"), ir: structuredClone(web) },
+      { member: member("ops", "ops"), ir: withMeta({ collector: topology, other: 1 }) },
+    ];
+    const doc = composeWorkspaceGraph({ name: "acme", root: "/w" }, inputs);
+    expect(doc.collectors).toEqual([
+      {
+        member: "ops",
+        pipelines: topology.pipelines,
+        components: topology.components.map(({ builtin: _b, ...c }) => c),
+        exporters: topology.exporters,
+      },
+    ]);
+    expect(doc.members.find((m) => m.name === "ops")!.meta).toEqual({ other: 1 });
+  });
+
+  test("is empty when no member reports a collector, and leaves meta alone", () => {
+    const doc = composeWorkspaceGraph({ name: "acme", root: "/w" }, [
+      { member: member("web", "web"), ir: structuredClone(web) },
+      { member: member("ops", "ops"), ir: withMeta({ _behaviour: { engine: "x" } }) },
+    ]);
+    expect(doc.collectors).toEqual([]);
+    expect(doc.members.find((m) => m.name === "ops")!.meta).toEqual({ _behaviour: { engine: "x" } });
+  });
+
+  test("ignores a meta.collector that is not a topology", () => {
+    for (const bad of ["x", 1, null, {}, { pipelines: "no" }]) {
+      const doc = composeWorkspaceGraph({ name: "acme", root: "/w" }, [{ member: member("ops", "ops"), ir: withMeta({ collector: bad }) }]);
+      expect(doc.collectors, JSON.stringify(bad)).toEqual([]);
+    }
+  });
+});

package/src/workspace/compose-graph.ts

@@ -87,12 +87,75 @@ export interface ComposedMember {
   cached?: boolean;
   /** The member's stamp (#2876): what the cache keys the read on, or null when none could be taken. */
   stamp?: string | null;
+  /**
+   * For a member of kind `workspace` (#2551, ws-071): the nested workspace's
+   * own view, read through its own `chant workspace graph`. Its nodes are in
+   * the outer `nodes` with `outer/inner/id` ids.
+   */
+  nested?: NestedWorkspace;
   /** Whole-read facts the member's IR carried (`meta`, `pipeline`), kept apart from the composed sections. */
   meta?: Record<string, unknown>;
   pipeline?: unknown;
 }
 
-export type ComposedNode = IRNode & { member: string };
+/** A nested workspace as the outer graph shows it (#2551, ./nested-graph.ts). */
+export interface NestedWorkspace {
+  /** The nested declaration's name. */
+  name: string;
+  /** The contract version of the document the nested read printed. */
+  contract: number;
+  /** The nested workspace's members, as its own graph lists them. */
+  members: ComposedMember[];
+  /** The nested workspace's links, with member names as the nested side writes them. */
+  links: (LinkTableRow | RecordLinkRow)[];
+}
+
+/**
+ * A collector pipeline as a member's IR reports it (#2559). Plain data, so
+ * core never imports the lexicon that computes it.
+ */
+export interface CollectorPipeline {
+  /** The id under `service.pipelines`, such as `traces` or `traces/backend`. */
+  id: string;
+  signal: string;
+  receivers: string[];
+  processors: string[];
+  exporters: string[];
+}
+
+/** One collector component with the addresses its config states. */
+export interface CollectorComponent {
+  id: string;
+  kind: string;
+  type: string;
+  endpoints: string[];
+  /** The wire protocols it speaks (`grpc`, `http/protobuf`, `http/json`); empty when unknown (#2558). */
+  protocols: string[];
+  pipelines: string[];
+}
+
+/** An exporter and the signals that reach it: where a member's telemetry goes. */
+export interface CollectorExporter {
+  id: string;
+  type: string;
+  endpoints: string[];
+  pipelines: string[];
+  signals: string[];
+}
+
+/** The topology of one member's collector config, from the lexicon that types it. */
+export interface MemberCollector {
+  member: string;
+  pipelines: CollectorPipeline[];
+  components: CollectorComponent[];
+  exporters: CollectorExporter[];
+}
+
+/** The meta key a lexicon's `graphMeta` hook answers the collector under. */
+export const COLLECTOR_META_KEY = "collector";
+
+/** `nested` names the nested workspace's member a node was read through (#2551); absent for the outer workspace's own nodes. */
+export type ComposedNode = IRNode & { member: string; nested?: string };
 export type ComposedEdge = IREdge & { member: string };
 
 export interface WorkspaceGraph {
@@ -110,6 +173,11 @@ export interface WorkspaceGraph {
    * the records read with `--kind` (#2549). Empty when no declaration is given.
    */
   links: (LinkTableRow | RecordLinkRow)[];
+  /**
+   * The collector pipelines and exporters of each member that declares a
+   * collector, in declaration order (#2559). Empty when none does.
+   */
+  collectors: MemberCollector[];
   /** The records read with `--kind` (#2524 D4, #2549). Empty without it. */
   records: GraphRecord[];
 }
@@ -163,6 +231,46 @@ export interface ComposeInput {
 
 const prefix = (member: string, id: string): string => `${member}/${id}`;
 
+const strings = (v: unknown): string[] => (Array.isArray(v) ? v.filter((x): x is string => typeof x === "string") : []);
+const records = (v: unknown): Record<string, unknown>[] =>
+  Array.isArray(v) ? v.filter((x): x is Record<string, unknown> => typeof x === "object" && x !== null) : [];
+
+/**
+ * A member's collector topology from its IR meta, or null when the meta holds
+ * none or something that isn't one. Read defensively: the topology comes from
+ * a lexicon the member's own toolchain loaded, which may be newer or older
+ * than this chant.
+ */
+function readCollector(member: string, value: unknown): MemberCollector | null {
+  if (typeof value !== "object" || value === null || !Array.isArray((value as { pipelines?: unknown }).pipelines)) return null;
+  const v = value as Record<string, unknown>;
+  return {
+    member,
+    pipelines: records(v.pipelines).map((p) => ({
+      id: String(p.id),
+      signal: String(p.signal),
+      receivers: strings(p.receivers),
+      processors: strings(p.processors),
+      exporters: strings(p.exporters),
+    })),
+    components: records(v.components).map((c) => ({
+      id: String(c.id),
+      kind: String(c.kind),
+      type: String(c.type),
+      endpoints: strings(c.endpoints),
+      protocols: strings(c.protocols),
+      pipelines: strings(c.pipelines),
+    })),
+    exporters: records(v.exporters).map((e) => ({
+      id: String(e.id),
+      type: String(e.type),
+      endpoints: strings(e.endpoints),
+      pipelines: strings(e.pipelines),
+      signals: strings(e.signals),
+    })),
+  };
+}
+
 function prefixRefs(value: unknown, member: string): unknown {
   if (Array.isArray(value)) return value.map((v) => prefixRefs(v, member));
   if (value === null || typeof value !== "object") return value;
@@ -202,6 +310,7 @@ export function composeWorkspaceGraph(
   const shared: Record<"byLexicon" | "byComposite", Record<string, string[]>> = { byLexicon: {}, byComposite: {} };
   const scoped: Record<"byStack" | "byContainer" | "byWave", Record<string, string[]>> = { byStack: {}, byContainer: {}, byWave: {} };
   const derivedAttrs: Record<string, Set<string>> = {};
+  const collectors: MemberCollector[] = [];
 
   for (const { member, ir } of inputs) {
     if (!ir) continue;
@@ -225,7 +334,14 @@ export function composeWorkspaceGraph(
     for (const e of ir.exports ?? []) exports.push({ ...e, ...(e.node ? { node: prefix(m, e.node) } : {}), member: m });
     for (const i of ir.imports ?? []) imports.push({ ...i, node: prefix(m, i.node), member: m });
     for (const [kind, attrs] of Object.entries(ir.derivedAttrs ?? {})) for (const a of attrs) (derivedAttrs[kind] ??= new Set()).add(a);
-    if (ir.meta) member.meta = ir.meta;
+    if (ir.meta) {
+      // The collector topology has a section of its own; the rest of the meta stays on the member.
+      const { [COLLECTOR_META_KEY]: collector, ...rest } = ir.meta;
+      const read = readCollector(m, collector);
+      if (read) collectors.push(read);
+      if (!read) member.meta = ir.meta;
+      else if (Object.keys(rest).length > 0) member.meta = rest;
+    }
     if (ir.pipeline) member.pipeline = ir.pipeline;
   }
 
@@ -247,8 +363,9 @@ export function composeWorkspaceGraph(
     exports,
     imports,
     links: links
-      ? graphLinks(links.declaration, { composed: inputs.filter((i) => i.ir).map((i) => i.member.name), exports, imports }, links.kinds)
+      ? graphLinks(links.declaration, { composed: inputs.filter((i) => i.ir).map((i) => i.member.name), collectors, exports, imports }, links.kinds)
       : [],
+    collectors,
     records: [],
   };
   if (Object.keys(derivedAttrs).length) {

package/src/workspace/conformance/__fixture__/decisions/decision.kind.mjs

@@ -14,8 +14,14 @@ export const recordKind = {
   idField: "id",
   stateField: "state",
   states: ["proposed", "decided", "ratified", "superseded", "withdrawn"],
-  // Sealed once reached (#2555).
+  // Sealed once reached (#2555): records amend and new write the whole-file
+  // seal into closed_digest when a decision enters one, and records checks it
+  // on every read (#2546, ws-063).
   closedStates: ["ratified", "superseded"],
+  seal: { field: "closed_digest" },
+  // The current decisions, with the files they pin, are the workspace's spec:
+  // records --current --json lists them under spec (#2524 D20, #2546).
+  spec: true,
   supersedes: { field: "supersedes", key: "decision" },
   // A remediates link names a closed decision this one fixes the consequence
   // of, without replacing it: the target's state never changes (#2774).

package/src/workspace/conformance/__fixture__/decisions/decision.schema.json

@@ -227,6 +227,11 @@
         "signature": { "description": "The armored ssh signature, as ssh-keygen -Y sign prints it.", "type": "string", "pattern": "^-----BEGIN SSH SIGNATURE-----\\n" }
       }
     },
+    "closed_digest": {
+      "description": "The decision's whole-file seal (#2546, ws-063): sha256: and the lowercase hex SHA-256 of the JCS form of {body, core}, where core is this front matter without closed_digest and body is the text below it, line endings LF. chant workspace records amend and new write it when the decision enters a closed state (ratified or superseded), and records reports record-seal-mismatch if the file changes afterwards. It covers the reviews, the author seal and the state, which the review digest leaves out, and the digest leaves this field out.",
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
     "constrains": {
       "description": "What this decision governs: issues (owner/repo#n), other decisions (their ids), workspace members (member:<name>) or files and directories in the workspace (path:<path>, the grammar of an evidence path, #2549). At least one entry: a decision that governs nothing is refused.",
       "type": "array",

package/src/workspace/declaration.schema.json

@@ -101,6 +101,36 @@
           }
         }
       }
+    },
+    "writeScope": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Who may write what (#2524 D5, #2548, ws-067): for each principal class, the members whose files it may write and the record kinds it may write, with which verbs. A class with no entry is not restricted. An agent is always bound to its session's member (agents); its entry can only narrow the record kinds and verbs. chant workspace records new, amend, review and close and the MCP record tools refuse a write outside the writer's scope with write-scope-member or write-scope-kind, and chant workspace check --changes reports each commit that writes outside its author's scope, read from the declaration and the trust policy at the range's base. Added in schema 1 by chant 0.101.0, so a declaration that uses it sets minReader to 0.101.0 or newer.",
+      "properties": {
+        "human": {
+          "$ref": "#/$defs/classScope",
+          "description": "Principals holding none of the agent, runner and service roles in the trust policy at base."
+        },
+        "agent": {
+          "$ref": "#/$defs/agentScope",
+          "description": "An agent session (agents), or a principal holding the agent role in the trust policy at base."
+        },
+        "runner": {
+          "$ref": "#/$defs/classScope",
+          "description": "Principals holding the runner role in the trust policy at base, such as a CI job's signing identity."
+        },
+        "service": {
+          "$ref": "#/$defs/classScope",
+          "description": "Principals holding the service role in the trust policy at base."
+        }
+      }
+    },
+    "agents": {
+      "type": "array",
+      "description": "The agent sessions the workspace declares (#2524 D20, #2548, ws-067). Each is bound to one member: it writes that member's files and the records of kinds that member or the workspace declares, as writeScope.agent allows. A session resumes from chant workspace agent <name> --json, which prints its member, its scope and the spec, read from the repository alone. A write names its session with the CHANT_AGENT environment variable, or a commit with a Chant-Agent trailer. Added in schema 1 by chant 0.101.0, so a declaration that uses it sets minReader to 0.101.0 or newer.",
+      "items": {
+        "$ref": "#/$defs/agent"
+      }
     }
   },
   "patternProperties": {
@@ -173,7 +203,7 @@
     },
     "link": {
       "type": "object",
-      "description": "A member link: this member reads output of member (#2539).",
+      "description": "A member link: this member reads output of member (#2539), or sends its telemetry to a pipeline of its collector (#2558).",
       "required": [
         "member",
         "output"
@@ -185,11 +215,19 @@
         },
         "output": {
           "$ref": "#/$defs/outputName",
-          "description": "The producer's output, matched exactly. It must be one the producer's kind exposes."
+          "description": "The producer's output, matched exactly. It must be one the producer's kind exposes. For a telemetry link, the id of a pipeline or an exporter in the producer's collector."
         },
         "kind": {
           "$ref": "#/$defs/kindName",
-          "description": "The link kind. output, the default, is the only one so far: the consumer reads the named output."
+          "description": "The link kind. output, the default: the consumer reads the named output. telemetry (#2558): the consumer sends its telemetry to the named pipeline or exporter of the producer's collector, and chant workspace graph checks that it exists and, when protocol is given, that it speaks it. A declaration that uses telemetry sets minReader to 0.101.0 or newer."
+        },
+        "protocol": {
+          "enum": [
+            "grpc",
+            "http/protobuf",
+            "http/json"
+          ],
+          "description": "For a telemetry link, the OTLP protocol the consumer sends, as OTEL_EXPORTER_OTLP_PROTOCOL names it. Refused on any other kind. Added in schema 1 by chant 0.101.0."
         }
       },
       "patternProperties": {
@@ -320,6 +358,10 @@
           "minLength": 1,
           "description": "Where an embedded member's files come from. Versions live in the lock."
         },
+        "travel": {
+          "type": "boolean",
+          "description": "Whether the member goes with an export (#2524 D10, #2552). chant workspace export writes only members that set travel to true into the export member, and refuses to name one that does not. Added in schema 1 by chant 0.101.0, so a declaration that uses it sets minReader to 0.101.0 or newer."
+        },
         "because": {
           "type": "string",
           "minLength": 1,
@@ -858,6 +900,99 @@
       "type": "string",
       "description": "A glob over file paths, relative to the workspace root: * and ? within one segment, ** across segments, [...] classes and {a,b} alternatives. No leading /, no . or .. segments.",
       "pattern": "^(?!\\.\\.?(/|$))[^/\\\\]+(/(?!\\.\\.?(/|$))[^/\\\\]+)*$"
+    },
+    "recordScope": {
+      "type": "object",
+      "description": "Record kind names, as the kind file's recordKind.name or the name the declaration gives it, each with the verbs the class may write it with: new, amend, review and close (a review session). A kind left out may not be written at all. A record file a commit deletes is never in scope.",
+      "propertyNames": {
+        "$ref": "#/$defs/kindName"
+      },
+      "additionalProperties": {
+        "type": "array",
+        "uniqueItems": true,
+        "items": {
+          "enum": [
+            "new",
+            "amend",
+            "review",
+            "close"
+          ]
+        }
+      }
+    },
+    "classScope": {
+      "type": "object",
+      "description": "A principal class's write scope.",
+      "properties": {
+        "members": {
+          "description": "The members whose files the class may write, by name, or * for every path. Without it, every path. A path in no member is in scope only under *.",
+          "oneOf": [
+            {
+              "const": "*"
+            },
+            {
+              "type": "array",
+              "uniqueItems": true,
+              "items": {
+                "$ref": "#/$defs/name"
+              }
+            }
+          ]
+        },
+        "records": {
+          "$ref": "#/$defs/recordScope",
+          "description": "The record kinds the class may write, and how. Without it, every kind in reach, with every verb. A kind a member declares is in reach when that member is; the workspace's own kinds always are."
+        }
+      },
+      "patternProperties": {
+        "^x-": true
+      },
+      "additionalProperties": false
+    },
+    "agentScope": {
+      "type": "object",
+      "description": "The agent class's write scope. Its members are always its session's one member, so only the record kinds can be set.",
+      "properties": {
+        "records": {
+          "$ref": "#/$defs/recordScope",
+          "description": "The record kinds an agent may write, and how. Without it, every kind in reach of its member, with every verb."
+        }
+      },
+      "patternProperties": {
+        "^x-": true
+      },
+      "additionalProperties": false
+    },
+    "agent": {
+      "type": "object",
+      "description": "An agent session (#2548).",
+      "required": [
+        "name",
+        "member"
+      ],
+      "properties": {
+        "name": {
+          "$ref": "#/$defs/name",
+          "description": "The session's name, unique among agents: what CHANT_AGENT and a Chant-Agent trailer give."
+        },
+        "member": {
+          "$ref": "#/$defs/name",
+          "description": "The one member the session is bound to. It must be a declared member, not an example group."
+        },
+        "principals": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": "Principals that write only as this session: a commit attested by one, or a write whose by names one, is judged as the session. A principal is listed by one session at most."
+        }
+      },
+      "patternProperties": {
+        "^x-": true
+      },
+      "additionalProperties": false
     }
   }
 }