IF Commons GitHub

Headless layers

0001Draft

0001-headless-layers · owner if · domain commons

The layers

FR-001checkpassing

The library MUST be arranged as the units of one table, and every file of it MUST be in exactly one unit: src/governance/ (layer 1), src/logical/ (layer 2), one folder under src/surfaces/ for each surface (layer 3), one folder under src/targets/ for each executor (local, ssh), src/otel/ (the adapter), src/mod.ts (the entry that names the two pure layers), and the checking of the library itself (suite/, tools/, and the manifest files of its root); a file in none MUST be a finding layers/unclassified. Taken from: the layers specification of commons data (its unit table and its unclassified-file rule), which the layers of this library follow.

Enforced (check): .github: cd commons/headless && bun run verify — suite/layers.test.ts: the real tree has no finding of the layers check; suite/layers.test.ts: every file is in one unit, and a file in none is layers/unclassified

Proved by: headless/suite/layers.test.ts

Written in: headless/src/governance/mod.ts, headless/src/logical/mod.ts, headless/src/mod.ts, headless/src/surfaces/cli/mod.ts

Tests: passed: suite/layers.test.ts the real tree has no finding of the layers check; passed: suite/layers.test.ts every file is in one unit, and a file in none is layers/unclassified

FR-002checkpassing

Imports MUST point one way: the logical layer MAY import the governance layer, a surface MAY import the logical and governance layers, the adapter MAY import a surface and the layers below it, and nothing below MAY import what is above it (layers/above); a surface MUST NOT import another surface, and a layer MUST NOT import a unit its row does not name (layers/around). Taken from: the layers specification of commons data (its table of what each unit may import).

Enforced (check): .github: cd commons/headless && bun run verify — suite/layers.test.ts: the real tree has no finding of the layers check; suite/layers.test.ts: imports point one way: below may not import above, and a surface may not import another surface

Proved by: headless/suite/layers.test.ts

Tests: passed: suite/layers.test.ts the real tree has no finding of the layers check; passed: suite/layers.test.ts imports point one way: below may not import above, and a surface may not import another su

FR-003checkpassing

A file of one unit MUST import a file of another by the package's own name and an entry of its exports (@intellectual-frontiers/headless/governance), never by a relative path (layers/relative), and an import by the package's name that exports does not name MUST be a finding layers/private. Taken from: the layers specification of commons data (its rules on package entries and relative imports).

Enforced (check): .github: cd commons/headless && bun run verify — suite/layers.test.ts: the real tree has no finding of the layers check; suite/layers.test.ts: a file of one unit reaches another through the package's exports, never by a relative path, and a name exports does not name is layers/private

Proved by: headless/suite/layers.test.ts

Tests: passed: suite/layers.test.ts the real tree has no finding of the layers check; passed: suite/layers.test.ts a file of one unit reaches another through the package's exports, never by a relative path

FR-004checkpassing

Each unit MUST import by package name only what its row of the table allows, and anything else MUST be a finding layers/external: governance, Core alone; logical, Core and the terminal's args and commands; the command-line surface, Core, the terminal and the system; an executor under src/targets/, Core and the system; the inbound ssh surface, Core alone; the adapter, Core and the telemetry; none of them an SSH library, the data library, the grc library or the ontology library. Taken from: the plan of commons/headless ("depend only on terminal, system and core") and the layers specification of commons data (its rule on external imports).

Enforced (check): .github: cd commons/headless && bun run verify — suite/layers.test.ts: the real tree has no finding of the layers check; suite/layers.test.ts: each unit imports only what its row allows: governance Core, logical Core and the terminal's args and commands, the command line Core, the terminal and the system, the adapter Core and the telemetry

Proved by: headless/suite/layers.test.ts

Tests: passed: suite/layers.test.ts the real tree has no finding of the layers check; passed: suite/layers.test.ts each unit imports only what its row allows: governance Core, logical Core and the terminal

Cited by: Headless reach and targets

FR-005checkpassing

The command-line surface MUST NOT depend on the telemetry. WHERE a run is to be reported in OpenTelemetry, the surface MUST give a port (RunObserver of its Io) and the adapter (@intellectual-frontiers/headless/otel) MUST sit behind it, as the telemetry sits behind proc.setProcessTracer of the system; no unit but the adapter MAY import the telemetry. Taken from: commons 0032-libraries-by-concern FR-003 and the way proc.setProcessTracer is installed by the telemetry's own module.

Enforced (check): .github: cd commons/headless && bun run verify — suite/layers.test.ts: the real tree has no finding of the layers check; suite/layers.test.ts: the command-line surface may not import the telemetry; only the adapter may

Proved by: headless/suite/layers.test.ts

Tests: passed: suite/layers.test.ts the real tree has no finding of the layers check; passed: suite/layers.test.ts the command-line surface may not import the telemetry; only the adapter may

FR-006checkpassing

WHEN a surface is added (a tool server, a REST interface), it MUST be one folder under src/surfaces/ with one row of the table naming the packages it may import; a folder under src/surfaces/ or src/targets/ with no row MUST fail the library's test, so that a surface cannot be added without saying what it may import (the folder src/ is a unit of the library's own, for its entry src/mod.ts alone, which the packer of commons requires there). Taken from: the decision of the plan that mcp and rest slot in beside the command line without being built now.

Enforced (check): .github: cd commons/headless && bun run verify — suite/layers.test.ts: a surface is one folder with one row of the table; a folder with no row is layers/unclassified, and its row says what it may import

Proved by: headless/suite/layers.test.ts

Tests: passed: suite/layers.test.ts a surface is one folder with one row of the table; a folder with no row is layers/unclassi

Cited by: Intellectual Frontiers Commons, Headless reach and targets, Headless REST surface (skeleton)

The check and the package

FR-007checkpassing

The table of the layers MUST be the kanon field of the manifest library.ts (commons 0033-kanon FR-010) and the library MUST keep no checker of its own: bun run verify MUST run the shared checker of Kanon (bun ../kanon/src/check.ts, finding keys of the form layers/<code> <file> <about>, held by kanon.baseline.txt) and tools/check.ts, which MUST hold the trace of the sources and tests to these specifications against trace.baseline.txt; both baselines only shrink. Taken from: commons data tools/check.ts and its layers specification (the check held against a baseline).

Enforced (check): .github: cd commons/headless && bun run verify — suite/layers.test.ts: the check holds the findings of the layers and of the trace against the baseline, which only shrinks, and verify runs it

Proved by: headless/suite/layers.test.ts

Written in: headless/tools/check.ts

Tests: passed: suite/layers.test.ts the checker holds the layers against its baseline, the trace is held by tools/check.ts, an

FR-008checkpassing

Headless MUST be published as compiled modules with their declarations as @intellectual-frontiers/headless (commons 0032-libraries-by-concern FR-005), with an entry for the package (.) and one for each layer (./governance, ./logical, ./cli, ./targets/local, ./targets/ssh, ./ssh-inbound, ./otel), for Node 26 and Bun, and its manifest (library.ts) MUST agree with its folder; its package.json MUST stay private so that nothing is published from the folder by hand. Taken from: the packaging of terminal, system and quality (commons 0032-libraries-by-concern FR-005, commons 0032-libraries-by-concern FR-013).

Enforced (check): .github: cd commons/headless && bun run verify — suite/layers.test.ts: the manifest agrees with the folder: the entries, the name, the level, the version and the distribution

Proved by: headless/suite/layers.test.ts

Written in: headless/about.ts, headless/library.ts, headless/tools/pack.ts

Tests: passed: suite/layers.test.ts the manifest agrees with the folder: the entries, the name, the level, the version, the di

Acceptance scenarios

  1. Given the real tree of the library, When the layers check runs, Then it finds nothing, per FR-001 to FR-004.
  2. Given a file of the governance layer that imports the logical layer, When the layers check runs, Then it reports layers/above, per FR-002.
  3. Given a file of the logical layer that imports a file of the governance layer by a relative path, When the check runs, Then it reports layers/relative, per FR-003.
  4. Given a file of the command-line surface that imports the telemetry, When the check runs, Then it reports layers/external, per FR-004 and FR-005.
  5. Given a folder under src/surfaces/ with no row in the table, When the library's tests run, Then they fail, per FR-006.
  6. Given the packed package, When a consumer on Node 26 and on Bun type-checks and imports each entry, Then both succeed, per FR-008.

Out of scope

  • The tool server and the REST interface themselves, and the conformance check of a program against the contract (headless check).
  • What each action does: the programs that declare them.

Edge cases

  • An import written as a dynamic import("...") or as a re-export: read as an import, per FR-002.
  • An import of the package's own root (@intellectual-frontiers/headless) from a layer: not allowed, the entry names the layers and is above them, per FR-002.

Assumptions

  • A surface is a way of being reached, not a set of commands: the same tree of commands is drawn by each.

Open questions

  • None.

Key entities

  • Unit - a folder of the table, with a class that says what it may import.
  • Surface - a folder under src/surfaces/ with a row of its own.

Success criteria

SC-001success criterion

A new surface cannot be added, and no layer can reach upward, without the check failing.

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

Intellectual Frontiers Commons, Headless reach and targets, Headless REST surface (skeleton)

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