facets · docs
DocumentationLIVE

The reference layer

Start here

Four files are enough to use the instrument: the quickstart, the tour, the glossary, and the author's path. Everything after this section is the record behind them: the language spec, the theory and its provenance, design positions, decisions, and the parked ledger.

  • quickstart.md — LIVE — ten minutes from just dev to a judged, running model, using the two smallest corpus files (bathtub, then process-m). The newcomer on-ramp.
  • tour.md — LIVE — the reader's tour: one running model (hal-projection) grown line by line, each step pairing SL with what the canvas and the three lenses render; three audience entry paths and the SL ↔ canvas ↔ JSON ↔ kernel notation table.
  • authoring-models.md — LIVE — the author's path from a description to a running, gated, gallery-visible model: the .sl → mint → bundle loop and the five facts that bite everyone once (deaf receivers, the matter tap, where amount acts, stocks-start-at-zero, loops need memory).
  • glossary.md — LIVE — fast definitions of the ~15 load-bearing terms (system, lens, bond/mere, conservation invariant, WorldModel, Save vs Export, run ledger, SL, systemhood, mode/lens, neutral spec, golden, dynamics-kind, precondition, concordance), each grounded in a fuller doc.

The language

  • language/ — SL, the Facets system language. Its README.md is the front door: what SL is, what it looks like, reading order, the corpus, and where the language lives in the code.
    • language/spec.md — LIVE — the SL v1.0 specification: five design commitments, lexicon, EBNF grammar, semantics, annotation layer, round-trip contract, structure/dynamics boundary, worked examples, lineage, known gaps. Normative. (Was docs/sl2-spec.md; moved 2026-07-18 when the language got its own home.)
    • language/terminology-concordance.md — LIVE — the Klir·Bunge·Mobus terminology grid: 12 kernel distinctions × 3 traditions, every cell primary-cited and VERIFIED/UNGROUNDED-marked. SSOT for the spec's lexicon attribution, per-lens UI copy, and K≅2 convergence exhibits; federates the partial two-tradition mappings in SSF.

Theory and kernel

  • kernel-architecture.md — LIVE — what the kernel is as a system: what describe/lens_facts/validate_mode/analyze actually compute, CODE-READ against source with confidence ratings (its two marks — CODE-READ vs MACHINE-CHECKED — are defined at the top of the doc). Read before trusting the substrate.

  • VENDORING.md — LIVE — where bert-core and bert-compose came from: the branch point (40de7a7, established by content), the two edits made on the way in, how far the copies have drifted, and why this is a successor rather than a fork under maintenance. Answers what here is ours? mechanically.

  • lean-provenance.md — LIVE — the pinned systems-science-foundations commit behind every "machine-checked" claim, the generated per-claim map (rendered from lean-manifest.json, with each declaration's Lean kind), the staleness budget against SSF HEAD, the K ≅ 2 scope fence, the two resolution gates, the from-this-repo-alone audit path, and the pin-moves-with-the-fixture update discipline (issues #128, #232; the provenance complement to ../spec/LENS_ENTRY_SPEC.md §D).

  • lean-manifest.json — LIVE — the machine-readable source of truth behind lean-provenance.md: one row per claim, carrying the SSF symbol and the Lean keyword it is declared with. The doc's tables are generated from it (just provenance); nobody hand-edits a citation string.

  • wellformedness-mapping.md — RESEARCH — the three well-formedness predicates compared in both directions: the eight-field Lean WellFormed structure, the 28 kernel codes, and the four conjuncts the life-cycle paper prints. Zero Lean fields map cleanly, six are partial, two are unviolable in the WorldModel; nineteen kernel codes check something other than well-formedness, which is the kernel doing more rather than less. Three gaps are demonstrated by executed probes, and the scope of the machine-checked closure result (two Step constructors against a fourteen-row table) is stated so it is hard to over-quote.

  • theory-fidelity.md — LIVE — per-tradition (Klir/Bunge/Mobus) take/drop/where/why, the mode-stamp semantics, the perspectival-realist scope statement, and the #5 collapse as a worked example of the refuse-don't-truncate discipline. For a reader assessing the theory's quality, not just its UI.

  • 216-cross-lens-findings.md — RESEARCH — the first read of the #216 cross-lens matrix over all 35 entries: every measurable model is read differently by each lens that accepts it (34 of 34, zero aligned), the per-lens count of authored content left unrendered (Klir 371 · Bunge 181 · Mobus 49), and why an all-green Klir column is evidence about the projection rather than about the models. The empirical companion to theory-fidelity.md; open questions at #284, #285, #286.

  • steel-plant-walkthrough.md — LIVE — the Steel-Plant walk demo script: the click path through Mobus's ch. 4 procedure (Figs. 4.14 → 4.16 → 4.17) as a three-level decomposition walk, what to say at each level, and where the seam glyphs live. Companion to assets/walkthroughs/steel-plant/ (all three levels).

  • 288-level-census.md — ADOPTED — the #288 Klir epistemological-level census, ratified 2026-08-08: every shipped entry declares its level (source 2 · generative 1 · structure 36 · data and metasystem 0 — the empty levels being a finding about SL's reach), the four ratifying decisions with their reasoning, the draft's eight-fork ledger resolved, and the live §5.4 cross-level refusal the declarations make possible. Five of the eight forks fell to one test: is the complete generating rule in the file?

  • audits/seam-readiness-2026-09-04.md — RESEARCH — which of the 29 shipped models could carry a decomposition seam today, run the day continuous zoom shipped (#139). Every model has crossings and none is network-first: 21 read as systems with 78 seam-ready components and no decomposes anywhere, 10 are corpus transcriptions of sources that were drawn as graphs, and only the Steel-Plant walk ships a seam. Regenerated by scripts/seam_audit.py, which compiles each model with the kernel and reports per component.

Design positions and research

design/README.md is the status-grouped index of this section (LIVE · ADOPTED · PROPOSED · RESEARCH). The highlights follow.

Positions — a stance the repo takes, or is being asked to take:

  • predictions/llm-market.md — PROPOSED — the llm-market prediction ledger: append-only entry format keyed to the spec content hash, calibration provenance, zero predictions recorded yet.
  • design/dynamics-principled-position.md — ADOPTED (adopted via #86) — what counts as dynamics: a state-transition family satisfying the semigroup axiom (Mesarovic–Takahara); a dynamics-kind is the transition functor; conservation is an invariant the model declares, not the engine's premise. Supersedes the "dynamics = the conservation engine" framing in the retired archive/roadmap-pre-web-rebuild.md Arc 4. language/spec.md §8 is normatively bound to it. Research trail: design/dynamics-research/.
  • design/hierarchical-decomposition-investigation.md — PROPOSED (#89) — the kernel's data model can carry arbitrary depth, but every active path is flat: project() forces level 1, to_canvas() drops deeper levels, validate_operational() refuses level > 1. Recommends decomposition by reference; implementation gated on deriving the parent↔child boundary math from the Lean 8-tuple.
  • design/decomposition-foundations.md — RESEARCH (#89) — the math layer under the investigation's Option B: the Eq. 4.3 substitution slot by slot over the Lean 8-tuple, the boundary-contract bijection β, the three Lean statements that open the gate, and the Lean-first dependency order. Explicit non-goals: no grammar, kernel, or neutral-spec change.

Research foundations — what others build on; not themselves decisions:

  • design/sl2-authoring-language.md — RESEARCH — the foundation behind language/spec.md: three concrete syntaxes over one neutral spec, the precedent survey (SysML v2, Modelica, Stella, Quint; gpt-jargon as negative control), keep/shed against Mobus and BERT SL v0.1, and the staged rung plan. Rungs 1–3 shipped 2026-07-18 (#82); its 8 open questions remain closeable work.
  • design/dynamics-research/ — RESEARCH — the research trail behind the adopted dynamics position: six primary-source reads (Mobus, Bunge, Klir, Bertalanffy, category theory, external general-systems literature), a synthesis, and two adversarial critiques (critique-novelty.md, critique-coverage.md). Start at its README.md for the reading order.
  • design/llm-integration-research.md — RESEARCH — LLM context/authoring/analysis (rests on kernel-architecture.md). §11 is the lens-fidelity mechanism; §12 is the recommended-first-rung plan the 2026-07-17 analysis rung executed.
  • design/lens-palettes.md — LIVE — the lens grounding for Phase 3/4 (Klir / Bunge / Mobus), and the two kernel primitives (boundary identity, edge classification) behind the faithful renderings.
  • design/educational-model-suite.md — RESEARCH — a 13-model graded curriculum teaching systems concepts through the instrument (primitive-first; refusals as lessons), plus a faculty-appeal appendix. Not in-tool, and untracked: the curriculum was planned against #80 and #21, both of which closed in July 2026 having shipped narrower things.
  • design/shape-vocabulary-research.md — RESEARCH — notation precedents (Mobus's own icon set, Stella/Forrester, Odum, SysML ports, automata, Petri nets) for the palette shape vocabulary (#81).
  • design/design-system-draft.md — RESEARCH — visual design system draft.
  • design/sandbox-surface.md — ADOPTED — the sandbox surface: a Home document entry (never a third mode, #345), the boundary's one stateful wasm export (SandboxSession), and the WorldModel-as-document graduation path; conservation declared, not premised (ADR 0003).
  • proposals/112-transition-functor.md — ADOPTED (#112) — the transition functor as shipped: F = Id over the whole-circuit product state, Δt a family index, the shipped forcing read as the closed instance; slice 1 implemented 2026-08-15.
  • proposals/workbench-declutter.md — PROPOSED — four ranked options for decluttering the model workbench, each flagged by how much decided doctrine (#345, #100/#309) it relitigates; option 1 shipped 2026-08-31.
  • proposals/trace-separation.md — PROPOSED — separating recorded trace from transition state (stage 0 applied 2026-08-15; stages 1–3 await a dedicated session with byte-identical float assertions as the acceptance bar).
  • translation-apparatus-walkthrough.md — RESEARCH — the translation apparatus running end to end, every number reproducible via bert run assets/examples/translation-apparatus.sl --t 15 (current as of 2026-08-15).

Decisions

  • decisions/0001-canvas-rendering-svg.md — ADOPTED — the hand-rolled React+SVG canvas call (vs. a graph library), from the blind-pick spike.
  • decisions/0002-web-first-rebuild.md — ADOPTED — the egui → React/wasm rebuild (Rust brain, React face); written retrospectively from the repo record.
  • decisions/0003-conservation-declared-not-assumed.md — ADOPTED — conservation is an invariant a model declares, never the engine's premise; the compose engine is the first interpreter of one dynamics-kind. Records the #86 position in force.
  • decisions/0006-closed-metric-verbs.md — ADOPTED — declared metrics (#203) grow a closed verb vocabulary, one checkable verb at a time, each owing a separating instance — never an open expression language. Ranking is a panel view, not a verb.
  • decisions/0005-vocabulary-tiers.md — ADOPTED — four vocabulary tiers (primitives / compositions / faithful lenses / vocabulary packs) and the rule that decides them: a tradition that never defines system is not a lens. Places Troncale's SPT as a composition, and records the stranded-sweep gap.
  • decisions/0004-neutral-archive-canvasmodel-json.md — ADOPTED — the neutral archive format is CanvasModel JSON. Adopted, then indexed nowhere for four days; its only inbound link was from an orphan until #235.

The parked ledger

  • parked.md — LIVE — the permanent record of work that was thought through, decided on, or found out, and then deliberately not scheduled. Eleven entries retired from the issue board in the W30 ratification audit (#234), each carrying what it is, what was decided, the evidence that settled it, and whether it has a live unpark trigger. It exists because 8 of 11 parked issues recorded a finding, and an issue is the wrong container for a finding.

Historical (pre-web-rebuild, kept as record)

  • archive/canvas-architecture.md — HISTORICAL — the standalone egui canvas (src/main.rs). Superseded by the web rebuild; its kernel-seam semantics (mode stamping, audit-panel verdict-quoting) carried forward and are still accurate, but the UI mechanics it describes are gone. (A stub remains at the old canvas-architecture.md path.)
  • archive/on-the-word-ladder.md — HISTORICAL — the concordance of the three senses of "ladder/rung/climb" in this repo. Its mode-entry hazard (Bucket A) is retired: mode entry now speaks lens vocabulary (see theory-fidelity.md, gated by scripts/doc_lint.py); the doc survives as the record of the words that legitimately stay (compose dependency ladder, per-edge classification, project-phase "rung"). Issue #90. (A stub remains at the old on-the-word-ladder.md path.)
  • archive/fidelity-audit.md — HISTORICAL — faithfulness verdicts from the egui-era canvas; the current fidelity assessment is theory-fidelity.md.
  • archive/ — HISTORICAL — superseded design docs; archive/README.md lists them all. One file there is RESEARCH rather than historical: archive/gst-1968-full.md, the Bertalanffy source extraction, which nothing superseded and which the dynamics research still reads against. It lives under archive/ for its size.

Three redirect stubs remain at the pre-move paths so old links do not rot. They are three lines each and carry no content: canvas-architecture.md, fidelity-audit.md, on-the-word-ladder.md.

Root-level references

  • Roadmap board — LIVE — the forward-looking plan, organized by epic (Reality Interface · Joy Surface · Resident Co-author · Trusted Seam · Legible Foundations · The Language · What Runs · Notation · Teaching Surface). There is no roadmap file; the retired one is archive/roadmap-pre-web-rebuild.md.
  • ../crates/bert-lenses-kernel/API.md — LIVE — the frozen JS↔wasm surface (append-only). Includes the SL surface (compile_sl / emit_sl).
  • ../web/DESIGN.md — LIVE — Halcyonic Frost design tokens for the face, and the one owner of the design system. design/design-system-draft.md, design/visual-language.md, design/lens-palettes.md, and the retired archive/design-system.md are all subordinate to it.
  • ../spec/LENS_ENTRY_SPEC.md — LIVE — the lens-entry specification; §D is the provenance complement to lean-provenance.md.
  • running-permanently.md — LIVE — how to keep the app running as a permanent local service rather than a just dev session.
  • ../pipeline/README.md — LIVE — the corpus pipeline: its own venv, its own dependencies, and how to run it.
  • ../examples/README.md — LIVE — what the worked examples are and how to open them.