app/lib/systems.mjs

Functions

Imports

It imports no other module of this repo. Imported by app/lib/nav.ts, app/routes/systems.tsx, app/routes/systems[.md].ts.

Source

1// The family of systems at /systems: Capsid's public model (data/system-model.json, the
2// document Capsid serves at /public/model/v1.json) checked, then drawn by Capsomer's system
3// map. Ruling: capsid/rulings/system-explorer-2026-10-10.md; design:
4// capsid/research/design-system-explorer.md, sections 2 and 3 (slice 4).
5//
6// Every system is drawn whole, a private repo's included (Dustin, 2026-10-23: "do not exclude
7// private repos", "fully wired just like the public ones"); a private system carries no repo
8// link. The file is refused unless every key is one the published shape allows and a private
9// system names no repo, so a mistake upstream stops the build rather than reaching the page.
10import { modelMapData } from "capsomer/behaviour/system-map";
11import { z } from "zod";
12
13export const SYSTEMS_PATH = "/systems";
14
15const Id = z.string().regex(/^[a-z0-9][a-z0-9-]{0,63}$/);
16/** @param {number} max */
17const Text = (max) => z.string().min(1).max(max);
18// The enums are capsid's (src/system-model.ts), so a value it publishes is never refused here.
19const FAMILIES = /** @type {const} */ (["system", "writing", "product", "plumbing", "site"]);
20const RINGS = /** @type {const} */ (["core", "shared", "used"]);
21const RELATIONSHIP_KINDS = /** @type {const} */ (["installs", "publishes-to", "coordinates", "watches", "reads", "writes", "deploys", "serves"]);
22const CONTAINER_KINDS = /** @type {const} */ (["worker", "database", "bucket", "kv", "queue", "cron", "package", "site", "external"]);
23
24const OpenSystem = z.strictObject({
25  id: Id,
26  name: Text(40),
27  short: Text(12),
28  family: z.enum(FAMILIES),
29  ring: z.enum(RINGS),
30  private: z.literal(false),
31  description: Text(280).optional(),
32  domain: Text(253).optional(),
33  repos: z.array(z.url().max(512)).optional(),
34});
35
36// A private system is everything a public one is but its repo link (capsid src/system-model.ts).
37const PrivateSystem = OpenSystem.omit({ repos: true }).extend({ private: z.literal(true) });
38
39const PublicModel = z.strictObject({
40  version: z.literal(1),
41  as_of: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
42  systems: z.array(z.union([PrivateSystem, OpenSystem])),
43  containers: z.array(
44    z.strictObject({
45      id: Id,
46      system: Id,
47      name: Text(40),
48      kind: z.enum(CONTAINER_KINDS),
49      technology: Text(60),
50      description: Text(280).optional(),
51    })
52  ),
53  relationships: z.array(
54    z.strictObject({
55      id: Text(200),
56      from: Id,
57      to: Id,
58      kind: z.enum(RELATIONSHIP_KINDS),
59      title: Text(280).optional(),
60    })
61  ),
62  // Capsid's flows (design section 4): walks the explorer animates. Optional, as Capsid's own
63  // schema has it, so a model written before flows existed still parses. Not drawn here.
64  flows: z
65    .array(
66      z.strictObject({
67        id: Id,
68        name: Text(60),
69        description: Text(280).optional(),
70        steps: z
71          .array(
72            z.strictObject({
73              relationship: Text(200),
74              toward: Id,
75              text: Text(280),
76              lights: z.array(Id).max(8).optional(),
77            })
78          )
79          .min(2)
80          .max(20),
81      })
82    )
83    .optional(),
84  counts: z.strictObject({
85    systems: z.number().int(),
86    public: z.number().int(),
87    private: z.number().int(),
88    containers: z.number().int(),
89    relationships: z.number().int(),
90  }),
91});
92
93/** @typedef {z.infer<typeof PublicModel>} SystemModel */
94/** @typedef {SystemModel["systems"][number]} ModelSystem */
95
96/**
97 * The model, or the reasons it is refused. Beyond the shape: ids are unique, every
98 * relationship and container names something that exists, and every flow rides lines the
99 * model has.
100 * @param {unknown} raw
101 * @returns {{ ok: true, model: SystemModel } | { ok: false, problems: string[] }}
102 */
103export function parseSystemModel(raw) {
104  const parsed = PublicModel.safeParse(raw);
105  if (!parsed.success) return { ok: false, problems: parsed.error.issues.map((i) => `${i.path.join(".") || "(model)"}: ${i.message}`) };
106  const model = parsed.data;
107  const problems = [];
108  const systems = new Map(model.systems.map((s) => [s.id, s]));
109  const containers = new Map(model.containers.map((c) => [c.id, c]));
110  if (systems.size !== model.systems.length) problems.push("systems: an id is used twice");
111  if (containers.size !== model.containers.length) problems.push("containers: an id is used twice");
112  for (const c of model.containers) {
113    if (!systems.has(c.system)) problems.push(`containers.${c.id}: no system ${c.system}`);
114  }
115  for (const r of model.relationships) {
116    for (const end of [r.from, r.to]) {
117      if (!systems.has(end) && !containers.has(end)) problems.push(`relationships.${r.id}: no element ${end}`);
118    }
119  }
120  const edges = new Map(model.relationships.map((r) => [r.id, r]));
121  const flowIds = new Set();
122  for (const f of model.flows ?? []) {
123    if (flowIds.has(f.id)) problems.push(`flows.${f.id}: the id is used twice`);
124    flowIds.add(f.id);
125    f.steps.forEach((step, i) => {
126      const where = `flows.${f.id}.steps.${i + 1}`;
127      const edge = edges.get(step.relationship);
128      if (!edge) {
129        problems.push(`${where}: rides ${step.relationship}, which is not a relationship in the model`);
130        return;
131      }
132      if (step.toward !== edge.from && step.toward !== edge.to) problems.push(`${where}: goes toward ${step.toward}, which is not an end of ${edge.id}`);
133      // A light is a part the step touches, in a system one of its ends belongs to (Capsid's rule).
134      const within = new Set([edge.from, edge.to].map((end) => containers.get(end)?.system ?? end));
135      for (const l of step.lights ?? []) {
136        const part = containers.get(l);
137        if (!part) problems.push(`${where}: lights ${l}, which is not a container`);
138        else if (!within.has(part.system)) problems.push(`${where}: lights ${l}, a part of ${part.system}, which the step does not run in`);
139      }
140    });
141  }
142  const counts = model.counts;
143  const privates = model.systems.filter((s) => s.private).length;
144  if (
145    counts.systems !== model.systems.length ||
146    counts.private !== privates ||
147    counts.public !== model.systems.length - privates ||
148    counts.containers !== model.containers.length ||
149    counts.relationships !== model.relationships.length
150  ) {
151    problems.push("counts: do not match the systems");
152  }
153  return problems.length ? { ok: false, problems } : { ok: true, model };
154}
155
156/**
157 * The checked model, or a thrown error naming every problem: a bad file stops the build.
158 * @param {unknown} raw
159 */
160export function loadSystemModel(raw) {
161  const result = parseSystemModel(raw);
162  if (!result.ok) throw new Error(`data/system-model.json is refused:\n  ${result.problems.join("\n  ")}`);
163  return result.model;
164}
165
166/**
167 * The query parameter that names the chosen system on /systems. There is one page: a system is a
168 * state of it, kept in the address so a shared link opens with that system chosen.
169 */
170export const SYSTEM_PARAM = "system";
171
172/** The address of /systems with one system chosen. @param {string} id */
173export const systemHref = (id) => `${SYSTEMS_PATH}?${SYSTEM_PARAM}=${encodeURIComponent(id)}`;
174
175/**
176 * The system a query value names, or null when it names none: an unknown value is the page with
177 * nothing chosen, never an error.
178 * @param {SystemModel} model
179 * @param {string | null | undefined} value
180 */
181export const chosenSystem = (model, value) => (value && model.systems.some((s) => s.id === value) ? value : null);
182
183/**
184 * The Capsid explorer, built from the same public model, so every system here has a page
185 * there under the same id, private ones included (design section 4, "Deep links both ways").
186 */
187export const EXPLORER_ORIGIN = "https://capsid.dustinedwards.info";
188/** @param {string} id */
189export const explorerUrl = (id) => `${EXPLORER_ORIGIN}/s/${id}/`;
190/** How a page shows that address, as it shows the others: host and path. @param {string} id */
191export const explorerLabel = (id) => `${new URL(EXPLORER_ORIGIN).host}/s/${id}`;
192
193/**
194 * What Capsomer's map draws, the same as the explorer's (Capsomer's modelMapData): every system with no link of its
195 * own, since choosing one shows its facts on the same page (app/enhance/system-map.ts), every line and the parts.
196 * @param {SystemModel} model
197 */
198export const mapData = (model) => modelMapData(model);
199
200// How a line reads from each end.
201/** @type {Record<SystemModel["relationships"][number]["kind"], [string, string]>} */
202const VERB = {
203  installs: ["installs", "is installed by"],
204  "publishes-to": ["publishes to", "is published to by"],
205  coordinates: ["coordinates", "is coordinated by"],
206  watches: ["watches", "is watched by"],
207  reads: ["reads", "is read by"],
208  writes: ["writes to", "is written to by"],
209  deploys: ["deploys", "is deployed by"],
210  serves: ["serves", "is served by"],
211};
212
213/**
214 * One system's connections to other systems, in the model's order: the verb as read from this
215 * end, and the system at the other.
216 * @param {SystemModel} model
217 * @param {string} id
218 * @returns {Array<{ verb: string, other: string, name: string }>}
219 */
220export function connectionsOf(model, id) {
221  const byId = new Map(model.systems.map((s) => [s.id, s]));
222  return model.relationships
223    .filter((r) => (r.from === id || r.to === id) && byId.has(r.from) && byId.has(r.to) && r.from !== r.to)
224    .map((r) => {
225      const out = r.from === id;
226      const other = /** @type {ModelSystem} */ (byId.get(out ? r.to : r.from));
227      const verb = VERB[r.kind][out ? 0 : 1];
228      return { verb: `${verb.charAt(0).toUpperCase()}${verb.slice(1)}`, other: other.id, name: other.name };
229    });
230}
231
232/** @type {Record<ModelSystem["ring"], string>} */
233const RING_HEADINGS = { core: "Runs everything", shared: "Shared parts", used: "What people use" };
234
235/**
236 * A system's parts, in the model's order.
237 * @param {SystemModel} model
238 * @param {string} id
239 */
240export const partsOf = (model, id) => model.containers.filter((c) => c.system === id && c.kind !== "external");
241/**
242 * What a system works with outside its boundary: its `external` containers, such as Capsid's
243 * Agents and GitHub (Dustin, 2026-10-11), never counted among its own parts.
244 * @param {SystemModel} model
245 * @param {string} id
246 */
247export const outsideOf = (model, id) => model.containers.filter((c) => c.system === id && c.kind === "external");
248
249/**
250 * The lines touching a system's parts, to each other or to what is outside it, as sentences
251 * ("MCP Worker writes to capsid"), in the model's order.
252 * @param {SystemModel} model
253 * @param {string} id
254 */
255export function wiresOf(model, id) {
256  // A line to what is outside the system counts too (the Worker serves the Agents); a line
257  // between two outside things does not, since it touches none of the system's parts.
258  const own = new Set(partsOf(model, id).map((c) => c.id));
259  const parts = new Map(model.containers.filter((c) => c.system === id).map((c) => [c.id, c]));
260  return model.relationships
261    .filter((r) => parts.has(r.from) && parts.has(r.to) && (own.has(r.from) || own.has(r.to)))
262    .map((r) => `${parts.get(r.from)?.name} ${VERB[r.kind][0]} ${parts.get(r.to)?.name}`);
263}
264
265/**
266 * One container as the twin and the page write it: name, what it runs on, what it does.
267 * @param {SystemModel["containers"][number]} c
268 */
269const containerLine = (c) => `${c.name} (${c.technology})${c.description ? `: ${c.description}` : ""}`;
270
271/**
272 * What a system's page says about it: its sentence, and that its repo is private when it is.
273 * @param {{ description?: string, private?: boolean }} s a system in the model or on the map
274 */
275export const summaryOf = (s) => [s.description, s.private ? "Its repo is private." : undefined].filter(Boolean).join(" ");
276
277/**
278 * The repo link a public system shows: its first repo, unless it has none.
279 * @param {ModelSystem} s
280 */
281export const repoOf = (s) => (s.private ? undefined : s.repos?.[0]);
282
283/**
284 * The markdown twin of /systems: every system, grouped by ring, each with the facts the page shows
285 * when it is chosen, so an agent reads what a person does.
286 * @param {SystemModel} model
287 * @param {string} origin
288 */
289export function systemsMarkdown(model, origin) {
290  const lines = [
291    "# Systems",
292    "",
293    `The systems Dustin Edwards runs. Public model of ${model.as_of}.`,
294    "",
295  ];
296  for (const ring of RINGS) {
297    const inRing = model.systems.filter((s) => s.ring === ring);
298    if (inRing.length === 0) continue;
299    lines.push(`## ${RING_HEADINGS[ring]}`, "");
300    for (const s of inRing) lines.push(systemSectionMarkdown(model, s.id, origin) ?? "");
301  }
302  lines.push(`Capsid explorer: ${EXPLORER_ORIGIN}/`, "");
303  return lines.join("\n");
304}
305
306/**
307 * One system's section of /systems.md: what the page shows when that system is chosen.
308 * @param {SystemModel} model
309 * @param {string} id
310 * @param {string} origin
311 */
312export function systemSectionMarkdown(model, id, origin) {
313  const s = model.systems.find((x) => x.id === id);
314  if (!s) return null;
315  const lines = [`### ${s.name}${s.private ? " (private)" : ""}`, ""];
316  lines.push(summaryOf(s), "");
317  lines.push(`- On the map: ${origin}${systemHref(s.id)}`);
318  if (s.domain) lines.push(`- Address: https://${s.domain}`);
319  const repo = repoOf(s);
320  if (repo) lines.push(`- Source: ${repo}`);
321  lines.push(`- In the Capsid explorer: ${explorerUrl(s.id)}`);
322  const parts = partsOf(model, id);
323  const outside = outsideOf(model, id);
324  if (parts.length) lines.push("", "#### Inside", "", ...parts.map((c) => `- ${containerLine(c)}`));
325  if (outside.length) lines.push("", "#### Outside it", "", ...outside.map((c) => `- ${containerLine(c)}`));
326  const wires = wiresOf(model, id);
327  if (wires.length) lines.push("", "How they connect:", "", ...wires.map((w) => `- ${w}`));
328  const links = connectionsOf(model, id);
329  lines.push("", "#### Connections", "");
330  if (links.length === 0) lines.push("No connections.");
331  for (const c of links) lines.push(`- ${c.verb} [${c.name}](${origin}${systemHref(c.other)})`);
332  lines.push("");
333  return lines.join("\n");
334}
335
336/**
337 * Whether two models say the same thing. The date is left out: Capsid stamps its build every
338 * day, and a pull request a day that changes only the date would teach a reviewer to skip them.
339 * @param {SystemModel} a
340 * @param {SystemModel} b
341 */
342export function sameModel(a, b) {
343  const { as_of: _a, ...restA } = a;
344  const { as_of: _b, ...restB } = b;
345  return JSON.stringify(restA) === JSON.stringify(restB);
346}