IF Commons GitHub

Kanon

0033Draft

0033-kanon · owner if · domain commons · part of 0003-mizan

The six rules

FR-001reviewno test run

A library that is Kanon MUST be built in three layers, in this order from the top: Governance (what a thing is and what it may do, stated once, in the words of its domain), Logical (the model a program reasons with, made from Governance) and Physical (what carries it out in a place: a dialect, a table, a command, a tool, a route, called a surface where it faces a caller); each unit of the library (a folder, FR-010) MUST be in exactly one layer, except the library's own checking (its tests, tools and examples), which is in none.

Enforced (review): 0033-kanon FR-001 — a reviewer checks that the folders of a library that declares kanon are in the three layers by its table (the check of FR-011 holds the imports)

Cited by: table, kanon/kanon, Headless describes a program

FR-002reviewno test run

Projection, not copying: WHEN a layer needs what the layer above says, it MUST derive it by code (a projection: a function from the elements above to the elements of this layer) and MUST NOT restate it by hand; a lower layer MUST hold no copy of a governance sentence that it cannot trace to its source by FR-003.

Enforced (review): 0033-kanon FR-002 — a reviewer checks that a lower layer derives what the layer above says by code and keeps no copy of it

FR-003reviewno test run

Identity survives as a trace graph: every element of every layer MUST have an id that is stable across builds, and every element of the Logical and Physical layers MUST have at least one trace edge to the element it was projected from; the edges MUST make a graph that is acyclic and runs only from a layer to the one below it, so that from any physical element the governance that says why it exists can be found.

Enforced (review): 0033-kanon FR-003 — a reviewer checks the trace graph of a library's model until the check finds an element with no edge; LayeredModel carries the edges (commons-kanon.test.ts)

Cited by: model

FR-004checkpassing

Imports run one way, with a check: a unit MUST import only units of a layer above its own, and units of its own layer only where its row of the table lists them (Logical may import Governance, Physical may import Logical and Governance, Governance imports no unit of the library, and a surface imports no other surface), and the library MUST pass the import check of @intellectual-frontiers/kanon (FR-012) with no finding that is not held by its baseline.

Enforced (check): .github: bun test ./tests/ — commons-kanon.test.ts: a table and a root give layers/above, layers/around and layers/cycle as data; the library's own tests are in commons/kanon/suite

Proved by: tests/commons-kanon.test.ts

Tests: passed: tests/commons-kanon.test.ts a climb is layers/above and a reach around a unit is layers/around, as data from a table

Cited by: imports, Kanon

FR-005checkpassing

Nothing is silently dropped: each annotation that Governance gives an element (a property of it: its effect, its audience, its retention) MUST end in one of three ways, and the model MUST say which: expressed (a trace edge to the lower element that enforces it), carried (it is passed on as data of a lower element, for a program to read at run time) or unexpressed (it is named, with the reason, as one that no lower layer enforces yet); an annotation with none of the three is a finding, kanon/dropped.

Enforced (check): .github: bun test ./tests/ — commons-kanon.test.ts: an annotation with no trace edge, no carried property and no unexpressed record is kanon/dropped, and is not once it is named

Proved by: tests/commons-kanon.test.ts

Tests: passed: tests/commons-kanon.test.ts an annotation with no end is kanon/dropped, and is not once it is named unexpressed with i

Cited by: account, dropped, Kanon, model, Headless describes a program, Archon

FR-006checkpassing

Extensions use only public surfaces: a unit that extends the library (a model, a dialect, a tool of another package) MUST reach the library only through its package's exports and MUST NOT import a file of it by a relative path or by a path exports does not name; the import check MUST name such an import (layers/relative, layers/private).

Enforced (check): .github: bun test ./tests/ — commons-kanon.test.ts: an import by a relative path or by a path exports does not name is layers/relative or layers/private

Proved by: tests/commons-kanon.test.ts

Tests: passed: tests/commons-kanon.test.ts an extension reaches a library only through exports: a relative import and an import by a

Cited by: imports, Kanon

The vocabulary

FR-007reviewno test run

These terms MUST mean what this requirement says in every specification, ontology and page of commons, and a document that uses one for another thing MUST be corrected:

  • Kanon: the pattern of FR-001 to FR-006, the name of this specification and of the library @intellectual-frontiers/kanon.
  • Layer: one of Governance, Logical, Physical, each with a rank (Governance 1, Logical 2, Physical 3; a higher rank imports a lower).
  • Unit: a folder of a library that is in one layer; a class of units that has instances (a dialect, a surface, a model) is one unit for each of its folders.
  • Element: one thing a layer says (a concept, an action, a table, a command), with a stable id, a kind, a name, a definition, a source and properties.
  • Projection: the derivation of the elements of one layer from those of the layer above (FR-002).
  • Trace edge: the record that one element was made from another, with how (FR-003).
  • Surface: a physical unit that faces a caller: the command line, a tool server, a REST service; a surface imports Logical and Governance and nothing of another surface. FR-030 widens the callers to readers and crawlers.
  • Finding: a sentence about a breach of a rule, with a code (FR-011), a file, a line and a key that a baseline can hold.
  • Table: a library's list of units, each with its layer and what it may import, as data (FR-010).
  • Instance: one of several occurrences of a kind of unit in the Physical layer (a dialect), declared in the table with the unit it is an instance of (instanceOf) and placed in a folder or in a package of its own (FR-019).
  • Host: a library that is Kanon and is extended by packages of its own; extension: a package that extends a host, a dialect (an instance) or a plugin, through the host's public exports only (FR-020).
  • Plugin: an extension that is not an instance of a unit: it adds a noun to the host's one program through the host's public exports and the plugin contract, and may depend on other plugins by declaration (FR-020).
  • Family: the host with its extensions, and the naming rule of their packages, as data of the host's table (<host>-dialect-<tool>, <host>-<noun>, FR-021).
  • Relation: a link between two elements of one layer, with a kind that the model's vocabulary declares; it is not a trace edge, which runs from a layer to the one below (FR-029).
  • Bundle: the Logical model published as files with a manifest of every file and its SHA-256, loaded across a process boundary by a loader that refuses the whole bundle where any file differs (FR-026).
  • Vocabulary: the element kinds, relation kinds and annotation names that a host declares for its model (FR-028).
  • Data module: a typed .ts module of a Governance unit whose exports are data (FR-025).
  • Disposition: how one annotation of Governance ends for one instance (FR-005, FR-022); Matrix: the requirement-by-instance table of the dispositions, as a value and as Markdown and JSON (FR-023).

Enforced (review): 0033-kanon FR-007 — a reviewer checks that the terms are used as the vocabulary says

Cited by: table

The alignment to standards

FR-008reviewno test run

This specification MUST carry the alignment of Kanon's terms to the standards that name something near them (0018-standards-first FR-001), each row saying what the standard is, what it says, how close Kanon's term is (closeMatch, narrowMatch, broadMatch) or that it is unaligned, and MUST be the source of the individuals of the ontology kanon (FR-015). A term for which no standard was found MUST be marked unaligned, never left out, and a standard that could not be verified MUST be marked so.

Kanon termStandard and termRelationVerified
Layer: GovernanceOMG Model Driven Architecture Guide, Revision 2.0 (OMG document ormsc/14-06-01, 2014): the Computation Independent Model (CIM), the view of a system that hides the details of its structure and processingcloseMatch (CIM is business and requirements; Governance is the policy and the facts of a thing, in the words of its domain, so it holds the CIM's concerns and some of the PIM's)document and its adoption in 2014 verified; the wording of the three viewpoints is that of the MDA Guide as commonly cited and was not re-read in this work
Layer: Logicalthe same guide: the Platform Independent Model (PIM)closeMatchas above
Layer: Physicalthe same guide: the Platform Specific Model (PSM)closeMatch (a surface or a dialect is a platform)as above
ProjectionOMG Meta Object Facility Query/View/Transformation (QVT), version 1.3 (formal/16-06-03, June 2016): a transformation of a model into anothercloseMatch (Kanon says that a layer is made from the one above by code; it does not adopt QVT's languages)document and version verified
The three layers as a wholeANSI/X3/SPARC three-schema architecture (1975, interim report of the Study Group on DBMS), published by ISO as ISO/IEC TR 9007:1987 (Concepts and terminology for the conceptual schema and the information base): external, conceptual and internal schemasunaligned for the layers (the external schema is a view for a user, and Kanon's three are not that; the nearest is the conceptual schema to Governance and the internal to Physical); the report is a Type 3 technical report that endorses the three-level architecturethe report and its title verified
Governance, Logical, Physical as the conceptual, logical and physical levels of data modelingno standard names these three levels: it is the practice of data modeling; ANSI/X3/SPARC's three levels are not the same threeunalignedsearched, none found
Trace edgeW3C PROV-O (Recommendation, 2013): prov:Derivation, prov:wasDerivedFromnarrowMatch (an edge is a derivation of an element from an element)in use by commons' own ontologies (0012-ontology)
ElementW3C PROV-O: prov:EntitynarrowMatchas above
FindingW3C SHACL (Recommendation, 2017): sh:ValidationResultcloseMatchthe term is of the Recommendation; its wording was not re-read in this work
Unit, Surface, Tablenone found: a folder of a library and what it may importunalignedsearched, none found
InstanceW3C PROV-O: prov:Entity (an instance is something a host declares and a person or program makes)narrowMatchin use by commons' own ontologies (0012-ontology)
PluginW3C PROV-O: prov:Entity; software plug-in architectures have no standard termnarrowMatch for the entity, the plug-in pattern unalignedsearched, none found
FamilyW3C SKOS (Recommendation, 2009): skos:Collection (a labelled group of concepts)narrowMatchthe term is of the Recommendation; in use by commons' own ontologies
MatrixW3C PROV-O: prov:Entity; the RDF Data Cube vocabulary (W3C Recommendation, 2014, qb:DataSet) is the nearest for a table of observations by dimensionsnarrowMatch to prov:Entity, closeMatch to qb:DataSet, not verifiedthe Data Cube term was not re-read in this work
RelationW3C PROV-O: prov:Entity; for a link between two concepts SKOS has skos:related, which this work did not re-read for the claimnarrowMatch to prov:Entity; skos:related is a candidate, not verifiedprov:Entity in use by commons' own ontologies; the candidate is not verified
BundleW3C PROV-O: prov:Entity; for a set of files with a manifest of digests the candidates are BagIt (RFC 8493) and RO-Crate, which were not read in this worknarrowMatch to prov:Entity; BagIt and RO-Crate are candidates, not verified; no relation is claimed to eithernot verified
Vocabulary, Data modulenone foundunalignedsearched, none found; a Decision of the owner is needed before either is a term of the ontology (OQ-5)
Conformance of a library to KanonISO/IEC/IEEE 42010 (architecture description) describes views and correspondences between thembroadMatch, not verifiednot verified

A correspondence to a standard that is unaligned MUST be recorded by a Decision of the owner (0018-standards-first FR-005) before it is a term of the ontology; the terms of the ontology kanon that this table maps are therefore stated as specializations of PROV-O and SKOS terms, and the unaligned rows above (the five of the layers and units, and the plug-in pattern of Plugin) are open to the owner.

Enforced (review): 0033-kanon FR-008 — a reviewer checks the table of the alignment against the standards; the ontology kanon is made from it (commons-kanon.test.ts reads the layers' viewpoints)

Cited by: kanon/kanon

What conforms

FR-009reviewno test run

Where a library is Kanon, the library's own specifications MUST say which of its folders are in which layer (FR-010), and a library that is not Kanon MUST NOT use the names Governance, Logical and Physical for its folders. The libraries that are Kanon are: commons/data (governance, the logical and physical schemas, with the vault of its secrets as a unit of it), and commons/headless (governance, logical, surfaces), and the libraries planned as Kanon are grc (governance of controls, the logical model, the OSCAL and OCSF forms as physical), integrations, signing and archon (a host: governance of requirements and approval, the order and the plan as logical, the surfaces and the dialect port as physical, with a dialect package for each tool and a plugin package for each noun of its command, FR-019 to FR-021); the libraries that are not Kanon are the single-level utility libraries core, crypto, formats, rdf, system, terminal, telemetry and net. The libraries mizan, ontology, docs, quality, test, githost, libraries, lint and ergonex are not classified by this specification (OQ-3).

Enforced (review): 0033-kanon FR-009 — a reviewer checks which libraries are Kanon until data and headless declare their tables

Cited by: Planning

The table and the check

FR-010checkpassing

A library that is Kanon MUST declare its table in its manifest library.ts, as the optional field kanon (0027-commons-libraries FR-012): package (the package name, which its units import each other by) and units, each with its folder, its layer (or own: true for the library's own checking, which is in no layer and may import any file of the library by a relative path), instances (true where each folder under it is a unit of its own), mayImport (the exact list of the other units it may import, in place of the units of the layers above) and packages (the packages and subpaths it may import by name, where it is restricted); and, only where the library has extensions, family, instances and plugins (FR-019 to FR-021), or, where the package is itself an extension, extends (FR-020); a library that does not declare kanon MUST be read as not Kanon, and the manifest MUST be refused where the field is not of this form or a unit names a layer that is not one of the three.

Enforced (check): .github: bun test ./tests/ — commons-kanon.test.ts: the manifest accepts a kanon table and refuses a unit in a fourth layer or a field of another form

Proved by: tests/commons-kanon.test.ts

Tests: passed: tests/commons-kanon.test.ts the manifest accepts a kanon table, and refuses a unit in a fourth layer or a field of ano

Cited by: Kanon, names, table, pack-commons, Headless layers, Integrations layers, Commons libraries, Distribution, Planning

FR-011checkpassing

The import check MUST find, from a table and a root and with no other input, every import of every file as data (a finding of this form: code, file, line, one sentence and a key) with these codes: layers/unclassified (a file in no unit of the table), layers/relative (a file of another unit imported by a relative path), layers/private (an import of the package by a path its exports does not name), layers/external (an import of a package the unit's row does not allow), layers/above (an import of a unit that stands below it in rank, that is, a climb), layers/around (an import of another unit of its own layer that its row does not list), layers/cycle (units of one class that import each other in a loop), instances/sibling, instances/undeclared, plugins/inverted, plugins/undeclared, plugins/contract and family/name (FR-019 to FR-021), and kanon/dropped (FR-005, FR-022); the codes MUST be a closed union with a sentence for each, and a relative import that leaves the package MUST be layers/relative.

Enforced (check): .github: bun test ./tests/ — commons-kanon.test.ts: every code of the check is found as data from a table and a root

Proved by: tests/commons-kanon.test.ts

Tests: passed: tests/commons-kanon.test.ts a climb is layers/above and a reach around a unit is layers/around, as data from a table; passed: tests/commons-kanon.test.ts each of the other codes is found: unclassified, relative, private, external and cycle

Cited by: imports, Kanon

FR-012checkno test run

The library @intellectual-frontiers/kanon MUST hold the type of the table, the import check (FR-011) lifted from the checks of commons/data/tools/layers.ts and commons/headless/tools/layers.ts, the check of FR-005 and the types-only contract of FR-013, and MUST be a utility library of a single level in the sense of FR-009 that is itself not Kanon where it has fewer than two levels; the check MUST be pure (given the files and the exports map, it returns findings) and MUST NOT read the file system but in the entry host of its package.

Enforced (check): .github: cd commons/kanon && bun run verify — commons/kanon: the verify of the library (its compiler, specification checker, rules, tests and the packing of its package)

Cited by: host, Kanon

FR-013checkpassing

The contract LayeredModel MUST be types only (no value that a program runs but the constants of its kinds and the builders of the ids) and MUST be the shape of the layered model of the documentation generator (0011-documentation FR-029: its layers, elements, trace edges and findings), so that a Kanon library's model is read by that generator as it is: a LayeredModel has layers, elements (each with id, layer, kind, name, definition, optional parent, source with the file and the line, and properties), trace (edges from one element to another, with how) and findings, and adds dispositions (FR-005) and instances (the instances of the model, FR-022), and an element MAY say which instance it belongs to. The kinds MUST be those agreed by Data and Headless: action, verb, option, operand, problem-code and outcome, and the projections cli-command, mcp-tool and rest-route; the ids MUST be headless:<program>/<verb-path>, cli:<program> <verb path>, mcp:<tool_name>, rest:<METHOD> <path>, and, for an option or an operand, the id of its verb followed by #--flag or #<operand>.

Enforced (check): .github: bun test ./tests/ — commons-kanon.test.ts: a LayeredModel is the shape of the layered model of the documentation generator, with the kinds and the id builders agreed

Proved by: tests/commons-kanon.test.ts

Tests: passed: tests/commons-kanon.test.ts a LayeredModel is the shape of the layered model of the documentation generator, with the

Cited by: Kanon, model, Kanon content checks

FR-014checkpassing

A library that declares kanon MUST pass the check (FR-011): its verify script MUST run the check of @intellectual-frontiers/kanon on its own table (kanon/src/check.ts of this repository), and the check of the manifests (0027-commons-libraries FR-013) MUST find a library that declares kanon and whose verify does not run it; and a conformance level (0028-conformance-levels) MAY entail the declaration, in which case the level states it as a requirement of Mizan's ontology and a library that declares that level and no kanon is found by the check of the manifests, which this specification does not yet make of any level (OQ-1).

Enforced (check): .github: bun test ./tests/ — commons-kanon.test.ts: the check of the manifests finds a library that declares kanon and whose verify does not run the check

Proved by: tests/commons-kanon.test.ts

Tests: passed: tests/commons-kanon.test.ts the check of the manifests finds a library that declares kanon and whose verify does not r

Cited by: check, host, Kanon, libraries, Archon

The ontology and what it replaces

FR-015checkpassing

The ontology of commons MUST have a namespace kanon beside ifr, ifccm, ifqs and mizan, with the classes kanon:Layer, kanon:Projection, kanon:Element, kanon:TraceEdge, kanon:Surface, kanon:Finding, kanon:Instance, kanon:Plugin, kanon:Family and kanon:Matrix, the three layers as the members of the code list kanon:Layer each with its rank, its MDA viewpoint (CIM, PIM, PSM) and its level of data modeling (conceptual, logical, physical) as data, and each class MUST have a record of the standard it rests on (0018-standards-first FR-003).

Enforced (check): .github: bun test ./tests/ — commons-kanon.test.ts: the ontology kanon has the ten classes, the three layers with their MDA viewpoints, and a record of the basis of each class

Proved by: tests/commons-kanon.test.ts

Tests: passed: tests/commons-kanon.test.ts the ontology kanon has the twelve classes (ten, and Relation and Bundle), the three layers

Cited by: kanon/kanon

FR-016reviewno test run

This specification MUST supersede, by citation only, the layers text of the first specification of the spec kit of commons/data and of the specifications of the spec kit of commons/headless about their layers, in this sense: where one of them states the three layers, the one-way import, the table or the check, it is an instance of FR-001 to FR-006 and its own text stays, in its own kit, until its owner changes it to cite this specification; no requirement of another library's kit is edited by this specification.

Enforced (review): 0033-kanon FR-016 — a reviewer checks that no requirement of another library's spec kit is edited by this specification

The relation to the ladder

FR-017reviewno test run

The ladder (0016-ladder) and Kanon MUST be kept apart and cross-referenced: the ladder is the rule of a whole harness that a rung relies only on the rungs below it, and Kanon is the same rule applied inside one library (a unit relies only on units of its layer or above), with the two things the ladder does not say, projection (FR-002) and identity (FR-003); the ladder's rung numbers and Kanon's layer ranks MUST NOT be compared. Whether the two are one rule stated twice is OQ-2.

Enforced (review): 0033-kanon FR-017 — a reviewer checks the cross-reference of the ladder and Kanon until the two are unified or kept apart by decision (OQ-2)

Cited by: Planning

The typing discipline

FR-018reviewno test run

A Kanon library SHOULD be typed as an algebra: a closed union for each thing with a fixed set of cases (the layers, the finding codes, the kinds of a unit, the ways an annotation ends), a product type for each record, an identity as a branded type made only by a smart constructor that returns a Result (parse, don't validate), every field readonly, a registry as a typed map with one entry for each case, a port as a typed record of functions, and a pure core with effects at the edge; and the Governance and Logical layers MUST match every union exhaustively (a default that passes the value to absurd, so that a new case fails to compile where it is not handled), MUST NOT throw for a failure that is expected (it is a Result), MUST NOT use any, a non-null assertion or an enum, and MUST hold no effect (no file, no clock, no network: a port is given to it).

Enforced (review): 0033-kanon FR-018 — a reviewer checks the typing of a Kanon library; commons/kanon is the example, and its tests prove its own (0001-kanon-checker FR-009)

Cited by: Kanon checker, Kanon content checks, Planning

Instances, plugins and families

A library that states one thing and carries it out in several places of one kind (a data library with a dialect for each database; a fleet library with a dialect for each convergence tool) needs more than the three layers: the several places are instances of one unit, and each must stay apart from the others. And a library whose command is made of nouns (server, device) needs each noun to be a package that extends the host and that the host never reaches back to.

FR-019checkpassing

A physical layer MAY contain several instances of one kind of unit (dialects). Each instance MUST be declared in the host's table (instances) with a name, the layered unit it is an instance of (instanceOf) and a placement: a folder under that unit (which MUST have instances: true) or a package of its own whose name the family's rule makes (FR-021). An instance MUST import only the layers it extends, through the public exports of the host (FR-006), and MUST NOT import another instance: where it does, the check MUST report instances/sibling, and a folder under a unit whose instances the table declares that no instance names MUST be instances/undeclared. The table MUST be refused where an instance is of no layered unit, is declared twice, or is a folder of a unit that has no instances.

Enforced (check): .github: bun test ./tests/ — commons-kanon.test.ts: an instance that imports another is instances/sibling; the library's own tests are in commons/kanon/suite

Proved by: tests/commons-kanon.test.ts

Tests: passed: tests/commons-kanon.test.ts an instance that imports another instance, and a host that imports its extension, are foun

Cited by: extensions, Kanon, model, table, ansible dialect: layers, apt dialect: layers, Boot plugin: layers, cloud-init dialect: layers, Converge plugin: layers, DNS plugin: layers, Homebrew dialect: layers, mise dialect: layers, Native-pinned layers, opentofu dialect: layers, Archon tool plugin: layers, WinGet dialect: layers, Commons libraries, Archon, Planning

FR-020checkpassing

A plugin MUST be a package that extends one host, declared in the host's table (plugins, each a noun and the nouns of the plugins it dependsOn), and the package MUST declare extends (the host's package) in its own table. A dialect or a plugin MUST reach the host only through the host's public exports (FR-006; layers/private), a dialect only the units its instance's unit may import (the layers above it and the dialect port), a plugin any unit the exports name and the plugin contract where the family has one (FR-021). The host MUST NOT import a package of its family (plugins/inverted, except in its own checking); a plugin MUST NOT import another member of the family but a plugin it declares a dependency on (plugins/undeclared), and a dialect MUST import none; the dependencies among plugins MUST have no loop, and the table MUST be refused where they have one. A package MUST be a host or an extension, never both. A package that extends a host and is not one the host's table declares by the family's rule is family/name.

Enforced (check): .github: bun test ./tests/ — commons-kanon.test.ts: a plugin reaches the host through its exports only (layers/private) and a host that imports its extension is plugins/inverted; commons/kanon/suite

Proved by: tests/commons-kanon.test.ts

Tests: passed: tests/commons-kanon.test.ts an instance that imports another instance, and a host that imports its extension, are foun

Cited by: extensions, Kanon, table, Kanon content checks, Planning

FR-021checkpassing

The naming of a family MUST be data of the host's table (family): a template for the dialects and one for the plugins, each with {host} once and {name} once (<host>-dialect-<tool> and <host>-<noun>), in the host's scope, and optionally contract, the export of the host that says what a plugin is. The package of each member MUST be made from the rule and never written a second time; a dialect MUST be read before a plugin, so that a noun that would read as a dialect is refused; where a contract is named the host MUST export it and each plugin MUST import it (plugins/contract). The manifest of a library of commons MAY carry family (the host's name and the library's role, host, dialect or plugin) and the manifests check MUST hold the two sides together (0027-commons-libraries FR-023).

Enforced (check): .github: bun test ./tests/ — commons-kanon.test.ts: the package of a member is made from the family rule and a noun that reads as a dialect is refused; commons/kanon/suite

Proved by: tests/commons-kanon.test.ts

Tests: passed: tests/commons-kanon.test.ts a family's rule is data: the package of a member is made from it and a noun that reads as

Cited by: extensions, family, Kanon, family, Libraries, Commons libraries, Planning

FR-022checkpassing

WHERE a model has instances, the rule of FR-005 MUST be checked for each instance: every annotation of Governance MUST end, for each instance, expressed, carried or unexpressed with a reason, by a disposition given for that instance or else by one given for no instance (which holds for all); one that ends in none for an instance, whose target is no element of the model or belongs to another instance, that is unexpressed with no reason, or that is given for an instance the model does not have, MUST be kanon/dropped naming the instance.

Enforced (check): .github: bun test ./tests/ — commons-kanon.test.ts: an annotation accounted for in one dialect and not the other is kanon/dropped for the other; commons/kanon/suite

Proved by: kanon/suite/content.test.ts, tests/commons-kanon.test.ts

Tests: passed: suite/content.test.ts a claim whose evidence no instance expresses, carries or declares unexpressed fails with k; passed: tests/commons-kanon.test.ts an annotation accounted for in one dialect and not the other is dropped for the other, and

Cited by: account, dropped, Kanon, model

FR-023checkpassing

A model MUST be able to give the matrix of requirement by instance as a typed value: a row for each annotation of each element of Governance, a cell for each instance, each cell expressed (with its target), carried (with its target), unexpressed (with its reason) or dropped (a finding of FR-022 and no other cell is); the matrix MUST be made from the same reading of the dispositions as the check, so that they cannot disagree, MUST be rendered as a Markdown table and as JSON for the documentation lens, in the order of the model, and MUST be keyed by the ids of the LayeredModel of FR-013, which the lens of 0011-documentation FR-029 reads, so that a page links each row to its element.

Enforced (check): .github: bun test ./tests/ — commons-kanon.test.ts: the matrix is built and rendered as Markdown; commons/kanon/suite holds the JSON and the property test

Proved by: kanon/suite/content.test.ts, tests/commons-kanon.test.ts

Tests: passed: suite/content.test.ts a claim whose evidence no instance expresses, carries or declares unexpressed fails with k; passed: tests/commons-kanon.test.ts an annotation accounted for in one dialect and not the other is dropped for the other, and

Cited by: Kanon, matrix, Planning

FR-024checkpassing

The checking of a library's names MUST be data of the manifests check, not folders: where a host is planned and its libraries are not yet written, the names MUST be reserved by data in the check of the manifests (0027-commons-libraries FR-024), each reservation an exact name or a prefix with the host that may hold it, and a library whose name a reservation holds MUST be refused unless it declares itself of that host's family.

Enforced (check): .github: bun test ./tests/ — commons-kanon.test.ts: the reserved names are refused to a library of no family; commons/libraries/suite/family.test.ts

Proved by: tests/commons-kanon.test.ts

Tests: passed: tests/commons-kanon.test.ts the names held for the fleet libraries are refused to a library of no family, with no fold

Cited by: family, Libraries, ansible dialect: layers, apt dialect: layers, Boot plugin: layers, cloud-init dialect: layers, Converge plugin: layers, DNS plugin: layers, Homebrew dialect: layers, mise dialect: layers, Native-pinned layers, opentofu dialect: layers, Archon tool plugin: layers, WinGet dialect: layers, Archon

FR-025checkpassing

A Governance unit MAY be typed data modules and not only code: .ts modules whose exports are data (pages, claims, records with their annotations) and that import nothing of the library's other units (FR-004), so that Governance is stated once, in the words of its domain, as values a program reads. The check reads .ts files only (kanon 0001-kanon-checker FR-007); data in another format MUST NOT be the only form of a Governance unit, because the import check cannot see it, and a host that keeps such data reads it through a typed .ts module of the unit.

Enforced (check): .github: bun test ./tests/ — commons/kanon/suite/content.test.ts: a governance unit of data modules that imports a logical unit is layers/above

Proved by: kanon/suite/content.test.ts

Tests: passed: suite/content.test.ts a governance unit of data modules that imports a logical unit is layers/above

Cited by: Intellectual Frontiers Commons, Kanon content checks

FR-026checkno test run

A Kanon library MAY publish its Logical model as a bundle: a set of files and a manifest, with these rules. The serialization MUST be deterministic (the same model gives the same bytes: a fixed order of elements, trace edges, relations and dispositions, a fixed order of keys, LF line ends, one final newline) and MUST keep the element ids and the trace edges as the model has them. The manifest MUST list every file of the bundle with its path (relative, with no .. and no leading /), its SHA-256 as lower-case hexadecimal of its bytes and its size in bytes, and MUST NOT list itself. A loader MUST be pure over the bytes it is given (no file, no network, no clock), MUST check the whole bundle before it returns any of it, and MUST refuse the whole bundle where any file differs from the manifest, is missing from the disk or the listing, or is not listed (a file changed, missing or extra), naming each fault and none other than the faults it found; a manifest that is itself not valid (a bad digest, a path that leaves the bundle, a path listed twice) MUST be refused the same way. The loader MUST run no module and evaluate nothing of the bundle, and after a pass what it returns is the verified bytes and the data decoded from them, so that nothing is read from the place afterwards. The shape and the loader are Kanon's and import no library above Kanon: the verification of a manifest is the design of 0011-grc-bundles of the library grc (the same layer as Kanon in 0032-libraries-by-concern, so not importable), made again on core and crypto and without the ledger and the signature, which are not in this requirement. The manifest is not signed in this version (decided by the owner on 2026-11-22): the SHA-256 manifest is the whole of the check, and a signature, optionally a DSSE envelope over the manifest as the library crypto already provides, may be added later as an optional field without changing the rules above.

Enforced (check): .github: bun test ./tests/ — commons/kanon/suite/content.test.ts: the bundle is the same bytes twice, loads whole and is refused whole with each fault named

Cited by: bundle, Kanon, Kanon content checks

FR-027checkpassing

A host MAY let a package of another scope be a member of its family: the family of its table takes scope, own (the default, the behavior of FR-021: a member is of the host's scope) or any. Where it is any, the package of a member in another scope MUST declare extends (the host's package) and its own role (a dialect with its name and the unit it is an instance of, or a plugin with its noun) in its own table, MUST run the check of Kanon in its own verify, and the host's naming rule MUST apply to the base name of the package in the extension's own scope; the host MUST NOT name a consumer, MUST NOT import one (plugins/inverted still holds) and is not told of one. The role of an extension of the host's own scope still comes from the host's table. A consumer is not a library of commons: its table is read from a manifest of its own, kanon.ts exporting kanon in the form of FR-010, with no library.ts and no conformance level.

Enforced (check): .github: bun test ./tests/ — commons/kanon/suite/content.test.ts: a package of another scope is a member where the family takes any scope, with its role in its own table

Proved by: kanon/suite/content.test.ts

Tests: passed: suite/content.test.ts a package of another scope is a member where the host's family takes any scope and is not

Cited by: extensions, host, table, Kanon content checks

FR-028checkno test run

A model MAY carry a vocabulary that its host declares (vocabulary): the kinds of element it holds, the kinds of relation (FR-029) and the names of the annotations of Governance. Where a model has a vocabulary, an element whose kind is not one the vocabulary lists for its layer, a relation whose kind it does not list and an annotation whose name it does not list MUST each be a finding (kanon/kind, kanon/kind and kanon/annotation); where it has none, no kind and no name is checked and the model is as it was. The kinds of the vocabulary are data of the host, never a closed union of Kanon: the agreed kinds of FR-013 are those of Headless and stay a list the host may include.

Enforced (check): .github: bun test ./tests/ — commons/kanon/suite/content.test.ts: with a vocabulary, a kind or a name it does not list is a finding; without one nothing is checked

Cited by: Kanon, model, vocabulary, Kanon content checks

FR-029checkno test run

A model MAY have relations (relations): a link between two elements of one layer with a kind from the vocabulary of FR-028, that may be cyclic and is never a trace edge (FR-003). The check MUST find a relation with an end that is no element of the model (kanon/dangling), a relation between two layers (kanon/relation-layer) and two elements with one id (kanon/duplicate-id, which holds for every model, with or without relations). What a host calls an orphan, a broken external link or a chain of redirects is the host's, not Kanon's.

Enforced (check): .github: bun test ./tests/ — commons/kanon/suite/content.test.ts: dangling, relation-layer and duplicate-id are found and a cycle is not

Cited by: Kanon, model, vocabulary, Kanon content checks

FR-030checkpassing

A surface MAY face a reader or a crawler as well as a program: a web page, a feed, a file of text for a model, a document of linked data, later a message, a printed page, a slide. Three things MUST be kept apart: a surface, a kind of unit of the Physical layer (FR-007); an instance, one occurrence of it that the host declares for one rendition (FR-019), which every annotation of Governance is accounted for (FR-022); and a generated artifact, a file that an instance writes from the model, which is never a source and never an element of Governance. A surface MAY write generated artifacts and MUST NOT be read back as the model.

Enforced (check): .github: bun test ./tests/ — commons/kanon/suite/content.test.ts: the content claim with a third instance and no disposition is kanon/dropped and a dropped cell of the matrix

Proved by: kanon/suite/content.test.ts

Tests: passed: suite/content.test.ts a claim whose evidence no instance expresses, carries or declares unexpressed fails with k

FR-031checkpassing

The ontology kanon MUST also have the classes kanon:Relation and kanon:Bundle, each a specialization of prov:Entity with a record of its basis (0018-standards-first FR-003), and the properties kanon:relationKind, kanon:relationFrom and kanon:relationTo; FR-015's ten classes are therefore twelve. The alignment of FR-008 gains the rows below, and a standard not read in this work MUST be marked not verified.

Enforced (check): .github: bun test ./tests/ — commons-kanon.test.ts: the ontology kanon has the twelve classes, Relation and Bundle with their basis

Proved by: tests/commons-kanon.test.ts

Tests: passed: tests/commons-kanon.test.ts the ontology kanon has the twelve classes (ten, and Relation and Bundle), the three layers

FR-032noneno test run

This specification MUST record, without deciding them, that docs is not classified (OQ-3): it reads LayeredModel and MAY later be a consumer or an instance of a content host once a web instance exists; and that a consumer's own ladder (0016-ladder) and Kanon's layers are kept apart as 0033-kanon FR-017 says: a consumer's rungs rank its whole harness, the layers rank the units inside one library or one body of content, a rung is never a layer, and the two are cross-referenced where a consumer's table names the rung its units stand on, never unified (OQ-2).

Enforced (none): a recorded paragraph, nothing to run: a paragraph of this specification records that docs is not classified and how a consumer's ladder and the layers are kept apart

FR-033checkpassing

The names content and content-* MUST be held as data of the check of the manifests, for the host content, until the library of Kanon for content exists (FR-024; 0027-commons-libraries FR-024). The package of an instance of that host is named {host}-rendition-{name}: a template of FR-021 needs only {host} and {name} once each, so the word dialect is in the name of the field of the rule and in this vocabulary's term for an instance, never required in a package name.

Enforced (check): .github: bun test ./tests/ — commons/libraries/suite/family.test.ts: content and content-* are refused to a library of no family

Proved by: libraries/suite/family.test.ts

Tests: passed: suite/family.test.ts the names held are data, and a library of the family may hold them and no other

Cited by: Intellectual Frontiers Commons, Kanon content checks

Acceptance scenarios

  1. Given a library whose logical unit imports a file of a physical unit by a relative path, When the check runs, Then it reports layers/relative naming the file and the line, per FR-004 and FR-011.
  2. Given a governance unit that imports a logical unit by the package's name, When the check runs, Then it reports layers/above, per FR-004 and FR-011.
  3. Given a model whose governance element has an annotation that no trace edge, no carried property and no unexpressed record names, When the model is checked, Then it reports kanon/dropped naming the element and the annotation, per FR-005.
  4. Given the same annotation named as unexpressed with its reason, When the model is checked, Then there is no finding, per FR-005.
  5. Given a manifest that declares kanon with a unit in a fourth layer, When the manifest is read, Then it is refused, per FR-010.
  6. Given a library that declares kanon and a verify that does not run the check, When the manifests are checked, Then the check finds it, per FR-014.
  7. Given a LayeredModel of a Kanon library, When the documentation generator reads it, Then it reads it as its own layered model, per FR-013.
  8. Given the ontology of commons, When it is read, Then it has the namespace kanon with the ten classes and the three layers with their MDA viewpoints, per FR-015.
  9. Given an extension that imports a file of a library by a path its exports does not name, When the check runs, Then it reports layers/private, per FR-006 and FR-011.
  10. Given a cycle of imports among the models of a library, When the check runs, Then it reports layers/cycle once, at the import that closes it, per FR-011.
  11. Given a union of finding codes to which a code is added and a match that does not handle it, When the library is compiled, Then the compiler fails, per FR-018.
  1. Given a host that declares two dialects by package, When one dialect imports the other, Then the check reports instances/sibling, per FR-019.
  2. Given a plugin that imports a plugin it declares no dependency on, When the check runs, Then it reports plugins/undeclared, and with the dependency declared no finding, per FR-020.
  3. Given a host whose file imports a package of its own family, When the check runs, Then it reports plugins/inverted, per FR-020.
  4. Given a plugin that imports the host by a path its exports does not name, When the check runs, Then it reports layers/private, per FR-020.
  5. Given a family rule and a plugin noun that would read as a dialect, When the table is read, Then it is refused, per FR-021.
  6. Given a model with two dialects and an annotation that only one accounts for, When the model is checked, Then kanon/dropped names the other dialect, per FR-022.
  7. Given that model made complete, When the matrix is built and rendered, Then each annotation has a cell for each dialect and the Markdown and the JSON say the same, per FR-023.
  8. Given a library named archon-dialect-x that declares no family, When the manifests are checked, Then the check finds it, per FR-024.
  9. Given a package of another scope that declares extends and its role as a dialect in its own table, and a host whose family has scope: any, When the package is classified, Then it is a member; When the host's family has scope: own, Then it is not, per FR-027.
  10. Given a model with a relation whose target is no element, When it is checked, Then kanon/dangling names the relation; Given two elements with one id, Then kanon/duplicate-id names the id, per FR-029.
  11. Given a claim with an annotation evidence, and the instances web and llms, where web expresses it as a citation and llms carries it as data, When a third instance has no disposition for it, Then kanon/dropped names that instance and the matrix shows the cell as dropped, per FR-022, FR-023 and FR-030.
  12. Given a bundle in which one file has changed, one is missing and one is extra, When it is verified, Then the whole bundle is refused, each fault is named and nothing is run, per FR-026.
  13. Given a Governance unit of data modules that imports a Logical unit, When the check runs, Then it reports layers/above, per FR-025.
  14. Given a model with a vocabulary and an element of a kind the vocabulary does not list, When it is checked, Then kanon/kind names the element, per FR-028.
  15. Given the names content and content-web, When the manifests are checked and no library declares the family of content, Then a library of either name is refused, per FR-033.

Out of scope

  • Moving the copies of the check that commons/data and commons/headless keep: they switch to the library later (see the migration note below), and each stays in force until then.
  • Renaming or editing the constitution of a company or a harness: the article is drafted in the appendix for the owner to decide.
  • Clearing the name Kanon as a trademark in any jurisdiction: see OQ-4.
  • Any commons library that is not named in FR-009.
  • The code of any host (archon and its dialects and plugins are written by their owners); what this specification gives is the table, the checks and the matrix they declare and are held to.

Edge cases

  • A library with two levels that is nevertheless a utility (system: files and processes): it is not Kanon, per FR-009, and has no table.
  • A surface with no unit of its own in the table: layers/unclassified, per FR-011, so that a surface cannot appear without saying what it may import.
  • A unit of a class with instances (a surface, a model) that imports another instance of its class: allowed only where its row lists the class, and a loop of them is layers/cycle, per FR-011; where the table declares the instances (a dialect, FR-019) the import is instances/sibling whatever the row lists.
  • A library with an annotation that nothing yet enforces: it is named unexpressed, with a reason, and the check passes; it is a finding when it is not named, per FR-005.
  • The name Kanon found, inside this repository's ontology, to clash with a term: Strata is the fallback; no such clash was found when this specification was written (the repository was searched for kanon and strata in its ontologies, specifications and code). (FR-007)
  • An instance of package placement is checked in its own package, beside the host's folder (the host is found by the package name of extends); an instance of folder placement is checked with the host's files, and a relative import between two such folders is layers/relative as before, per FR-019.
  • A plugin and a dialect that are both of the family and import each other by name: found from the side of the importer, plugins/undeclared, and never allowed by a declared dependency, which names plugins only, per FR-020.
  • A model with no instances: the rule of FR-005 is as it was, and its matrix has no columns, per FR-022 and FR-023.

Migration note for the libraries that keep their own check

commons/data and commons/headless switch when their owners choose: replace the UnitClass, FOLDERS, MAY_IMPORT, LEVEL, OWN and STRICT values of tools/layers.ts by a table in library.ts (kanon, FR-010), delete layerFindings and specifiersOf and call findings of @intellectual-frontiers/kanon/host from tools/check.ts (it reads the manifest's table and the folder), keep the findings' keys (they are the same: layers/<code> <file> <about>) so that trace.baseline.txt stays valid, and add @intellectual-frontiers/kanon to devDependencies.

Assumptions

  • The three layers are enough for every library of commons that is Kanon: Headless's surfaces and Data's dialects are Physical.
  • A single rank per layer is enough to say a climb from a reach-around, as the two existing checks do with a level per class.

Open questions

OQ-1open question

Whether a conformance level (0028-conformance-levels) requires kanon of a library, and which.

OQ-2open question

Whether the ladder (0016-ladder) and Kanon are one rule, and what the one specification would be; the two are cross-referenced and not unified.

OQ-3open question

Which of mizan, ontology, docs, quality, test, githost, libraries, lint and ergonex are Kanon.

OQ-4open question

(decided by the owner on 2026-11-22: the name is kept): The name Kanon is kept. The names kanon on npm, PyPI and crates.io are held by unrelated projects (a proof-of-concept static site generator, a history-of-astronomy library and a Gemini server), which does not block this library: its packages are scoped (@intellectual-frontiers/commons/kanon). No proper trademark search was possible from this repository: a web search found one KANON record (a Madrid designation in classes 6, 7 and 37) and near-homophones in software classes (KAON), and the name sounds like CANON; none of it settles whether a software mark exists. Before the name is used as an external product name, a trademark attorney or a search of the USPTO's database should check classes 9, 35 and 42. The fallback stays Strata (taken on npm, PyPI and crates.io, which scoped packages tolerate too), and the change would be the name in this specification, the ontology namespace and the library, with no alias kept. The decision is recorded in commons/spec-kit/audits/2026-11-kanon-decisions.md.

OQ-5open question

(the two terms decided by the owner on 2026-11-22; the rest open): The unaligned rows of the alignment table need Decisions of the owner (0018-standards-first FR-005). The owner accepted Vocabulary and Data module as commons' own terms; the Decision records are written in commons/spec-kit/audits/2026-11-kanon-decisions.md for the owner to sign. The MDA wording and the SHACL and 42010 rows still need verifying against the documents themselves.

Key entities

  • Kanon - the pattern: three layers, projection, a trace graph, one-way imports, nothing dropped, public surfaces only.
  • Layer, Unit, Element, Projection, Trace edge, Surface, Finding, Table - as FR-007.
  • LayeredModel - the types-only contract of a Kanon library's model.

Success criteria

SC-001success criterion

A Kanon library's table is data in its manifest, and the check that holds its imports is the one in @intellectual-frontiers/kanon, with no copy in the library.

SC-002success criterion

From any element of a Physical layer a reader can follow the trace edges up to the Governance element that says why it is there, and no annotation of Governance is missing from the model's account.

Appendix: the constitution article (a draft, for the owner to decide)

No constitution document is edited by this specification. The article that a constitution might carry, if the owner adopts the pattern:

> Article: Kanon. A library of ours that states a thing once and carries it out in more than one place is built to Kanon: Governance says what the thing is and what it may do; Logical is made from Governance by code, never copied; Physical is made from Logical by code, in each place it is carried out. Every element keeps its identity from the layer above, so that what was said can be found where it is carried out; imports run from a layer to the layers above it only, and a machine checks that they do; no annotation of Governance is dropped without being named; and whatever extends the library reaches it through its public surface alone. One rule, projected down, nothing lost.

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

account, bundle, check, dropped, extensions, family, host, imports, Kanon, matrix, model, names, table, vocabulary, family, generate-ontology, Libraries, libraries, pack-commons, Ontology, kanon/kanon, kanon/mod, Intellectual Frontiers Commons, Kanon, ansible dialect: layers, AnyFS: layers, AnyfsPosix layers, apt dialect: layers, Archon layers, Assessment layers, Boot plugin: layers, Catalog Nist Csf 2 layers, Catalog Nist Sp800 layers, Catalog Soc2 layers, Change Control layers, cloud-init dialect: layers, Converge plugin: layers, DNS plugin: layers, Estate Endpoints layers, Estate Iac layers, Estate: layers, Estate Query layers, Evidence Capture layers, Findings layers, Gate layers, Headless layers, Homebrew dialect: layers, Integrations Identity layers, Integrations layers, Kanon checker, Lab layers, Linux Observe layers, Linux Services layers, Machine Probe layers, mise dialect: layers, Native-pinned layers, Netboot layers, opentofu dialect: layers, Pentest layers, Planning layers, Planning Query layers, Posture Report layers, Repoctl layers, Scanners layers, Tenancy layers, Archon tool plugin: layers, Toolchain layers, WinGet dialect: layers, Kanon content checks, Headless describes a program, Commons libraries, Archon, Distribution, Planning

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