IF Commons GitHub

The ladder

0016Draft

0016-ladder · owner if · domain commons · part of 0003-mizan

The ladder

FR-001checkpassing

The ladder MUST be typed data in commons' ontology: a Rung class whose individuals each carry a number, a name, a purpose, the homes of its files (paths and globs), the numbers of the rungs it may rely on, the commands that prove it and, where a harness traces its terms to its specifications, the specifications it comes from (spec), in TypeScript on the kernel's RDF (0012-ontology).

Enforced (check): .github: bun test ./tests/ — Mizan ontology: the nine rungs are individuals of mz:Rung with number, purpose, required and rely-on edges

Proved by: tests/commons-mizan-ontology.test.ts

Tests: passed: tests/commons-mizan-ontology.test.ts the ladder is eleven individuals of mz:Rung: rungs 0 to 7 required, 8 optional, 9 observer

FR-002checkpassing

Rungs 0 to 7 MUST be required: 0 ontology, 1 specifications, 2 governed data, 3 data operations, 4 infrastructure rules, 5 business rules, 6 application (the headless hosts, then the windowed hosts) and 7 documentation. A rung 8, the lifecycle (what is retired, alive but not to be used, then what is archived, dead and safe to delete), MUST be optional: where a harness has it, it relies on no rung and no rung relies on it.

Enforced (check): .github: bun test ./tests/ — Mizan ontology: rungs 0 to 7 are required, rung 8 is optional and relies on nothing

Proved by: tests/commons-mizan-ontology.test.ts

Tests: passed: tests/commons-mizan-ontology.test.ts the ladder is eleven individuals of mz:Rung: rungs 0 to 7 required, 8 optional, 9 observer

Cited by: Kanon

FR-003checkpassing

A rung MUST rely only on the rungs below it that it names, and never reach around the rung under it (dependency direction); a change MUST be complete only when every rung it touches is updated and proved by that rung's checks, lowest first (order of work).

Enforced (check): .github: bun test ./tests/ — Mizan ontology: a rung relies only on rungs below it, and no rung relies on rung 8

Proved by: mizan/suite/mizan-changes-pure.test.ts, tests/commons-mizan-ontology.test.ts

Tests: passed: tests/commons-mizan-ontology.test.ts a rung relies only on rungs below it, and nothing relies on the lifecycle rung

Cited by: changes/capability-view, Intellectual Frontiers Capabilities Configuration Management, Kanon

FR-004noneno test run

Headless first: rungs 0 to 5 MUST be headless; rung 6 MUST hold the headless hosts before the windowed ones, and every operation a window offers MUST also be a command or a tool.

Enforced (none): Planned, Phase 2 and 3 of issue #10: the Rung class and the generator check are not built yet

A harness's instance

FR-005noneno test run

A harness MUST state its ladder as individuals of Rung in its own ontology, and MAY add homes, checks and rely-on edges to a rung; it MUST NOT renumber, rename or drop rungs 0 to 7, and MUST NOT renumber or rename rungs 8 to 10, and a rung it leaves empty MUST say why.

Enforced (none): Planned, Phase 2 and 3 of issue #10: the Rung class and the generator check are not built yet

FR-006noneno test run

Every folder, package and file of a harness MUST be on exactly one rung, by the most specific of the rungs' homes, and a TypeScript import MUST NOT climb to a higher rung or reach around the one under it; the checks are 0015-trace FR-009 and 0015-trace FR-010, run by the tools of 0003-mizan.

Enforced (none): Planned, Phase 2 and 3 of issue #10: the Rung class and the generator check are not built yet

FR-007noneno test run

A harness's constitution table of the ladder and the layout in its AGENTS.md MUST be generated from its instances between marker comments (<!-- ladder:begin --> and <!-- ladder:end -->, <!-- layout:begin --> and <!-- layout:end -->), and its generator's --check MUST fail where either differs.

Enforced (none): Planned, Phase 2 and 3 of issue #10: the Rung class and the generator check are not built yet

FR-008checkpassing

Every rung MUST have exactly one kind, a member of the code list mz:RungKind: required (rungs 0 to 7), optional (rung 8), observer (rung 9) or environment (rung 10); the kind MUST be what the checks branch on, not the number.

Enforced (check): .github: bun test ./tests/ — Mizan ontology: every rung has one kind of mz:RungKind, rungs 0 to 7 required, 8 optional, 9 observer and 10 environment

Proved by: tests/commons-mizan-ontology.test.ts

Tests: passed: tests/commons-mizan-ontology.test.ts the ladder is eleven individuals of mz:Rung: rungs 0 to 7 required, 8 optional, 9 observer

Cited by: mizan/mizan

FR-009checkpassing

A rung 9, the evidence, MUST be of kind observer: the records the system produces by operating (test and check runs, findings, nonconformances, corrective actions, change records, attestations), append-only and never written by hand. It MAY rely on rungs 0 to 7 for the shapes of what it records, it MAY observe rungs 8 and 10 without relying on them, and no rung MUST rely on it, so that evidence cannot authorize itself.

Enforced (check): .github: bun test ./tests/ — Mizan ontology: rung 9 is an observer that may rely on rungs 0 to 7 and no rung relies on it

Proved by: tests/commons-mizan-ontology.test.ts

Tests: passed: tests/commons-mizan-ontology.test.ts a rung relies only on rungs below it, and nothing relies on the lifecycle rung

FR-010checkpassing

A rung 10, the workspace, MUST be of kind environment: the controlled working environment everything is built in (the layout of repositories on a machine, the approved tools, the policy and hooks). It MUST rely on no rung and no rung MUST rely on it; rung 9 records what it does.

Enforced (check): .github: bun test ./tests/ — Mizan ontology: rung 10 is an environment that relies on no rung and no rung relies on it

Proved by: tests/commons-mizan-ontology.test.ts

Tests: passed: tests/commons-mizan-ontology.test.ts the ladder is eleven individuals of mz:Rung: rungs 0 to 7 required, 8 optional, 9 observer

Cited by: Intellectual Frontiers Workspaces

FR-011reviewno test run

Where a harness claims a regulated domain, rungs 9 and 10 MUST be required of it from the day it declares production; a harness that claims none MAY omit them, and a harness that omits one MUST NOT use its number for anything else.

Enforced (review): 0017-two-languages FR-007 — Whether a harness that claims a regulated domain has rungs 9 and 10 from the day it declares production is judged by a person until the harness declares its domains as typed data (0020-ifccm)

Cited by: changes/declaration, Conformance levels

Out of scope

  • Which folders a particular harness puts on which rung: each harness states its own homes.
  • Checking imports and file placement: 0015-trace.

Edge cases

  • A harness with no windowed hosts: rung 6 holds only the headless hosts, per FR-002 and FR-004.
  • A harness with nothing retired or archived: it states no rung 8, per FR-002.
  • A harness that renames rung 3: refused, per FR-005.
  • A harness that leaves rung 2 empty: it says why in the rung's purpose, per FR-005.
  • A constitution table edited by hand: the generator's check names the difference, per FR-007.
  • A rung-5 file that imports a rung-2 file when rung 5 may rely on 0, 1, 3 and 4: refused, per FR-003 and FR-006.

Assumptions

  • The ladder is Intellectual Frontiers' own architecture: no consensus standard names it (ISO/IEC/IEEE 42010 describes architecture descriptions and layered architectures are common practice, but neither defines these rungs), so 0018-standards-first treats it as unaligned, with that reason as its justification.
  • Erga and stolos each state a ladder today; they become instances of this one when they move to Mizan (issue #10, Phase 6).

Open questions

OQ-1open question

The Decision individual that records why the ladder is unaligned (0018-standards-first FR-005) is written within its 90 days.

Key entities

  • Rung - one level of the ladder, with its number, name, kind, purpose, homes, what it may rely on and what proves it.
  • RungKind - what kind of rung a rung is: required, optional, observer or environment.
  • Instance - a harness's own individuals of Rung.

Success criteria

SC-001success criterion

A harness's ladder, as individuals of Rung, is the only place its rungs are stated, and its constitution table and layout are made from them.

SC-002success criterion

A harness that departs from rungs 0 to 7 fails its check.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

Ergonex, generate-ontology, Libraries, changes/capability-view, changes/declaration, Ontology, mizan/mizan, mizan/mod, The layers, Intellectual Frontiers Workspaces, Mizan, the IF Spec Profile, Intellectual Frontiers Capabilities Configuration Management, Conformance levels, Kanon

Titles, headings, exports, tables, columns and requirements. Esc closes.