@archcode-io/engine 0.2.0-preview.0

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to the ArchCode engine. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
+[SemVer](https://semver.org/) once 1.0 is out — until then every release may change the API.
+
+## [Unreleased] — 0.2.0-preview
+
+The first public preview. Everything below is new.
+
+### Language (v0.2 draft)
+
+- Objects: `arch system service webapp app component function job datastore cache gateway broker topic actor external`, placement kinds `env segment cluster node managed`; nested blocks give full ids (`orders.worker`).
+- Relations as verbs (`calls publishes subscribes reads writes uses streams depends_on emits listens`) with `over`, `via a, b`, `port`, `spec`, `as`, a label and a body.
+- Interfaces by pointer: `exposes http openapi://…`, `stores schema sql://…`.
+- Attribute lines with lists, pairs (`dc dc1 vlan 3076`), flags (`transit`) and unit tokens (`8Gi`, `24x7`, `2027-01`).
+- Placement: `run a, b` inside a host, sizing (`cpu mem disk gpu count nodes`), `phase` and `at <moment>` timelines.
+- `view` blocks: pins (`at`, `size`), `route … from side to side label f below via x y`, lenses, `layout`, `agents on|off`.
+- Reserved for v0.3, kept byte for byte by the parser: `decision rule board profile contract`, YAML/JSON dialects as input.
+
+### Engine
+
+- Lossless CST with byte-exact round trip; a fuzzer runs random documents through `parse → serialize`.
+- Model lowering with interfaces, placements, timelines and ownership.
+- Semantic diagnostics `AC100–AC109` (unknown reference, ambiguous id, attribute out of scope, …).
+- Compiled form `archcode/v1`: `toCompiled`, `toJSON`, `toYAML`.
+- Lenses (`logical`, `infrastructure`), transit nodes, agents on hosts, phases and moments.
+- Two-phase ELK layout, A* orthogonal router, route repair (`repairRoute`) that keeps a person's arrows when cards move, label placement on either side of the line.
+- ELK host abstraction: bundled in Node, `useElkWorker(url)` in the browser.
+- SVG renderer with dark and light themes; capacity tables.
+- Source edits that touch only the line they mean: `addObject`, `renameObject`, `setAttribute`, `retargetRelation`, `moveInto`, `addRun`, …

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,88 @@
+# ArchCode engine
+
+The reference implementation of [ArchCode](https://archcode.io) — an open notation for
+describing the architecture of digital systems across C4 levels. Compact enough to paste
+into a README, precise enough to validate, diff and generate from code.
+
+```archcode
+service   checkout   "Checkout"      tech Go
+datastore orders_db  "Orders DB"     tech PostgreSQL 16
+
+checkout writes orders_db over SQL
+```
+
+This package turns text like that into a model, a picture, and data — and back into the
+same text, byte for byte.
+
+**Status: v0.2 preview.** The language is a draft; the API below is what the Playground at
+[archcode.io/play](https://archcode.io/play/) runs on and will change before 1.0.
+
+## What is inside
+
+| module | what it does |
+|---|---|
+| `parse` / `serialize` | text ⇄ lossless syntax tree — comments, spacing and order survive a round trip, and the fuzzer checks that on every build |
+| `lower` | syntax tree → model: objects with full ids, relations, interfaces, placements, timelines |
+| `check` | semantic diagnostics `AC100…AC109` — unknown references, ambiguous ids, attributes out of scope |
+| `applyLens` | the model as a graph for one lens (`logical`, `infrastructure`), one phase, one moment |
+| `layout` | positions and orthogonal routes (ELK, two-phase); `repairRoute` keeps a person's arrows when cards move |
+| `toSvg` | the picture, dark or light theme |
+| `toCompiled` / `toJSON` / `toYAML` | the model as plain data (schema `archcode/v1`) |
+| `capacityTable` | resources per environment and moment, from `run … cpu 4 mem 8Gi` |
+| `addObject`, `setAttribute`, `retargetRelation`, … | edits that touch only the line they mean |
+
+## Use
+
+```sh
+npm install        # once
+npm run build      # tsc → dist/
+npm test           # unit tests
+npm run fuzz       # random documents through parse → serialize, must be identical
+```
+
+```ts
+import { parse, lower, check, applyLens, layout, toSvg } from './dist/src/index.js';
+
+const src = `service a "A"\nservice b "B"\na calls b over HTTPS`;
+const { doc, diagnostics } = parse(src);
+const model = lower(doc);
+diagnostics.push(...check(doc, model));
+
+const graph = applyLens(model, { lens: 'logical' });
+const positioned = await layout(graph);
+const svg = toSvg(positioned, '', { theme: 'light' });
+```
+
+The engine has no opinion about where ELK runs. In Node it loads the bundled ELK on first
+use; a browser host calls `useElkWorker('/elk-worker.js')` once and every layout after that
+runs in a Web Worker.
+
+Not on npm yet — the first published version will be `0.2.0-preview.x`.
+
+## Layout of the repository
+
+```
+src/          lexer · parser · cst · model · check · compiled · edit · lens · capacity
+src/layout/   elk (layered) · balance (two-phase) · route (A*) · ortho · label · host
+src/render/   svg
+test/         unit tests, fixtures, fuzz.ts
+tools/        layout scoring and strategy experiments
+```
+
+## The language
+
+The specification lives at [archcode.io/docs](https://archcode.io/docs/). Marks in the
+text say what this engine implements, what is partial, and what is reserved for v0.3.
+
+## Contributing
+
+ArchCode is at an early stage and we are not taking pull requests yet — see
+[CONTRIBUTING](https://github.com/archcode-io/.github/blob/main/CONTRIBUTING.md) for what
+we do welcome, and for the DCO sign-off that every commit carries.
+
+## License
+
+Apache-2.0 — see [LICENSE](LICENSE). The ArchCode language and its specification are a
+separate work under CC BY 4.0.
+
+ArchCode is an open standard created and maintained by Baryshev Labs.

package/dist/src/capacity.d.ts

@@ -0,0 +1,67 @@
+import type { Model, Placement } from './model.js';
+/**
+ * The resources table — the slide every architecture committee asks for
+ * (`Ресурсы серверов … Итого`). It is a projection of the placement blocks,
+ * never a thing written by hand: every `node`, sized `cluster` and sized `run`
+ * contributes its figures times its multiplier, per environment, per moment.
+ */
+export interface Figures {
+    cpu?: number;
+    mem?: number;
+    disk?: number;
+    gpu?: number;
+}
+export declare const FIGURE_KEYS: (keyof Figures)[];
+export interface CapacityRow {
+    id: string;
+    /** For a node/cluster: what runs on it asks for, and whether that exceeds it. */
+    load?: HostLoad;
+    label: string;
+    kind: string;
+    host?: string;
+    /**
+     * Pods inside a sized cluster are demand on capacity the cluster row already
+     * counts, so they are listed but not summed. A run inside an unsized cluster
+     * or a managed service is the only figure there is, and it counts.
+     */
+    counted: boolean;
+    figures: Record<string, Figures & {
+        count: number;
+    }>;
+}
+export interface CapacityEnv {
+    id: string;
+    label: string;
+    rows: CapacityRow[];
+    totals: Record<string, Figures>;
+}
+export interface CapacityTable {
+    moments: string[];
+    envs: CapacityEnv[];
+}
+/** `4Gi` `800Mi` `2Ti` `16GB` `300` → GiB */
+export declare function toGiB(v: string | undefined): number | undefined;
+/** `0.7/2` (requests/limit) → the limit; `2` → 2 */
+export declare function toCpu(v: string | undefined): number | undefined;
+export declare const SIZING_KEYS: string[];
+/**
+ * A placement's sizing, with the logical object's own figures as defaults:
+ * `service api cpu 2` placed with a bare `run api` still runs at 2 cpu, and
+ * `run api cpu 4` overrides it there.
+ */
+export declare function effectiveSizing(m: Model, p: Placement): Record<string, string[]>;
+/**
+ * What the things running on a host ask for, against what the host offers.
+ * cpu/mem of every `run` × replicas, against the host's figures × count.
+ */
+export interface HostLoad {
+    cpu?: [number, number];
+    mem?: [number, number];
+    over: boolean;
+}
+export declare function hostLoad(m: Model, hostId: string): HostLoad | undefined;
+export declare function capacityTable(m: Model, opt?: {
+    phase?: string;
+}): CapacityTable;
+/** `12.5` → `12.5`, `0.78125` → `0.8`, `2048` → `2048` */
+export declare const fmt: (n: number | undefined) => string;

package/dist/src/capacity.js

@@ -0,0 +1,227 @@
+import { PLACEMENT_KINDS } from './vocab.js';
+export const FIGURE_KEYS = ['cpu', 'mem', 'disk', 'gpu'];
+/** `4Gi` `800Mi` `2Ti` `16GB` `300` → GiB */
+export function toGiB(v) {
+    if (!v)
+        return undefined;
+    v = v.split('/').pop(); // `800Mi/2Gi` (requests/limit) → the limit
+    const m = v.match(/^(\d+(?:\.\d+)?)\s*([A-Za-z]*)$/);
+    if (!m)
+        return undefined;
+    const n = parseFloat(m[1]);
+    const u = m[2].toLowerCase();
+    if (u === 'mi' || u === 'mb' || u === 'm')
+        return n / 1024;
+    if (u === 'ti' || u === 'tb' || u === 't')
+        return n * 1024;
+    if (u === 'ki' || u === 'kb' || u === 'k')
+        return n / 1024 / 1024;
+    return n; // Gi, GB, G, bare
+}
+/** `0.7/2` (requests/limit) → the limit; `2` → 2 */
+export function toCpu(v) {
+    if (!v)
+        return undefined;
+    const last = v.split('/').pop();
+    const n = parseFloat(last);
+    return Number.isFinite(n) ? n : undefined;
+}
+const num = (v) => { const n = parseFloat(v ?? ''); return Number.isFinite(n) ? n : undefined; };
+export const SIZING_KEYS = ['replicas', 'count', 'nodes', 'cpu', 'mem', 'disk', 'gpu'];
+/**
+ * A placement's sizing, with the logical object's own figures as defaults:
+ * `service api cpu 2` placed with a bare `run api` still runs at 2 cpu, and
+ * `run api cpu 4` overrides it there.
+ */
+export function effectiveSizing(m, p) {
+    const logical = [...m.objects.values()].find(o => o.id === p.ref || o.localId === p.ref);
+    const out = {};
+    for (const k of SIZING_KEYS)
+        if (logical?.attrs[k])
+            out[k] = logical.attrs[k];
+    return { ...out, ...p.attrs };
+}
+export function hostLoad(m, hostId) {
+    const host = m.objects.get(hostId);
+    if (!host || (host.kind !== 'node' && host.kind !== 'cluster'))
+        return undefined;
+    const cap = figuresOf(host.attrs);
+    const mult = num(host.attrs['count']?.[0]) ?? num(host.attrs['nodes']?.[0]) ?? 1;
+    const runs = m.placements.filter(p => p.host === hostId);
+    if (!runs.length || (cap.cpu === undefined && cap.mem === undefined))
+        return undefined;
+    const demand = {};
+    for (const p of runs) {
+        const a = effectiveSizing(m, p);
+        const f = figuresOf(a);
+        const n = num(a['replicas']?.[0]) ?? 1;
+        if (f.cpu !== undefined)
+            demand.cpu = (demand.cpu ?? 0) + f.cpu * n;
+        if (f.mem !== undefined)
+            demand.mem = (demand.mem ?? 0) + f.mem * n;
+    }
+    const out = { over: false };
+    if (cap.cpu !== undefined && demand.cpu !== undefined) {
+        out.cpu = [demand.cpu, cap.cpu * mult];
+        if (demand.cpu > cap.cpu * mult)
+            out.over = true;
+    }
+    if (cap.mem !== undefined && demand.mem !== undefined) {
+        out.mem = [demand.mem, cap.mem * mult];
+        if (demand.mem > cap.mem * mult)
+            out.over = true;
+    }
+    if (!out.cpu && !out.mem)
+        return undefined;
+    return out;
+}
+function figuresOf(attrs) {
+    const f = {};
+    const cpu = toCpu(attrs['cpu']?.[0]);
+    if (cpu !== undefined)
+        f.cpu = cpu;
+    const mem = toGiB(attrs['mem']?.[0]);
+    if (mem !== undefined)
+        f.mem = mem;
+    const disk = attrs['disk'];
+    if (disk?.length) {
+        // `disk 300Gi` or `disk system 30Gi data 200Gi` — sum every figure present
+        const parts = disk.map(toGiB).filter((x) => x !== undefined);
+        if (parts.length)
+            f.disk = parts.reduce((a, b) => a + b, 0);
+    }
+    const gpu = attrs['gpu'];
+    if (gpu?.length)
+        f.gpu = num(gpu[0]) ?? 1;
+    return f;
+}
+/** Moments sort as written dates; relative ones (`+1y`) come after, by size. */
+const momentKey = (w) => (w.startsWith('+') ? `~${w.slice(1).padStart(6, '0')}` : w);
+/** Attributes as they stand at `when`: base, overlaid by every earlier moment. */
+function attrsAt(base, timeline, when) {
+    if (when === 'now')
+        return base;
+    const out = { ...base };
+    for (const t of timeline)
+        if (momentKey(t.when) <= momentKey(when))
+            Object.assign(out, t.attrs);
+    return out;
+}
+const scale = (f, n) => {
+    const out = {};
+    for (const k of FIGURE_KEYS)
+        if (f[k] !== undefined)
+            out[k] = f[k] * n;
+    return out;
+};
+const add = (a, b) => {
+    const out = { ...a };
+    for (const k of FIGURE_KEYS)
+        if (b[k] !== undefined)
+            out[k] = (out[k] ?? 0) + b[k];
+    return out;
+};
+export function capacityTable(m, opt = {}) {
+    const inPhase = (attrs) => !opt.phase || !attrs['phase']?.length || attrs['phase'].includes(opt.phase);
+    const envOf = (id) => {
+        let cur = id;
+        while (cur) {
+            const ob = m.objects.get(cur);
+            if (!ob?.parent)
+                return cur;
+            cur = ob.parent;
+        }
+        return id;
+    };
+    const hostKind = (id) => m.objects.get(id)?.kind;
+    // every moment anyone mentions
+    const moments = new Set();
+    for (const ob of m.objects.values())
+        for (const t of ob.timeline)
+            moments.add(t.when);
+    for (const p of m.placements)
+        for (const t of p.timeline)
+            moments.add(t.when);
+    const cols = ['now', ...[...moments].sort((a, b) => momentKey(a).localeCompare(momentKey(b)))];
+    const envs = new Map();
+    const envFor = (id) => {
+        const e = envOf(id);
+        if (!envs.has(e)) {
+            const ob = m.objects.get(e);
+            envs.set(e, { id: e, label: ob?.name ?? ob?.localId ?? e, rows: [], totals: {} });
+        }
+        return envs.get(e);
+    };
+    const rowOf = (id, label, kind, base, timeline, countKey, host) => {
+        const figures = {};
+        for (const when of cols) {
+            const a = attrsAt(base, timeline, when);
+            const count = countKey.map(k => num(a[k]?.[0])).find(x => x !== undefined) ?? 1;
+            figures[when] = { ...scale(figuresOf(a), count), count };
+        }
+        return { id, label, kind, host, figures, counted: true };
+    };
+    // nodes and sized clusters are resources in themselves
+    for (const [id, ob] of m.objects) {
+        if (!PLACEMENT_KINDS.has(ob.kind) || !inPhase(ob.attrs))
+            continue;
+        if (ob.kind === 'node')
+            envFor(id).rows.push({ ...rowOf(id, ob.name ?? ob.localId, 'node', ob.attrs, ob.timeline, ['count']), load: hostLoad(m, id) });
+        else if (ob.kind === 'cluster' && (ob.attrs['cpu'] || ob.attrs['mem']))
+            envFor(id).rows.push({ ...rowOf(id, ob.name ?? ob.localId, 'cluster', ob.attrs, ob.timeline, ['nodes', 'count']), load: hostLoad(m, id) });
+    }
+    // a sized run inside a cluster or a managed service is a resource too;
+    // a run on a node is not — the node already is
+    for (const p of m.placements) {
+        if (!inPhase(p.attrs) || hostKind(p.host) === 'node' || hostKind(p.host) === undefined)
+            continue;
+        const a = effectiveSizing(m, p);
+        if (!a['cpu'] && !a['mem'] && !a['disk'] && !a['gpu'])
+            continue;
+        const logical = [...m.objects.values()].find(o => o.id === p.ref || o.localId === p.ref);
+        const host = m.objects.get(p.host);
+        const row = rowOf(`${p.host}/${p.ref}`, logical?.name ?? p.ref, 'run', a, p.timeline, ['replicas'], p.host);
+        row.counted = host.kind !== 'cluster' || (!host.attrs['cpu'] && !host.attrs['mem']);
+        envFor(p.host).rows.push(row);
+    }
+    // what the stores hold: `capacity size 340Gi growth 11Gi/mo` on a datastore or cache,
+    // shown in the environment it runs in — a line of its own, not summed into the
+    // disk of the hosts (that is sizing; this is content, and it grows)
+    const monthsFrom = (when) => {
+        if (when === 'now')
+            return 0;
+        const rel = /^\+(\d+)([dwmy])$/.exec(when);
+        if (rel)
+            return +rel[1] * { d: 1 / 30, w: 7 / 30, m: 1, y: 12 }[rel[2]];
+        const abs = /^(\d{4})(?:-(\d{2}))?/.exec(when);
+        if (!abs)
+            return undefined;
+        const now = new Date();
+        return (+abs[1] - now.getUTCFullYear()) * 12 + ((abs[2] ? +abs[2] : 1) - (now.getUTCMonth() + 1));
+    };
+    for (const p of m.placements) {
+        const logical = [...m.objects.values()].find(o => o.id === p.ref || o.localId === p.ref);
+        if (!logical || (logical.kind !== 'datastore' && logical.kind !== 'cache') || !inPhase(logical.attrs))
+            continue;
+        const cap = logical.attrs['capacity'] ?? [];
+        const pair = (k) => { const i = cap.indexOf(k); return i >= 0 ? cap[i + 1] : undefined; };
+        const size = toGiB(pair('size'));
+        if (size === undefined)
+            continue;
+        const g = /^(\d+(?:\.\d+)?\s*[A-Za-z]*)\/(d|w|mo|m|y)$/.exec(pair('growth') ?? '');
+        const perMonth = g ? (toGiB(g[1]) ?? 0) * { d: 30, w: 30 / 7, mo: 1, m: 1, y: 1 / 12 }[g[2]] : 0;
+        const figures = {};
+        for (const when of cols) {
+            const months = monthsFrom(when);
+            figures[when] = { disk: Math.round((size + perMonth * Math.max(0, months ?? 0)) * 10) / 10, count: 1 };
+        }
+        if (m.objects.get(p.host))
+            envFor(p.host).rows.push({ id: `${p.host}/${p.ref}#data`, label: `${logical.name ?? p.ref} · data`, kind: 'data', host: p.host, figures, counted: false });
+    }
+    for (const e of envs.values())
+        for (const when of cols)
+            e.totals[when] = e.rows.filter(r => r.counted).reduce((acc, r) => add(acc, r.figures[when]), {});
+    return { moments: cols, envs: [...envs.values()] };
+}
+/** `12.5` → `12.5`, `0.78125` → `0.8`, `2048` → `2048` */
+export const fmt = (n) => n === undefined ? '' : Number.isInteger(n) ? String(n) : String(Math.round(n * 10) / 10);

package/dist/src/check.d.ts

@@ -0,0 +1,21 @@
+import type { Doc } from './cst.js';
+import { type Diagnostic } from './diagnostics.js';
+import type { Model } from './model.js';
+/**
+ * Semantic diagnostics (spec §17.10). The parser only knows shapes; this pass
+ * knows names. It never changes the document and never stops a render — the
+ * lens still draws what it can — it only says what a reader would trip on.
+ *
+ *   AC100  duplicate id                      error
+ *   AC101  unresolved reference              warning
+ *   AC102  ambiguous reference               warning
+ *   AC103  reserved block kind               info      (rule · decision · board · profile — kept, not interpreted)
+ *   AC104  unknown attribute                 info      (`x-…` keys are silent: they are yours)
+ *   AC105  `archcode <version>` pragma       warning   (unknown version, or not the first statement)
+ *   AC106  `at` without a moment             error
+ *   AC107  relation between placement blocks warning   (a node does not `call` a cluster — put things inside)
+ *   AC108  `run` outside a placement block   error
+ *   AC109  `run` of something that cannot run warning  (an actor, an external, a topic)
+ */
+export declare const LANGUAGE_VERSIONS: Set<string>;
+export declare function check(doc: Doc, m: Model): Diagnostic[];