IF Commons GitHub

Headless describes a program

0015Draft

0015-describe · owner if · domain commons

The models

FR-001checkpassing

describe(program) MUST give one LayeredModel for each tier of the program's ladder, lowest first, named <program>-<tier>, of the library headless, made from the Program alone: pure, deterministic and with no input or output, so that the same program always gives equal models. Each model MUST have the three layers of Kanon, governance, logical and physical, in that order, with the kinds each holds, and no instances. describeChecked(program) MUST give the same models as a Result, and an err that says why where the program's name cannot make an id; describe then gives none.

Enforced (check): .github: cd commons/headless && bun run verify — suite/describe.test.ts: describe gives one model for each tier of the ladder, lowest first, with the three layers, pure and deterministic, and describeChecked says why where the name is not an id; suite/describe.test.ts: for any generated program, each model has unique ids, a trace between its elements, the tools and routes of the surfaces for its tier, a command for each visible verb and nothing dropped

Proved by: headless/suite/describe.test.ts, tests/commons-headless-describe.test.ts

Written in: headless/src/describe/describe.ts, headless/src/describe/mod.ts

Tests: passed: suite/describe.test.ts for any generated program, each model has unique ids, a trace between its elements, the to; passed: suite/describe.test.ts describe gives one model for each tier of the ladder, lowest first, with the three layers,; passed: tests/commons-headless-describe.test.ts Ergonex is described for each tier: the ids are the agreed ones, every verb the tier sees

FR-002checkpassing

The kind of an element MUST be one of a closed union: action, problem-code and outcome in governance; program, plugin, verb, option and operand in the logical layer; cli-command, mcp-tool, rest-route and openapi-document in the physical layer. The layer of an element MUST be the layer of its kind (an exhaustive match), and every element MUST have an id, a layer, a kind, a name, a definition, a source and its properties, and a parent where it is a part of another.

Enforced (check): .github: cd commons/headless && bun run verify — suite/describe.test.ts: every element has the layer of its kind and an id made by the agreed forms: verbs, commands, tools, routes, options and operands

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

Written in: headless/src/describe/describe.ts, headless/src/describe/ids.ts

Tests: passed: suite/describe.test.ts every element has the layer of its kind and an id made by the agreed forms: verbs, command

Cited by: describe/ids, Headless

FR-003checkpassing

Every id MUST be an ElementId made by a smart constructor that returns a Result: a verb headless:<program>/<verb path>, a command cli:<program> <verb path>, a tool mcp:<tool name>, a route rest:<METHOD> <path>, an option <verb id>#--flag and an operand <verb id>#<operand>, and, besides those agreed with the data library, the program headless:<program>, an action action:<program>/<verb path>, a problem code problem-code:<program>/<code>, an exit status outcome:<program>/<exit name>, a plugin plugin:<owner> and the document openapi:<program>. The tool name and the path of a route MUST be those of the tool server (toolName) and of the REST surface (pathOf).

Enforced (check): .github: cd commons/headless && bun run verify — suite/describe.test.ts: every element has the layer of its kind and an id made by the agreed forms: verbs, commands, tools, routes, options and operands

Proved by: headless/suite/describe.test.ts, tests/commons-headless-describe.test.ts

Written in: headless/src/describe/describe.ts, headless/src/describe/ids.ts

Tests: passed: suite/describe.test.ts every element has the layer of its kind and an id made by the agreed forms: verbs, command; passed: tests/commons-headless-describe.test.ts Ergonex is described for each tier: the ids are the agreed ones, every verb the tier sees

Cited by: describe/ids, Headless

The layers

FR-004checkpassing

Governance MUST hold one action for each verb, whose properties are the annotations of the action: its kind, effect, idempotency, audience, tier, preview, check and human-only options, and the channels, read-only fact, need of a terminal, whom it runs as and confirmation of its reach policy (null where it has none); one problem-code for each code of the program's catalogue, and for each generic code the catalogue does not hold, with its explanation (title and what in the definition, why, fix and guide as properties); and one outcome for each exit status of the one table, with its status and its meaning.

Enforced (check): .github: cd commons/headless && bun run verify — suite/describe.test.ts: governance holds the action of each verb with its annotations, the problem codes with their explanation and the exit statuses by name

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

Written in: headless/src/describe/describe.ts

Tests: passed: suite/describe.test.ts governance holds the action of each verb with its annotations, the problem codes with thei

FR-005checkpassing

The logical layer MUST hold the program (its version, prefix, ladder and default command), one verb for each command of the tree with its summary as the definition, its examples and the annotations of its action as properties it carries, one option for each option of the verb (those it declares and those the model adds by its action's facts: --json, --dry-run, --yes, and the others) and one operand for each operand, each with its verb as parent. A verb contributed by a plugin MUST name it as its origin (Program.origins) and have the plugin as its parent, and a plugin MUST list the verbs it contributes; a verb of the host has the program as its parent.

Enforced (check): .github: cd commons/headless && bun run verify — suite/describe.test.ts: the logical layer holds the program, the verbs with their options, standard ones included, operands and examples, and the plugin that contributed a verb as its parent

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

Written in: headless/src/describe/describe.ts

Tests: passed: suite/describe.test.ts the logical layer holds the program, the verbs with their options, standard ones included,

FR-006checkpassing

What is wrong with the model MUST be the findings of the model: each problem of modelProblems (a name, an action's facts, a reach policy, a reserved option or short, a built-in word, a human-only option that is not declared) and of catalogueProblems, with a rule and the element it is about; a duplicate id, an element with no words to define it, a tool name two verbs would share and an id that cannot be made MUST be findings too, never an exception and never a silent omission.

Enforced (check): .github: cd commons/headless && bun run verify — suite/describe.test.ts: the problems of the model are findings of the element they are about, and nothing is thrown; suite/describe.test.ts: two verbs that would be one tool are one tool and a finding, never two elements of one id

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

Written in: headless/src/describe/describe.ts

Tests: passed: suite/describe.test.ts the problems of the model are findings of the element they are about, and nothing is throw; passed: suite/describe.test.ts two verbs that would be one tool are one tool and a finding, never two elements of one id

FR-007checkpassing

The physical layer of a model MUST hold, for each verb the tier of the model may see (tierGate), a cli-command; a mcp-tool where the tool server draws the verb (the reach policy names the mcp channel and the audience is not human), with the name, the hints and the inputs of toolOf; and a rest-route where the REST surface draws it (the rest channel, not for a person alone), the method and the path of the OpenAPI document, which is an openapi-document that is the parent of its routes. The tools of a model MUST be exactly those that served gives for its tier, and the routes exactly the paths of openApiOf for its tier.

Enforced (check): .github: cd commons/headless && bun run verify — suite/describe.test.ts: the tools of a model are those the tool server serves for the tier and the routes are the paths of the OpenAPI document, drawn by the reach and the audience; suite/describe.test.ts: for any generated program, each model has unique ids, a trace between its elements, the tools and routes of the surfaces for its tier, a command for each visible verb and nothing dropped

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

Written in: headless/src/describe/describe.ts

Tests: passed: suite/describe.test.ts for any generated program, each model has unique ids, a trace between its elements, the to; passed: suite/describe.test.ts the tools of a model are those the tool server serves for the tier and the routes are the

The trace and what is not drawn

FR-008checkpassing

The trace MUST have an edge projects to from each action to its verb, and from each verb to each projection it has; every verb the tier sees MUST trace to a cli-command, and every edge MUST join two elements of the model.

Enforced (check): .github: cd commons/headless && bun run verify — suite/describe.test.ts: the trace goes from the action to the verb to each projection, every visible verb traces to a command, and a verb a tier hides is there with no projection and says why; suite/describe.test.ts: for any generated program, each model has unique ids, a trace between its elements, the tools and routes of the surfaces for its tier, a command for each visible verb and nothing dropped

Proved by: headless/suite/describe.test.ts, tests/commons-headless-describe.test.ts

Written in: headless/src/describe/describe.ts

Tests: passed: suite/describe.test.ts for any generated program, each model has unique ids, a trace between its elements, the to; passed: suite/describe.test.ts the trace goes from the action to the verb to each projection, every visible verb traces t; passed: tests/commons-headless-describe.test.ts Ergonex is described for each tier: the ids are the agreed ones, every verb the tier sees

FR-009checkpassing

A verb the tier may not see MUST have no projection on any surface, and the model MUST say so: the verb's notProjected property lists each surface and why, in the sentence of the gate (tierMessage), and for a verb that the tier sees but a machine surface does not draw it lists the surface and the reason (no reach policy, the channel, a person alone); the dispositions of its tier and audience are unexpressed with that reason.

Enforced (check): .github: cd commons/headless && bun run verify — suite/describe.test.ts: the trace goes from the action to the verb to each projection, every visible verb traces to a command, and a verb a tier hides is there with no projection and says why

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

Written in: headless/src/describe/describe.ts

Tests: passed: suite/describe.test.ts the trace goes from the action to the verb to each projection, every visible verb traces t

FR-010checkpassing

Every annotation of every action, and every annotation of a problem code and an outcome, MUST end in one disposition (commons 0033-kanon FR-005): expressed by the element that enforces it (the command that draws the tier and audience, the tool or route that draws the reach, the option --dry-run, --check or --yes that a preview, a check or a destruction adds), carried as data by the verb, or unexpressed with its reason, so that droppedFindings of Kanon finds nothing in any model.

Enforced (check): .github: cd commons/headless && bun run verify — suite/describe.test.ts: every annotation of every action, problem code and exit status ends in a disposition, so that the check of Kanon finds nothing dropped; suite/describe.test.ts: for any generated program, each model has unique ids, a trace between its elements, the tools and routes of the surfaces for its tier, a command for each visible verb and nothing dropped

Proved by: headless/suite/describe.test.ts, tests/commons-headless-describe.test.ts

Written in: headless/src/describe/describe.ts

Tests: passed: suite/describe.test.ts for any generated program, each model has unique ids, a trace between its elements, the to; passed: suite/describe.test.ts every annotation of every action, problem code and exit status ends in a disposition, so t; passed: tests/commons-headless-describe.test.ts Ergonex is described for each tier: the ids are the agreed ones, every verb the tier sees

FR-011checkpassing

Where an element is written MUST be what the caller says: describe(program, { locate }) asks locate for the source of a subject (the program, a plugin, a verb, a code, an exit status), a closed union, and where it has none the source is the name of the program (or of the plugin that contributed the verb) and the line 1.

Enforced (check): .github: cd commons/headless && bun run verify — suite/describe.test.ts: where an element is written is what the caller says, and the name of the program or of the plugin and the line 1 where it says nothing

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

Written in: headless/src/describe/describe.ts

Tests: passed: suite/describe.test.ts where an element is written is what the caller says, and the name of the program or of the

Acceptance scenarios

  1. Given a program with a report, an operator action and an administrator action, When it is described, Then there is a model for each tier of its ladder, and the model of public has the cli-command of the report and none of the others, per FR-001 and FR-007.
  2. Given a verb whose reach names mcp and rest, When it is described, Then its verb traces to a command, a tool and a route with the ids cli:<program> <verb path>, mcp:<tool name> and rest:GET /v1/<path>, per FR-003, FR-007 and FR-008.
  3. Given a verb hidden from a tier, When the model of that tier is read, Then the verb is there, has no projection, says why in notProjected and has its tier unexpressed, per FR-009.
  4. Given a program composed of a host and a plugin, When it is described, Then the plugin is an element and the verbs it contributed have it as parent, per FR-005.
  5. Given a program with a model problem, When it is described, Then the problem is a finding of the element it is about, per FR-006.
  6. Given any model, When droppedFindings reads it, Then it finds nothing, per FR-010.

Out of scope

  • The pages of the documentation: the layered lens of the documentation generator (commons/docs) reads these models and writes them.
  • The model of a target or of the run log: what a run does is not what a program says.

Edge cases

  • A program with no verb: models with the program, the exit statuses and the generic codes, and no projection, per FR-004 and FR-007.
  • A tier that is not on the ladder: the verb needing it is hidden from every tier, per FR-009.
  • A tool name that two verbs share (a b-c and a-b c both a_b_c): the first is kept and the second is a finding, per FR-006.

Assumptions

  • The ladder of a program is its own (Program.tiers), the default one where it gives none.
  • The tool server and the REST skeleton are generated from the same tree and tier, so the physical layer reads their own functions and does not draw their rules a second time.

Open questions

  • None.

Key entities

  • Model - the program for a caller of one tier, in three layers.
  • Element - one thing a layer says: an action, a verb, an option, a command, a tool, a route.
  • Disposition - how an annotation of an action ends: expressed, carried or unexpressed with its reason.

Success criteria

SC-001success criterion

A documentation generator given describe(program) documents every verb of any headless program, the surfaces that draw it for each tier, and what the tiers hide, with no knowledge of the program.

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

describe/describe, describe/ids, Headless

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