IF Commons GitHub

Headless composition

0009Draft

0009-composition · owner if · domain commons

The plugin and its contract

FR-001checkpassing

A plugin MUST be the value that a package exports (Plugin, made only by definePlugin), and a host MUST take a plugin's nodes through that value alone, never by reading a file of the package: its stable identity is the program's name, a hyphen and a noun (PluginId, a branded type made only by parsePluginId or parsePluginIdText), its contract is the number PLUGIN_CONTRACT, and it holds its version, its summary, the nodes it contributes (each with the path of the branch it is placed in, the root where none) and the plugins it requires. definePlugin MUST return every problem of a definition as a value (plugin/id, plugin/version, plugin/summary, plugin/empty, plugin/root-claim, plugin/requires), and MUST NOT throw. Taken from: the plan of archon, whose plugins are packages named archon-<noun>.

Enforced (check): .github: cd commons/headless && bun run verify — suite/composition.test.ts: a plugin is a value made by definePlugin with a stable id, and every problem of a definition is returned as a value

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

Written in: headless/src/logical/compose.ts

Tests: passed: suite/composition.test.ts a plugin is a value made by definePlugin with a stable id, and every problem of a definiti

FR-002checkpassing

A plugin MUST place a node at the root of the program only under its own noun (archon-server contributes the word server), so that a root word names the plugin that owns it; below another branch it MAY place nodes where that branch exists.

Enforced (check): .github: cd commons/headless && bun run verify — suite/composition.test.ts: a plugin is a value made by definePlugin with a stable id, and every problem of a definition is returned as a value

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

Written in: headless/src/logical/compose.ts

Tests: passed: suite/composition.test.ts a plugin is a value made by definePlugin with a stable id, and every problem of a definiti

Composition

FR-003checkpassing

compose(host, plugins) MUST return one Program made of the host's own nodes and each plugin's, placed in the order of the plugin ids so that the tree does not depend on the order in which the plugins are given, and MUST return the owner of every command (the host or a plugin id). Two contributions of the same branch name MUST merge, their children placed one by one.

Enforced (check): .github: cd commons/headless && bun run verify — suite/composition.test.ts: composing a host and plugins gives one program with the owner of every command, the same in any order of the plugins, with one help, completions, man page and verb ids

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

Written in: headless/src/logical/compose.ts

Tests: passed: suite/composition.test.ts composing a host and plugins gives one program with the owner of every command, the same i

FR-004checkpassing

Where two owners claim one verb compose MUST return the conflict as a value and no tree: claimed-twice (two commands, or two owners of one word), command-vs-branch (one a command and the other a branch), missing-parent (a branch to place below that does not exist) or parent-is-command; each names the path and the owners in the order they claimed. It MUST NOT choose a winner, and it MUST NOT throw. The same plugin composed twice (duplicate-plugin), a plugin of another program (wrong-program), a contract other than PLUGIN_CONTRACT (contract) and a requirement that is not composed (missing-requirement) MUST each be an error value, and every error of a composition MUST be returned together.

Enforced (check): .github: cd commons/headless && bun run verify — suite/composition.test.ts: two plugins claiming one verb is a conflict value naming both owners, no winner is chosen, and the other errors are values too

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

Written in: headless/src/logical/compose.ts

Tests: passed: suite/composition.test.ts two plugins claiming one verb is a conflict value naming both owners, no winner is chosen,

FR-005checkpassing

The composed program MUST be checked as one program (modelProblems with the reach policy required of every command), a problem of it MUST be an error value of the composition (model), and the tier of every command MUST be on the host's ladder (tier-not-on-ladder): there is one gate for the whole command (0010-audience-tiers).

Enforced (check): .github: cd commons/headless && bun run verify — suite/composition.test.ts: the composed program is checked as one: a command with no reach policy and a tier that is not on the ladder are errors of the composition

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

Written in: headless/src/logical/compose.ts

Tests: passed: suite/composition.test.ts the composed program is checked as one: a command with no reach policy and a tier that is

FR-006checkpassing

A program composed of plugins MUST have one help, one completion script for each shell, one man page and one run log: they are drawn from the one Program, the log of a run MUST say which owner contributed the command it ran (Program.origins), and the verb identifiers of the program (verbIds: the program's name and the words of each command, sorted) MUST be stable, so that a plugin's test can hold them in a snapshot.

Enforced (check): .github: cd commons/headless && bun run verify — suite/composition.test.ts: composing a host and plugins gives one program with the owner of every command, the same in any order of the plugins, with one help, completions, man page and verb ids; suite/composition.test.ts: a composed program runs as one: its commands run, the run log names the plugin they came from, and there is one log

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

Written in: headless/src/logical/compose.ts

Tests: passed: suite/composition.test.ts composing a host and plugins gives one program with the owner of every command, the same i; passed: suite/composition.test.ts a composed program runs as one: its commands run, the run log names the plugin they came f

Conformance

FR-007checkpassing

pluginConformance(plugin, host) MUST give a result for each rule of CONFORMANCE_RULES (definition, contract, program, root-claim, composes, tiers, reach, deterministic, ids) by composing the plugin alone with a host that declares nothing but its name and ladder (the plugins it requires standing in), MUST be pure, and a plugin that passes it MUST compose with any other plugin that passes it unless they claim one verb.

Enforced (check): .github: cd commons/headless && bun run verify — suite/composition.test.ts: the conformance suite gives a result for every rule, passes a good plugin and fails, by rule, a plugin that breaks one

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

Written in: headless/src/logical/compose.ts

Tests: passed: suite/composition.test.ts the conformance suite gives a result for every rule, passes a good plugin and fails, by ru

Acceptance scenarios

  1. Given a host and two plugins (server, device), When they are composed in either order, Then the tree, its owners and its help are the same, per FR-003 and FR-006.
  2. Given two plugins that each place a command at server list, When they are composed, Then the result is a claimed-twice conflict naming both, per FR-004.
  3. Given a plugin that claims the root word device while being archon-server, When it is defined, Then it is plugin/root-claim, per FR-002.
  4. Given a composed program, When a command runs, Then the run log names the plugin it came from, per FR-006.
  5. Given a plugin with a command with no reach policy, When the conformance suite runs, Then conformance/reach fails and says which, per FR-007.

Out of scope

  • Finding and loading the packages: the host's composition root imports each plugin by its package name and gives the values to compose.
  • Ordering of verbs in the help beyond the ids' order, and versions of the host that a plugin requires.

Edge cases

  • A plugin that requires a plugin that is composed: it composes; one that is not composed is missing-requirement, per FR-004.
  • A branch of the host and a branch of a plugin of one name: they merge, and a command inside them claimed twice is the conflict, per FR-003 and FR-004.
  • A host with no children and no plugins: an empty program, which is not an error, per FR-003.

Assumptions

  • A plugin is written in TypeScript against the version of Headless the host uses; PLUGIN_CONTRACT changes only when the type of Plugin changes incompatibly.

Open questions

  • None.

Key entities

  • Plugin - what a package exports to extend a program.
  • Composition - the one program, its owners, and the conflicts as values.

Success criteria

SC-001success criterion

A fleet's composition root imports its plugins and gets one command, or the list of everything wrong, and a plugin author runs one function to know the plugin conforms.

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

AnyFS command line, physical/program, Headless, logical/compose, Repoctl, physical/program, Archon tool plugin: layers, Archon assembly

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