@intentius/chant 0.100.0 → 0.101.0

package/src/workspace/graph.schema.json

@@ -29,6 +29,7 @@
         "exports",
         "imports",
         "links",
+        "collectors",
         "records"
       ],
       "properties": {
@@ -223,6 +224,13 @@
             "$ref": "#/$defs/link"
           }
         },
+        "collectors": {
+          "type": "array",
+          "description": "The collector pipelines and exporters of each member that declares a collector, in declaration order (#2559). A member reports them from its own IR (`meta.collector`), which the lexicon that types the collector config writes, so chant itself reads no collector config. Empty when no member declares one. A reader joins a telemetry endpoint to the pipeline or exporter it names through `exporters[].endpoints` and `pipelines[].id`.",
+          "items": {
+            "$ref": "#/$defs/collector"
+          }
+        },
         "records": {
           "type": "array",
           "description": "The records read with --kind (#2524 D4, #2549), sorted by path; empty without it. A record link in `links` names its record by id.",
@@ -330,6 +338,40 @@
         },
         "pipeline": {
           "description": "The member IR's pipeline projection, when it has one."
+        },
+        "nested": {
+          "type": "object",
+          "description": "For a member of kind workspace (#2551): the nested workspace, read read-only through its own chant workspace graph. Its nodes, edges, exports and imports are in the outer sections with `<member>/<nested member>/<id>` ids, and each node names its nested member in `nested`. The outer workspace never writes inside it.",
+          "required": [
+            "name",
+            "contract",
+            "members",
+            "links"
+          ],
+          "properties": {
+            "name": {
+              "type": "string",
+              "description": "The nested declaration's name."
+            },
+            "contract": {
+              "type": "integer",
+              "description": "The contract version of the nested read's document."
+            },
+            "members": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/member"
+              },
+              "description": "The nested workspace's members as its own graph lists them, with their own names and directories (relative to the nested root)."
+            },
+            "links": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/link"
+              },
+              "description": "The nested workspace's links, naming its members as the nested side does."
+            }
+          }
         }
       },
       "if": {
@@ -396,6 +438,10 @@
         "runtimeOwner": {
           "type": "string"
         },
+        "nested": {
+          "type": "string",
+          "description": "For a node read through a nested workspace (#2551): the nested workspace's member it belongs to. `member` is then the outer member, and the id is `<member>/<nested>/<id>`."
+        },
         "sourceLoc": {
           "type": "object",
           "required": [
@@ -544,7 +590,7 @@
             },
             "kind": {
               "type": "string",
-              "description": "What the link joins, such as output."
+              "description": "What the link joins: `output`, or `telemetry` (#2558), where the consumer sends its telemetry to a pipeline or exporter of the producer's collector and `output` names it."
             },
             "origin": {
               "enum": [
@@ -599,6 +645,21 @@
             "pointer": {
               "type": "string",
               "description": "The declared link's JSON Pointer in the declaration; left out of the graph for a declared link."
+            },
+            "protocol": {
+              "enum": [
+                "grpc",
+                "http/protobuf",
+                "http/json"
+              ],
+              "description": "A telemetry link: the OTLP protocol it states."
+            },
+            "target": {
+              "enum": [
+                "pipeline",
+                "exporter"
+              ],
+              "description": "A telemetry link that found its target: whether `output` named a pipeline or an exporter in the producer's `collectors` entry."
             }
           }
         },
@@ -764,6 +825,150 @@
         }
       ]
     },
+    "collector": {
+      "type": "object",
+      "required": [
+        "member",
+        "pipelines",
+        "components",
+        "exporters"
+      ],
+      "properties": {
+        "member": {
+          "type": "string",
+          "description": "The member whose source declares the collector."
+        },
+        "pipelines": {
+          "type": "array",
+          "description": "Each pipeline under `service.pipelines`.",
+          "items": {
+            "type": "object",
+            "required": [
+              "id",
+              "signal",
+              "receivers",
+              "processors",
+              "exporters"
+            ],
+            "properties": {
+              "id": {
+                "type": "string",
+                "description": "The pipeline id, such as `traces` or `traces/backend`."
+              },
+              "signal": {
+                "type": "string",
+                "description": "`traces`, `metrics` or `logs`."
+              },
+              "receivers": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "processors": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "exporters": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        },
+        "components": {
+          "type": "array",
+          "description": "Every receiver, processor, exporter, connector and extension, with the addresses its config states.",
+          "items": {
+            "type": "object",
+            "required": [
+              "id",
+              "kind",
+              "type",
+              "endpoints",
+              "protocols",
+              "pipelines"
+            ],
+            "properties": {
+              "id": {
+                "type": "string",
+                "description": "The collector id, `type` or `type/name`."
+              },
+              "kind": {
+                "type": "string",
+                "description": "`receiver`, `processor`, `exporter`, `connector` or `extension`."
+              },
+              "type": {
+                "type": "string"
+              },
+              "endpoints": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "protocols": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "The wire protocols the component speaks, as OTLP SDKs name them: `grpc`, `http/protobuf` or `http/json`. Empty when its definition states none, which a telemetry link's protocol check reads as unknown."
+              },
+              "pipelines": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        },
+        "exporters": {
+          "type": "array",
+          "description": "The exporters again, with the signals that reach each: where the member's telemetry is sent.",
+          "items": {
+            "type": "object",
+            "required": [
+              "id",
+              "type",
+              "endpoints",
+              "pipelines",
+              "signals"
+            ],
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "type": {
+                "type": "string"
+              },
+              "endpoints": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "pipelines": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "signals": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "record": {
       "type": "object",
       "required": [

package/src/workspace/import.ts

@@ -0,0 +1,325 @@
+/**
+ * `chant workspace import`: bring an export back into the workspace it came
+ * from (#2552, #2524 D10, requirements X3 and X5, ws-004, ws-073).
+ *
+ * The source is the export member, or a directory holding a copy of an
+ * export, such as the repository a hosted copy was kept in. Its
+ * `.chant/export.json` names the workspace and the members that went, and the
+ * hash each file had on both sides when it went: the merge base.
+ *
+ * For each file, three hashes decide. A file the copy did not change is left
+ * alone. A file the copy changed is written when the workspace did not
+ * change it since the export. A file both changed differently is a conflict,
+ * and any conflict refuses the whole import, which then writes nothing. The
+ * same holds for removed and added files. Only paths inside the members that
+ * went, and the record directories of a whole export, are written: a copy
+ * that holds anything else is refused, so an import never writes into another
+ * member.
+ *
+ * Host values switch back (X3): the host-bound values the export recorded
+ * are put back in the files the lineage lists, and in the lock. Each lineage
+ * scope merges the same way as a file, with the scope's digest as the base.
+ *
+ * Every write is recorded in `.chant/returns/<id>.json` (./returns.ts). When
+ * the copy is a git repository of its own, each written file also carries the
+ * commit that last changed it there, with the original signature, and the
+ * tree objects that tie that commit to the bytes. Records keep their seals,
+ * since their bytes are copied as they are.
+ *
+ * Last, the export member is written again from the workspace as it now
+ * stands (the default), or removed with its declaration entry (`--remove`).
+ */
+
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { readDeclaration, type Declaration } from "./declaration";
+import {
+  EXPORT_MANIFEST,
+  ExportError,
+  exportMember,
+  exportWorkspace,
+  gitTopOf,
+  isLockPath,
+  lineageDigest,
+  listFiles,
+  lockDir,
+  rawDeclaration,
+  readManifestAt,
+  scopedPath,
+  switchHostValues,
+  under,
+  type ExportManifest,
+  type ExportResult,
+} from "./export";
+import { fileHash, LOCK_FILE, parseLock, renderLock, type LineageLock } from "./lineage-lock";
+import { buildOrigin, originSigners, RETURNS_DIR, writeReturn, type ReturnRecord } from "./returns";
+import { workingTree } from "./tree";
+
+export interface ImportOptions {
+  /** The workspace root. */
+  root: string;
+  /** The returned copy's directory. Absent: the export member. */
+  from?: string;
+  /** Remove the export member and its declaration entry, rather than writing it again. */
+  remove?: boolean;
+  dryRun?: boolean;
+}
+
+export interface ImportConflict {
+  path: string;
+  reason: string;
+}
+
+export interface ImportResult {
+  /** The export the copy started from. */
+  export: string;
+  /** The copy's directory, as given or the export member's. */
+  from: string;
+  written: string[];
+  removed: string[];
+  /** Locks changed, by path. */
+  locks: string[];
+  /** Paths whose host-bound values were switched back. */
+  hostValues: string[];
+  conflicts: ImportConflict[];
+  /** Paths in the copy that are outside every member that went. */
+  outside: string[];
+  /** The return record written, relative to the workspace root, or null when nothing changed or for a dry run. */
+  returnRecord: string | null;
+  return: ReturnRecord | null;
+  /** What happened to the export member: written again, removed, or left (nothing changed, a dry run, or a conflict). */
+  member: { name: string; action: "regenerated" | "removed" | "left"; note?: string } | null;
+  applied: boolean;
+}
+
+/** Paths the copy may hold besides member and record files. */
+function ignoredInCopy(path: string): boolean {
+  return path === EXPORT_MANIFEST || path === "chant.workspace.json" || path === "chant.workspace.jsonc" || path.startsWith(`${RETURNS_DIR}/`);
+}
+
+function readOr(abs: string): Buffer | undefined {
+  return existsSync(abs) ? readFileSync(abs) : undefined;
+}
+
+/** Plan the import, and apply it unless `dryRun` or a conflict. Throws an {@link ExportError}. */
+export async function importWorkspace(o: ImportOptions): Promise<ImportResult> {
+  const root = resolve(o.root);
+  const decl = readDeclaration(workingTree(root));
+  const fromDir = o.from !== undefined ? resolve(o.from) : join(root, exportMember(decl).dir);
+  const manifest = readManifestAt(fromDir);
+  if (!manifest) throw new ExportError(`${fromDir} holds no ${EXPORT_MANIFEST}: it is not an export`);
+  if (manifest.from.workspace !== decl.name) {
+    throw new ExportError(`the export came from workspace ${manifest.from.workspace}, and this one is ${decl.name}`);
+  }
+  const memberDirs = manifest.members.map((name) => {
+    const m = decl.members.find((x) => x.name === name);
+    if (!m) throw new ExportError(`member ${name} went with the export, and this workspace no longer declares it`);
+    return m.dir;
+  });
+  const allowed = [...memberDirs, ...manifest.dirs];
+  const others = decl.members.filter((m) => !manifest.members.includes(m.name) && m.dir !== ".");
+
+  // The copy's files and locks.
+  const copyFiles = new Map<string, Buffer>();
+  const copyLocks = new Map<string, LineageLock>();
+  const outside: string[] = [];
+  for (const path of listFiles(fromDir)) {
+    if (ignoredInCopy(path)) continue;
+    if (path === LOCK_FILE) {
+      copyLocks.set(path, parseLock(readFileSync(join(fromDir, path), "utf-8")));
+      continue;
+    }
+    if (!allowed.some((d) => under(path, d)) || others.some((m) => under(path, m.dir))) {
+      outside.push(path);
+      continue;
+    }
+    if (isLockPath(path)) copyLocks.set(path, parseLock(readFileSync(join(fromDir, path), "utf-8")));
+    else copyFiles.set(path, readFileSync(join(fromDir, path)));
+  }
+
+  // Each scope's digest as the copy holds it, before host values go back.
+  const copyDigests = new Map<string, string>();
+  for (const [path, lock] of copyLocks) for (const [scope, lineage] of Object.entries(lock.scopes)) copyDigests.set(`${path}#${scope}`, lineageDigest(lineage));
+
+  // Host values back (X3), in the files and in each lock.
+  const exportForm = new Map(copyFiles);
+  const hostValues = new Set<string>();
+  for (const [path, lock] of copyLocks) {
+    for (const [scope, lineage] of Object.entries(lock.scopes)) {
+      const values = manifest.hostValues[`${path}#${scope}`];
+      if (!values) continue;
+      const back = Object.fromEntries(Object.entries(values).map(([n, v]) => [n, { from: v.export, to: v.host }]));
+      for (const p of switchHostValues(lineage, lockDir(path), scope, back, copyFiles)) hostValues.add(p);
+    }
+  }
+
+  const conflicts: ImportConflict[] = [];
+  const writes = new Map<string, Buffer>();
+  const removes: string[] = [];
+  for (const path of [...new Set([...Object.keys(manifest.files), ...copyFiles.keys()])].sort()) {
+    if (!allowed.some((d) => under(path, d))) continue;
+    const base = manifest.files[path];
+    const copy = exportForm.get(path);
+    const changedThere = copy === undefined ? base !== undefined : base === undefined || fileHash(copy) !== base.export;
+    if (!changedThere) continue;
+    const here = readOr(join(root, path));
+    const changedHere = here === undefined ? base !== undefined : base === undefined || fileHash(here) !== base.host;
+    if (copy === undefined) {
+      if (here === undefined) continue;
+      if (changedHere) conflicts.push({ path, reason: "the copy removed it, and it changed here since the export" });
+      else removes.push(path);
+      continue;
+    }
+    const target = copyFiles.get(path)!;
+    if (here !== undefined && here.equals(target)) continue;
+    if (changedHere) {
+      conflicts.push({ path, reason: here === undefined ? "the copy changed it, and it was removed here since the export" : base === undefined ? "the copy added it, and a different file was added here" : "the copy and this workspace both changed it since the export" });
+      continue;
+    }
+    writes.set(path, target);
+  }
+
+  // Locks, scope by scope.
+  const lockWrites = new Map<string, LineageLock>();
+  for (const path of [...new Set([...Object.keys(manifest.locks), ...copyLocks.keys()])].sort()) {
+    const there = copyLocks.get(path);
+    const hereText = readOr(join(root, path));
+    const here: LineageLock | null = hereText ? parseLock(hereText.toString("utf-8")) : null;
+    const next: LineageLock = here ? JSON.parse(JSON.stringify(here)) : { lockVersion: 1, scopes: {} };
+    let changed = false;
+    const recorded = manifest.locks[path] ?? {};
+    for (const scope of [...new Set([...Object.keys(recorded), ...Object.keys(there?.scopes ?? {})])].sort()) {
+      const base = recorded[scope];
+      const theirs = there?.scopes[scope];
+      const ours = here?.scopes[scope];
+      const theirDigest = copyDigests.get(`${path}#${scope}`);
+      const changedThere = theirDigest === undefined ? base !== undefined : base === undefined || theirDigest !== base.export;
+      if (!changedThere) continue;
+      const changedHere = ours === undefined ? base !== undefined : base === undefined || lineageDigest(ours) !== base.host;
+      const where = `${path} scope ${scope}`;
+      if (changedHere) {
+        conflicts.push({ path: where, reason: "the copy and this workspace both changed the lineage since the export" });
+        continue;
+      }
+      if (!theirs) {
+        delete next.scopes[scope];
+        changed = true;
+        continue;
+      }
+      if (base?.partial && ours) {
+        // Only part of the scope went: take the copy's files, and nothing that would move the rest.
+        const { files: _f, manualSteps: _m, repinned: _r, ...a } = ours;
+        const { files: _f2, manualSteps: _m2, repinned: _r2, ...b } = theirs;
+        if (JSON.stringify(a) !== JSON.stringify(b)) {
+          conflicts.push({ path: where, reason: "the copy upgraded a scope only part of which went with the export; upgrade it here instead" });
+          continue;
+        }
+        const dir = lockDir(path);
+        const went = (f: string) => manifest.files[scopedPath(dir, scope, f)] !== undefined || theirs.files[f] !== undefined;
+        const files = Object.fromEntries(Object.entries(ours.files).filter(([f]) => !went(f)));
+        next.scopes[scope] = {
+          ...ours,
+          files: { ...files, ...theirs.files },
+          manualSteps: [...ours.manualSteps.filter((s) => !went(s.path)), ...theirs.manualSteps],
+        };
+      } else {
+        next.scopes[scope] = theirs;
+      }
+      changed = true;
+    }
+    if (changed) lockWrites.set(path, next);
+  }
+
+  const result: ImportResult = {
+    export: manifest.id,
+    from: fromDir,
+    written: [...writes.keys()],
+    removed: removes,
+    locks: [...lockWrites.keys()],
+    hostValues: [...hostValues].filter((p) => writes.has(p)).sort(),
+    conflicts,
+    outside,
+    returnRecord: null,
+    return: null,
+    member: null,
+    applied: false,
+  };
+  if (outside.length > 0 || conflicts.length > 0) return result;
+  const nothing = writes.size === 0 && removes.length === 0 && lockWrites.size === 0;
+
+  // The return record: what came back, and where each file was made.
+  const ownRepo = gitTopOf(fromDir);
+  const own = ownRepo !== undefined && realpathSync(ownRepo) === realpathSync(fromDir);
+  let head: string | null = null;
+  if (own) {
+    try {
+      head = execFileSync("git", ["rev-parse", "HEAD"], { cwd: fromDir, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    } catch {
+      head = null;
+    }
+  }
+  const paths: ReturnRecord["paths"] = {};
+  for (const [path, data] of writes) {
+    const origin = own && head && !hostValues.has(path) ? buildOrigin(fromDir, path, data) : undefined;
+    paths[path] = { sha256: fileHash(data), ...(origin ? { origin } : {}) };
+  }
+  for (const path of lockWrites.keys()) paths[path] = { sha256: fileHash(renderLock(lockWrites.get(path)!)) };
+  const origins = Object.values(paths).flatMap((p) => (p.origin ? [p.origin] : []));
+  const idBody = JSON.stringify({ export: manifest.id, head, paths: Object.fromEntries(Object.entries(paths).map(([p, v]) => [p, v.sha256])), removes });
+  const ret: ReturnRecord = {
+    schema: 1,
+    id: `ret-${createHash("sha256").update(idBody).digest("hex").slice(0, 12)}`,
+    export: { id: manifest.id, workspace: manifest.from.workspace, revision: manifest.from.revision },
+    head,
+    paths,
+    removed: removes,
+    hostValues: result.hostValues,
+    signers: originSigners(origins),
+  };
+  if (!nothing) result.return = ret;
+  if (o.dryRun) return result;
+
+  // Apply.
+  for (const [path, data] of writes) {
+    const abs = join(root, path);
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, data);
+  }
+  for (const path of removes) rmSync(join(root, path), { force: true });
+  for (const [path, lock] of lockWrites) {
+    const abs = join(root, path);
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, renderLock(lock));
+  }
+  if (!nothing) result.returnRecord = writeReturn(root, ret);
+  result.applied = true;
+
+  // The export member: written again from the workspace as it stands, or removed.
+  result.member = await settleExportMember(root, decl, manifest, o.remove === true, fromDir);
+  return result;
+}
+
+async function settleExportMember(root: string, decl: Declaration, manifest: ExportManifest, remove: boolean, fromDir: string): Promise<ImportResult["member"]> {
+  const m = decl.members.find((x) => x.name === manifest.member);
+  if (!m) return null;
+  if (!remove) {
+    const again: ExportResult = await exportWorkspace({
+      root,
+      to: m.name,
+      ...(manifest.whole ? {} : { members: manifest.members }),
+      params: Object.fromEntries(Object.values(manifest.hostValues).flatMap((v) => Object.entries(v).map(([n, x]) => [n, x.export]))),
+    });
+    return { name: m.name, action: "regenerated", note: `${again.manifest.id}, ${again.files} file(s)` };
+  }
+  rmSync(join(root, m.dir), { recursive: true, force: true });
+  const { file, obj } = rawDeclaration(root);
+  if (file.endsWith(".jsonc")) {
+    return { name: m.name, action: "removed", note: `removed ${m.dir}; ${file} keeps comments, so drop the entry for ${m.name} by hand` };
+  }
+  obj.members = (obj.members as { name: string }[]).filter((e) => e.name !== m.name);
+  writeFileSync(join(root, file), JSON.stringify(obj, null, 2) + "\n");
+  const inside = resolve(fromDir) === resolve(root, m.dir);
+  return { name: m.name, action: "removed", note: `removed ${m.dir} and its entry in ${file}${inside ? "" : `; the copy at ${relative(root, fromDir) || "."} is left as it is`}` };
+}

package/src/workspace/kinds.test.ts

@@ -61,10 +61,10 @@ function pkg(name: string, version: string, kinds: unknown[] | null, extra: Reco
 }
 
 describe("the built-in kinds (#2535)", () => {
-  test("are chant, workspace and other, and the group kind examples", () => {
-    expect(BUILTIN_KINDS.map((k) => `${k.name}:${k.shape}`)).toEqual(["chant:member", "workspace:member", "other:member", "examples:group"]);
+  test("are chant, workspace, design and other, and the group kind examples", () => {
+    expect(BUILTIN_KINDS.map((k) => `${k.name}:${k.shape}`)).toEqual(["chant:member", "workspace:member", "other:member", "design:member", "examples:group"]);
     const registry = builtinKindRegistry();
-    expect(registry.names()).toEqual(["chant", "other", "workspace"]);
+    expect(registry.names()).toEqual(["chant", "design", "other", "workspace"]);
     expect(registry.get(EXAMPLES_KIND)?.shape).toBe("group");
   });
 
@@ -203,7 +203,7 @@ describe("loadKindRegistry: kinds from the pins", () => {
     const { registry, problems } = loadKindRegistry([{ package: "@acme/chant-lexicon-tf", version: "1.2.3", path: null }], root);
     expect(problems).toEqual([]);
     expect(registry.get("terraform")).toMatchObject({ source: "@acme/chant-lexicon-tf", precedence: 400 });
-    expect(registry.names()).toEqual(["chant", "other", "terraform", "workspace"]);
+    expect(registry.names()).toEqual(["chant", "design", "other", "terraform", "workspace"]);
     expect(existsSync(join(root, "node_modules/@acme/chant-lexicon-tf/IMPORTED"))).toBe(false);
     expect((globalThis as { __chantKindsImported?: boolean }).__chantKindsImported).toBeUndefined();
   });
@@ -223,7 +223,7 @@ describe("loadKindRegistry: kinds from the pins", () => {
       ],
       root,
     );
-    expect(registry.names()).toEqual(["chant", "other", "workspace"]);
+    expect(registry.names()).toEqual(["chant", "design", "other", "workspace"]);
     expect(problems).toEqual([
       { pin: 1, message: "pinned package absent is not installed; install it to read the kinds it supplies" },
       { pin: 2, message: "tf-kinds is pinned at 1.0.0, and 2.0.0 is installed" },

package/src/workspace/kinds.ts

@@ -3,8 +3,8 @@
  * `examples`).
  *
  * A kind is data: a name, a precedence and a probe that says what its
- * directory holds. Probes run no code (K3). Four kinds are built in: the
- * member kinds `chant`, `workspace` and `other`, and the group kind
+ * directory holds. Probes run no code (K3). Five kinds are built in: the
+ * member kinds `chant`, `workspace`, `design` and `other`, and the group kind
  * `examples`. Every other kind comes from a pinned package, which publishes
  * its kinds as a JSON file at a `./workspace-kinds` subpath, the way a
  * lexicon publishes a slim `./detect` entry (#426). chant finds that file
@@ -23,6 +23,7 @@ import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import schema from "./workspace-kinds.schema.json";
 import type { WorkspaceTree } from "./tree";
 import { joinPath, skippedDir } from "./tree";
+import { checkPinIntegrity } from "./pin-integrity";
 
 export const KINDS_SCHEMA_ID = schema.$id;
 
@@ -111,6 +112,9 @@ export interface KindRegistry {
 /** The group kind (ws-051). An entry of this kind is a group, not a member. */
 export const EXAMPLES_KIND = "examples";
 
+/** The data member kind that holds design artifacts (#2549, ws-062). */
+export const DESIGN_KIND = "design";
+
 export const BUILTIN_KINDS: readonly MemberKind[] = [
   {
     name: "chant",
@@ -123,7 +127,7 @@ export const BUILTIN_KINDS: readonly MemberKind[] = [
   },
   {
     name: "workspace",
-    description: "a nested workspace, with its own chant.workspace.json; opaque to the outer one",
+    description: "a nested workspace, with its own chant.workspace.json; the outer one reads it through its own chant workspace graph and never writes inside it",
     probe: { anyFile: ["chant.workspace.json", "chant.workspace.jsonc"] },
     precedence: 1000,
     shape: "member",
@@ -139,6 +143,15 @@ export const BUILTIN_KINDS: readonly MemberKind[] = [
     outputs: { from: "declared", names: [] },
     source: "builtin",
   },
+  {
+    name: DESIGN_KIND,
+    description: "a data member holding the design artifacts the workspace owns; chant reads its files for record pins and builds nothing",
+    probe: { directory: true },
+    precedence: 0,
+    shape: "member",
+    outputs: { from: "declared", names: [] },
+    source: "builtin",
+  },
   {
     name: EXAMPLES_KIND,
     description: "an example group: every directory its glob matches that holds a chant project is built and linted",
@@ -471,6 +484,8 @@ export interface PinLike {
   package: string | null;
   version: string | null;
   path: string | null;
+  /** A path pin's content hash (#2547). Checked before anything is read from the directory. */
+  integrity?: string | null;
 }
 
 export interface KindLoadProblem {
@@ -521,6 +536,13 @@ export function loadKindRegistry(pins: readonly PinLike[], workspaceRoot: string
     } else if (pin.path) {
       source = pin.path;
       dir = join(workspaceRoot, ...pin.path.split("/"));
+      if (pin.integrity) {
+        const checked = checkPinIntegrity(dir, pin.integrity, pin.path);
+        if (!checked.ok) {
+          problems.push({ pin: i, message: checked.message });
+          return;
+        }
+      }
     } else {
       return;
     }