src/system-model.ts

Functions

Imports

It imports src/limits.ts. Imported by src/model-drift.ts, src/public-code.ts, src/public-data.ts.

Source

1import { z } from "zod";
2import { bounded } from "./limits";
3
4// The system model (capsid/rulings/system-explorer-2026-10-10.md, answers 1 and 2;
5// design capsid/research/design-system-explorer.md, sections 1 and 2). One
6// machine-readable model of Dustin's systems, hand-written in system/model.json and
7// changed by pull request. Every map and diagram is drawn from what toPublic makes of
8// it, never from the file itself.
9//
10// Every system is drawn whole, its parts and lines included, whether its repo is public
11// or private (Dustin, 2026-10-23: "do not exclude private repos", "fully wired just like
12// the public ones"). A private repo shows no link and no code map; nothing else differs.
13// The file is in a public repo, so it holds only what may be published: what a system is
14// for and what it is made of, never a secret, an id or an internal address.
15
16const ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
17const REPO = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
18const DOMAIN = /^(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}$/;
19
20const Id = bounded(64).regex(ID, "an id is lowercase kebab-case");
21const Text = bounded(280).trim().min(1);
22
23// Family follows the shared-homes naming (capsid/rulings/shared-homes-2026-10-06.md);
24// ring is where the map draws a system: core in the middle, shared parts around it,
25// what people use on the outside.
26const FAMILIES = ["system", "writing", "product", "plumbing", "site"] as const;
27const RINGS = ["core", "shared", "used"] as const;
28const CONTAINER_KINDS = ["worker", "database", "bucket", "kv", "queue", "cron", "package", "site", "external"] as const;
29const RELATIONSHIP_KINDS = ["installs", "publishes-to", "coordinates", "watches", "reads", "writes", "deploys", "serves"] as const;
30
31const System = z.strictObject({
32  id: Id,
33  name: bounded(40).trim().min(1),
34  // The phone map draws a capsomer about 90 px across, so its label is short.
35  short: bounded(12).trim().min(1),
36  family: z.enum(FAMILIES),
37  ring: z.enum(RINGS),
38  description: Text.optional(),
39  domain: bounded(253).regex(DOMAIN).optional(),
40  repos: z.array(bounded(200).regex(REPO)).min(1),
41  // Answer 15: a public system shown without a link to its repo.
42  hide_repo_link: z.boolean().optional(),
43  aliases: z.array(Id).optional(),
44});
45
46const Container = z.strictObject({
47  id: Id,
48  system: Id,
49  name: bounded(40).trim().min(1),
50  kind: z.enum(CONTAINER_KINDS),
51  technology: bounded(60).trim().min(1),
52  description: Text.optional(),
53});
54
55const Relationship = z.strictObject({
56  from: Id,
57  to: Id,
58  kind: z.enum(RELATIONSHIP_KINDS),
59  title: Text.optional(),
60});
61
62// A flow (design section 4, animated flows): ordered steps, each riding one relationship
63// already in the model, toward one of its two ends, with the sentence the explorer shows
64// and the containers it lights. A flow never draws a line of its own, so it cannot show
65// a connection the model does not have.
66const FlowStep = z.strictObject({
67  from: Id,
68  kind: z.enum(RELATIONSHIP_KINDS),
69  to: Id,
70  toward: Id,
71  text: Text,
72  lights: z.array(Id).max(8).optional(),
73});
74
75const Flow = z.strictObject({
76  id: Id,
77  name: bounded(60).trim().min(1),
78  description: Text.optional(),
79  steps: z.array(FlowStep).min(2).max(20),
80});
81
82export const SystemModelSchema = z
83  .strictObject({
84    $schema: bounded(512).optional(),
85    version: z.literal(1),
86    systems: z.array(System).min(1),
87    containers: z.array(Container),
88    relationships: z.array(Relationship),
89    flows: z.array(Flow).optional(),
90    // Repos Dustin keeps off the map: the drift check skips them, and nothing publishes them.
91    left_off: z.array(z.strictObject({ repo: bounded(200).regex(REPO), why: bounded(200) })).optional(),
92  })
93  .superRefine((m, ctx) => {
94    const ids = new Map<string, string>();
95    const claim = (id: string, what: string) => {
96      const prior = ids.get(id);
97      if (prior) ctx.addIssue({ code: "custom", message: `id ${id} is used by a ${prior} and a ${what}` });
98      ids.set(id, what);
99    };
100    for (const s of m.systems) {
101      claim(s.id, "system");
102      for (const a of s.aliases ?? []) claim(a, `alias of ${s.id}`);
103    }
104    for (const c of m.containers) claim(c.id, "container");
105    const systems = new Set(m.systems.map((s) => s.id));
106    const endpoints = new Set([...systems, ...m.containers.map((c) => c.id)]);
107    for (const c of m.containers) {
108      if (!systems.has(c.system)) ctx.addIssue({ code: "custom", message: `container ${c.id} names system ${c.system}, which does not exist` });
109    }
110    const seen = new Set<string>();
111    for (const r of m.relationships) {
112      for (const end of [r.from, r.to]) {
113        if (!endpoints.has(end)) ctx.addIssue({ code: "custom", message: `relationship ${r.from} ${r.kind} ${r.to} names ${end}, which does not exist` });
114      }
115      const key = `${r.from} ${r.kind} ${r.to}`;
116      if (seen.has(key)) ctx.addIssue({ code: "custom", message: `relationship ${key} is listed twice` });
117      seen.add(key);
118    }
119    const containerSystem = new Map(m.containers.map((c) => [c.id, c.system]));
120    const ownerOf = (id: string) => containerSystem.get(id) ?? id;
121    for (const f of m.flows ?? []) {
122      claim(f.id, "flow");
123      f.steps.forEach((step, i) => {
124        const where = `flow ${f.id} step ${i + 1}`;
125        const key = `${step.from} ${step.kind} ${step.to}`;
126        if (!seen.has(key)) ctx.addIssue({ code: "custom", message: `${where} rides ${key}, which is not a relationship in the model` });
127        if (step.toward !== step.from && step.toward !== step.to) ctx.addIssue({ code: "custom", message: `${where} goes toward ${step.toward}, which is not an end of ${key}` });
128        // A light is a part the step's work touches (a store written while the Worker
129        // serves an agent), so it belongs to a system one of the step's ends belongs to.
130        const within = new Set([ownerOf(step.from), ownerOf(step.to)]);
131        for (const l of step.lights ?? []) {
132          const system = containerSystem.get(l);
133          if (system === undefined) ctx.addIssue({ code: "custom", message: `${where} lights ${l}, which is not a container` });
134          else if (!within.has(system)) ctx.addIssue({ code: "custom", message: `${where} lights ${l}, a part of ${system}, which the step does not run in` });
135        }
136      });
137    }
138  });
139
140export type SystemModel = z.infer<typeof SystemModelSchema>;
141type ModelSystem = SystemModel["systems"][number];
142
143/** The model, or every problem with it. */
144export function parseSystemModel(raw: unknown): { ok: true; model: SystemModel } | { ok: false; problems: string[] } {
145  const parsed = SystemModelSchema.safeParse(raw);
146  if (parsed.success) return { ok: true, model: parsed.data };
147  return { ok: false, problems: parsed.error.issues.map((i) => `${i.path.join(".") || "(model)"}: ${i.message}`) };
148}
149
150// The published document. Strict schemas, so a key nobody listed fails the test that
151// parses toPublic's output, and the site builds validate against the same shape.
152const PublicSystemOpen = z.strictObject({
153  id: Id,
154  name: bounded(40),
155  short: bounded(12),
156  family: z.enum(FAMILIES),
157  ring: z.enum(RINGS),
158  private: z.literal(false),
159  description: bounded(280).optional(),
160  domain: bounded(253).optional(),
161  repos: z.array(bounded(512).url()).optional(),
162});
163// A private system is everything a public one is but its repo link.
164const PublicSystemPrivate = PublicSystemOpen.omit({ repos: true }).extend({ private: z.literal(true) });
165
166export const PublicModelSchema = z.strictObject({
167  version: z.literal(1),
168  as_of: bounded(10).regex(/^\d{4}-\d{2}-\d{2}$/),
169  systems: z.array(z.union([PublicSystemOpen, PublicSystemPrivate])),
170  containers: z.array(
171    z.strictObject({
172      id: Id,
173      system: Id,
174      name: bounded(40),
175      kind: z.enum(CONTAINER_KINDS),
176      technology: bounded(60),
177      description: bounded(280).optional(),
178    })
179  ),
180  relationships: z.array(
181    z.strictObject({
182      id: bounded(200),
183      from: Id,
184      to: Id,
185      kind: z.enum(RELATIONSHIP_KINDS),
186      title: bounded(280).optional(),
187    })
188  ),
189  // Optional so a document built before flows existed still parses; toPublic always writes it.
190  flows: z
191    .array(
192      z.strictObject({
193        id: Id,
194        name: bounded(60),
195        description: bounded(280).optional(),
196        steps: z
197          .array(
198            z.strictObject({
199              relationship: bounded(200),
200              toward: Id,
201              text: bounded(280),
202              lights: z.array(Id).max(8).optional(),
203            })
204          )
205          .min(2)
206          .max(20),
207      })
208    )
209    .optional(),
210  counts: z.strictObject({
211    systems: z.number().int(),
212    public: z.number().int(),
213    private: z.number().int(),
214    containers: z.number().int(),
215    relationships: z.number().int(),
216  }),
217});
218
219export type PublicModel = z.infer<typeof PublicModelSchema>;
220
221/** Repo visibility as GitHub reports it, keyed by "owner/name" in lower case: true for
222 *  a private repo, false for a public one. A repo missing from the map is unknown. */
223export type RepoPrivacy = ReadonlyMap<string, boolean>;
224
225/** A relationship's published id, derived from its ends and kind, never copied from text. */
226const relationshipId = (r: { from: string; kind: string; to: string }) => `${r.from}--${r.kind}--${r.to}`;
227
228/** Public only when GitHub says every repo the system lists is public. Any other
229 *  answer, an unknown repo included, is private. */
230function isPublicSystem(s: ModelSystem, privacy: RepoPrivacy): boolean {
231  return s.repos.every((r) => privacy.get(r.toLowerCase()) === false);
232}
233
234/** Every repo of a public system, with its system: the only repos whose code maps may be
235 *  published (design section 2, rule 2). */
236export function publicRepos(model: SystemModel, privacy: RepoPrivacy): Array<{ system: string; repo: string }> {
237  return model.systems.filter((s) => isPublicSystem(s, privacy)).flatMap((s) => s.repos.map((repo) => ({ system: s.id, repo })));
238}
239
240/**
241 * The public document: what the explorer and the dustinedwards.info map read.
242 *
243 * Built by picking named fields into new objects, never by copying an input object and
244 * deleting from it, so a field nobody listed here cannot pass through. Every system,
245 * part, line and flow is published; a system is private unless GitHub says every repo
246 * it lists is public, and a private system carries no repo link. An output id is
247 * derived from its ends, never copied from text.
248 */
249export function toPublic(model: SystemModel, privacy: RepoPrivacy, asOf: string): PublicModel {
250  const open = new Set(model.systems.filter((s) => isPublicSystem(s, privacy)).map((s) => s.id));
251
252  const systems: PublicModel["systems"] = model.systems.map((s) => {
253    const base = { id: s.id, name: s.name, short: s.short, family: s.family, ring: s.ring };
254    const out: PublicModel["systems"][number] = open.has(s.id) ? { ...base, private: false } : { ...base, private: true };
255    if (s.description !== undefined) out.description = s.description;
256    if (s.domain !== undefined) out.domain = s.domain;
257    if (!out.private && !s.hide_repo_link) out.repos = s.repos.map((r) => `https://github.com/${r}`);
258    return out;
259  });
260
261  const containers: PublicModel["containers"] = model.containers.map((c) => {
262    const out: PublicModel["containers"][number] = { id: c.id, system: c.system, name: c.name, kind: c.kind, technology: c.technology };
263    if (c.description !== undefined) out.description = c.description;
264    return out;
265  });
266
267  const relationships: PublicModel["relationships"] = model.relationships.map((r) => {
268    const out: PublicModel["relationships"][number] = { id: relationshipId(r), from: r.from, to: r.to, kind: r.kind };
269    if (r.title !== undefined) out.title = r.title;
270    return out;
271  });
272
273  const flows: NonNullable<PublicModel["flows"]> = (model.flows ?? []).map((f) => {
274    const out: NonNullable<PublicModel["flows"]>[number] = {
275      id: f.id,
276      name: f.name,
277      steps: f.steps.map((step) => {
278        const s: NonNullable<PublicModel["flows"]>[number]["steps"][number] = { relationship: relationshipId(step), toward: step.toward, text: step.text };
279        if (step.lights?.length) s.lights = [...step.lights];
280        return s;
281      }),
282    };
283    if (f.description !== undefined) out.description = f.description;
284    return out;
285  });
286
287  return {
288    version: 1,
289    as_of: asOf,
290    systems,
291    containers,
292    relationships,
293    flows,
294    counts: {
295      systems: systems.length,
296      public: open.size,
297      private: systems.length - open.size,
298      containers: containers.length,
299      relationships: relationships.length,
300    },
301  };
302}