IF Commons GitHub

Libraries

0001Draft

0001-libraries · owner if · domain commons

The libraries of a repository

FR-001checkno test run

A library MUST be a folder commons/<name>/ with a manifest library.ts that is an object literal read as data and never run, naming the library, its conformance level, its spec kit, its verify command, its version, its exports and where it is published; the library MUST give the decoder of that manifest and the check that the manifest and its folder agree (the name of the folder is the package's name, the version is the package's and the record's, the exports are the package's, a registry of distribution is one of the two kinds), as commons 0027-commons-libraries FR-011 to FR-018 require.

Enforced (check): .github: cd commons/libraries && bun test suite/ — libraries.test.ts: the manifest is read as data and never run, an unknown field and a second export are refused, and the check names where the manifest and its folder disagree

Cited by: libraries

FR-002checkno test run

The library MUST make, from the manifests, the section "The libraries" of commons 0027-commons-libraries (one requirement for each library, numbered from FR-101 for the life of the library) and the rows of those requirements in enforcement.tsv, and MUST fail with --check where either is not what the manifests make (commons 0027-commons-libraries FR-011).

Enforced (check): .github: cd commons/libraries && bun test suite/ — libraries.test.ts: the section of the libraries and the rows of enforcement.tsv are what the manifests make, and --check names the file that is not

FR-003checkno test run

The library MUST say which libraries a change affects: from the files of a change (since a revision, or named) it MUST give the libraries whose folder, or whose dependencies (the link:, file: and workspace: entries of package.json and the packages their imports reach through exports), changed, as a matrix a workflow reads, and for a library the folders and files it reads, one a line (commons 0027-commons-libraries FR-019 to FR-022).

Enforced (check): .github: cd commons/libraries && bun test suite/ — affected.test.ts: the libraries a change affects by folder and by dependency, the inputs of a library, and the matrix a workflow reads

Cited by: affected

The workflows

FR-004checkno test run

The library MUST model a workflow of GitHub Actions as typed values (the triggers, the jobs, the steps, the strategy, the permissions, the concurrency and the composite action), give validateWorkflow and validateAction (an action with no version, a job that needs a job that is not there, a step of no script) and render the YAML of a workflow and of an action as the same bytes for the same values, each beginning with a line that says it is generated and by what (commons 0030-generated-workflows FR-002 to FR-006).

Enforced (check): .github: cd commons/libraries && bun test suite/ — workflows.test.ts: the typed model, its validation findings and the rendering of the YAML, the same bytes for the same values

Cited by: Libraries, workflows/definitions, workflows/model, workflows/render

FR-005checkno test run

The library MUST make, with one command, the files .github/workflows/<name>.auto.yml and .github/actions/bun/action.yml of a repository from the manifests of its libraries and the facts of their CI, MUST fail with --check where a file is not what the model makes, where a workflow is written by hand or where a library that is published to npm has no tools/pack.ts for its publish workflow to run, and MUST make the publish workflow of such a library idempotent: it checks the tag is the version, proves and packs the library, sends the tarball to the registries its manifest names unless the version is already there, and makes the tag of the version (commons 0030-generated-workflows FR-001, FR-004, FR-007 to FR-009).

Enforced (check): .github: cd commons/libraries && bun test suite/ — workflows.test.ts: the generator makes the files, finds a hand-written workflow and a missing packer, and the publish workflow tags a version that is already on the registry

Cited by: generate-workflows, Libraries

FR-006checkno test run

The library MUST read the pins of commons (commons/generated/pins.auto.env) and install the pinned Bun on a runner: the release asset of the platform fetched with retries, kept only where its SHA-256 is the pinned one, unpacked by the zip reader of formats and put on the PATH, on Linux, macOS and Windows, with no shell script, no Python and no unzip (commons 0005-typescript-practice FR-026).

Enforced (check): .github: cd commons/libraries && bun test suite/ — pins.test.ts: the pins of an env file and the release asset of each platform; the installer is run by the workflows of this repository

Cited by: pins

The package

FR-007checkno test run

The library MUST give the packer of a library: from the manifest and the sources it builds the compiled modules and their declarations with the TypeScript 7 compiler, writes the package.json that is published (each entry with types, the source for Bun and the compiled file for the rest), inspects the package and packs it into dist/<scope>-<name>-<version>.tgz, and MUST fail where an export has no types condition or no .d.ts in the tarball, where a declaration imports a module that is neither in the tarball nor among the package's dependencies, or where a declaration names a node: module and the package has no peer of @types/node (commons 0032-libraries-by-concern FR-005 and FR-013).

Enforced (check): .github: cd commons/libraries && bun run verify — the package is built, inspected and packed by tools/pack.ts; tests/release/commons-packages.test.ts packs every library of npm, refuses one with no declaration for an export and type-checks a consumer

Cited by: Libraries, pack-library

FR-008checkno test run

The library MUST give the commands that hold a whole repository to Mizan, each reading every manifest, ontology and specification they need: check (a spec kit held to a conformance level, and with --all the verify of every library), changes (the change requests of a range and the rules of change control), versions (the records of the works and their versions, the tag and the ledger), newer (the standards that are newer than their pins), oscal-register (the register of requirements and proofs as OSCAL, current or not) and the generators of the ontologies of commons (their Turtle, OWL, RDF/XML, SHACL, JSON Schema, SSSOM, SKOS, SQL and HTML) (commons 0003-mizan, commons 0018-standards-first, commons 0020-ifccm, commons 0026-works-versioning, commons 0028-conformance-levels and 0012-ontology).

Enforced (check): .github: cd commons/mizan && bun test suite/ — mizan.test.ts, mizan-levels.test.ts, mizan-changes-git.test.ts and versions-git.test.ts, and in libraries mizan-oscal-register.test.ts and mizan-newer.test.ts: each command run on real folders and repositories

Written in: libraries/src/release-run.ts, libraries/tools/changes.ts

Cited by: changes, check, generate-ontology, newer, oscal-register, publish-ontology, versions

FR-009checkno test run

The library MUST keep the importers of standards, each a module that fetches or reads a standard at a pinned address and writes the typed module and the provenance of what it read, with --check for whether what is committed is what the standard gives (commons 0019-mizan-integrations).

Enforced (check): .github: cd commons/libraries && bun test suite/ — mizan-nist-import.test.ts: the committed module names the controls the specifications cite with the titles of the pinned catalog, and the offline check passes

FR-010checkno test run

The library MUST be published to npm as compiled modules with their declarations, one entry for the package and one for each tool above, and each of its commands MUST run as bun commons/libraries/src/<command>.ts in this repository.

Enforced (check): .github: cd commons/libraries && bun run verify — the package is built, inspected and packed by tools/pack.ts; the commands run as bun commons/libraries/src/<command>.ts in the workflows of this repository

Cited by: Libraries

The development loop, the plan of CI and the release

FR-011checkpassing

The library MUST give a development loop, one command (bun run dev:check at the root), that finds the libraries the working tree changes since a revision (origin/main by default, the files not yet committed included) or that are named, and the libraries whose own sources import them, from the same planner as affected with the narrower reach of a library's own code (its folder and the packages its about.ts and src/ import); that links the libraries of the repository under commons/node_modules so that a library imports another by its package name and reads the checkout's source, installs the packages that the root shares once and those a library has of its own; that type-checks each affected library with TypeScript 7, several at a time, and runs the tests of each in a bun test process of its own, several at a time; and that prints a short summary in the marks and colours of the terminal library (what it looked at, one line for each stage, what failed under it) and exits 1 where a stage failed. It MUST prove less than verify and say so, and never be the release.

Enforced (check): .github: cd commons/libraries && bun test suite/ — dev.test.ts: the counts and failures read from bun test, the packages a library installs itself, the libraries linked by name, what each scope affects, the summary, and a real run with a type error and a failing test

Tests: passed: suite/dev.test.ts a fresh checkout, with no link under commons/node_modules and only the root's packages ins; passed: suite/dev.test.ts a library installs only what the root does not share: a link is a library, a package the r; passed: suite/dev.test.ts a real run on real files: the libraries a file affects are type-checked and tested, a type; passed: suite/dev.test.ts a scope affects the libraries of what it names: a file, a library and the libraries whose ; passed: suite/dev.test.ts every package of commons is linked under commons/node_modules by its name, commons/commons and 2 more

Cited by: dev, Libraries, link, Commons libraries

FR-012checkpassing

The library MUST give the plan of CI, plan.ts: from the same planner (the reach of verify: what a library's verify reads and what depends on it) and the record of CI of each library, the cells of a matrix on Linux, one for each library affected, and the cells of a matrix on the systems besides Linux, one for each affected library whose record names one, as the outputs of a step a workflow reads; and the one workflow ci of this repository MUST be made from it (commons 0030-generated-workflows FR-006, FR-007), so that a push or a pull request runs verify and the tests on Node 26 for the libraries it affects, on Windows and macOS only for the libraries that have code of their own for them, and nothing else. The packing that verify ends with MUST be checked in a push only for the libraries that changed their exports since the base (a new library included) or where the packer changed, and in every cell of a run of everything; the release packs every library.

Enforced (check): .github: cd commons/libraries && bun test suite/ — plan.test.ts: the cells on Linux and on the systems a library's record names, the outputs of a step, the command on this repository, and the one workflow ci

Tests: passed: suite/plan.test.ts every affected library has a cell on Linux, and one on each system its record of CI names;; passed: suite/plan.test.ts the command plans this repository: the libraries a file affects with the reach of verify, ; passed: suite/plan.test.ts the one workflow ci plans, runs the matrices the plan writes and gives one result, and no ; passed: suite/plan.test.ts the packing is checked in the cells of the libraries that changed their exports or where t

Cited by: dev, Libraries, plan, Generated workflows

FR-013checkpassing

The library MUST give the one command of the release, releasing.ts (bun run release at the root), whose plan writes nothing and says what a release does and whose apply does it. In single distribution mode (commons 0036-distribution FR-019) the release is one release of the package commons, with the tag commons-v<version>, raised by the greatest Impact: of the commits that touched any library since its last tag and by the floor of FR-027 read from the keys of the single package's exports (commons 0036-distribution FR-027), and the library versions are not raised; in per-library mode (--distribution per-library or IFC_DISTRIBUTION) the rules below apply to each library, and are those of commons 0026-works-versioning FR-041: from the tags of each library and its files since its last tag (its folder and the paths its record adds) a library MUST be raised by the greatest of the Impact: of its commits since the tag (a patch where none states one) and the floor of FR-027, a breaking impact (major) raising the minor while the major version is 0 (SemVer 2.0.0 item 4) and the major from 1.0.0, a library that imports a library that is raised MUST be raised by at least a patch, a version that has no tag, or is ahead of its tag, MUST be released as it is only where npm does not hold it or holds it with the same files (the sources the package carries by their SHA-256, and the keys of its exports), and MUST be raised like a changed library where npm holds it with other files, or, where npm cannot be asked (--offline, or no answer), where files changed since the commit that raised its version; --raise NAME[=IMPACT] MUST raise a library whatever its state says, and plan MUST say for each library whether it is released as it is, raised, left alone or not released, and why (FR-026), a version tagged and unchanged MUST be left alone, a version below its last tag and a cycle of imports MUST be errors, and the steps MUST be in the order of the imports. A library with no record of its own is released by its manifest and its package.

Enforced (check): .github: cd commons/libraries && bun test suite/ — releasing.test.ts: each rule of the plan on facts, a breaking impact raising the minor while the major version is 0, and on a real repository with tags and commits

Tests: passed: suite/releasing.test.ts on a real repository of tags and commits: the plan reads the tags, the files since each an; passed: suite/releasing.test.ts --raise raises a library whatever its state says, by an impact or by its commits', refuses; passed: suite/releasing.test.ts a library changed since its tag is raised by its impact, one that imports it by a patch an; passed: suite/releasing.test.ts a tarball is read for the hash of each file and its package.json, and its sources are comp; passed: suite/releasing.test.ts a version that is below its last tag, in a real repository, stops the plan with the exit s and 1 more

Cited by: Libraries, releasing, How works are versioned, Libraries by concern, Distribution

FR-014checkpassing

apply MUST write the new version into the record, the manifest and the package of each library it raises (in single mode, of commons/commons), then refresh the lockfile of every library it releases (an install in its folder that may change the lockfile, never a frozen one), then make the generated files once (the section of the libraries, the packaging tables, the ontologies, the workflows and the register) and run repoctl sync, then run the tests that pack, install and type-check a consumer (tests/release/commons-package.test.ts for the one package of single mode, commons-packages.test.ts for every library in per-library mode) unless it is told not to, and write the record commons/generated/release.auto.json (the libraries to publish and tag, in order, with no day and no person), so that a version change never leaves a stale lockfile or a stale generated file for the tests to find; it MUST NOT publish, tag or commit; matrix MUST read the record and give the workflow what is not tagged yet.

Enforced (check): .github: cd commons/libraries && bun test suite/ — releasing.test.ts: apply refreshes the lockfiles, makes the generated files once, synchronizes, runs the proof last and writes the record, and publishes and tags nothing; release-lockfile.test.ts: on a real repository with a stale lockfile the gate passes after apply and fails without the refresh; matrix leaves out what is tagged

Tests: passed: suite/release-lockfile.test.ts apply refreshes the lockfile of each library it releases before the gate that installs it ; passed: suite/releasing.test.ts on a real repository of tags and commits: the plan reads the tags, the files since each an; passed: suite/releasing.test.ts the record is the plan in order with no day and no person, it reads back, the matrix leave

Cited by: Generated workflows

FR-015checkpassing

The library MUST make, with the generator of its workflows, the one release workflow release.auto.yml (commons 0030-generated-workflows FR-009): run by hand from main, it plans from the record, proves and packs each library in a matrix, and, only where asked to publish, sends the tarballs in the order of the record to npm (trusted publishing with provenance, or the secret INFRO_NPMJS_TOKEN where the repository has it) and to the GitHub package registry, skipping a version a registry has, and makes the tags with the runner's token.

Enforced (check): .github: cd commons/libraries && bun test suite/ — workflows.test.ts: the release workflow is by hand from main, in the order of the record, with provenance and the token only where there is one

Tests: passed: suite/releasing.test.ts a release is published and tagged by itself: a version already on npm is not sent again an

Cited by: Libraries, releasing, How works are versioned, Libraries by concern, Distribution

Families and reserved names

FR-016checkpassing

The decoder of the manifest MUST read the optional field family (a host, a library name, and a role of host, dialect or plugin), and the check of the manifests MUST find, as one sentence each: a library whose name a reservation holds and whose family is not the host the reservation names (the reservations are data of the library, an exact name or a prefix with the host that may hold it, and hold archon, archon-*, signing, gitops and estate, with no folder); a host that is not named as its family; a dialect or plugin whose host is not a library that declares role host and a kanon table; a name the host's family rule does not read as its role; a member the host's table does not declare, and a member the host's table declares that no library declares; a member whose kanon table does not extend the host; and a library whose name the family rule of a host reads as a member and that declares no family.

Enforced (check): .github: cd commons/libraries && bun test suite/ — family.test.ts: the family field is decoded, the reserved names are found as data with no folder, and each side of a family held against the host's table is found

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; passed: suite/family.test.ts a host, a dialect and a plugin of one family that declare each other have no finding; passed: suite/family.test.ts a manifest's family is decoded and refused where it is not a host and a role; passed: suite/family.test.ts a member whose table does not extend the host, a host that is not a host and a member with; passed: suite/family.test.ts a name the host's rule does not read as the role, a member nobody declared and a declared

Cited by: family

The map of the libraries in the README

FR-017checkpassing

The library MUST make, from the manifests and the summary of each library's about.ts (read as data, no library run), the table of the libraries in the root README.md between the markers <!-- libraries-map:begin --> and <!-- libraries-map:end --> (readme.ts, exported as ./readme): one row for each library, sorted by role (foundation, pattern, program, standard) and then by name, with the package (linked to npm where it is published there), the first clause of the first sentence of its summary, its Kanon shape where its manifest declares a table, its level and its registries; it MUST name a library that has no role as a problem, MUST fail with --check (and write nothing) where the README is not what the manifests make, and verify and the tests of the repository MUST run that check.

Enforced (check): .github: cd commons/libraries && bun test suite/ — readme.test.ts: the summary and the first clause are read as data, a row is made from each manifest, the table is sorted by role and name, a library with no role is a problem, --check writes nothing and fails where the README is stale, and the real README is what the manifests make

Tests: passed: suite/readme.test.ts --check writes nothing and fails where the README is stale; without it the table is writte; passed: suite/readme.test.ts a row is made from a manifest, a library with no role is a problem, and rows are sorted by; passed: suite/readme.test.ts a summary is read as data from its literals joined by +, and the first clause is the first; passed: suite/readme.test.ts the real README is what the real manifests make, with a role for every library

Cited by: readme

FR-018checkpassing

The root README.md MUST describe what is and nothing that was: it MUST NOT contain the words formerly, previously, legacy, deprecated, backward, migration, UAT, acceptance test or agora, and every link of it whose target is a path in the repository MUST name a file or folder that exists.

Enforced (check): .github: cd commons/libraries && bun test suite/ — readme.test.ts: the real README has none of the words of history and every link to a path of the repository names a file or folder that exists

Tests: passed: suite/readme.test.ts the README holds none of the words of history and links only to paths that exist

The license

FR-019checkno test run

The library MUST make and check the license files of the repository (license.ts, exported as ./license; commons 0035-licensing FR-004 to FR-007 and FR-010, FR-012): the LICENSE of the root and of every library folder from the one official text in src/license/ and the required notice, and THIRD_PARTY_NOTICES.md from the record of what is vendored; --check MUST write nothing and exit 1 naming each file that is not what they make, a library with no LICENSE among them and the command that writes it; its verify and the development loop MUST run it; and the packer MUST write the identifier of the library's license as the license of the package it publishes and MUST pack its LICENSE.

Enforced (check): .github: cd commons/libraries && bun test suite/ — license.test.ts: --check writes nothing and names a missing or a hand-edited LICENSE, a changed official text is refused, the packer writes the SPDX id and packs the LICENSE

Cited by: license

FR-020checkpassing

A manifest MAY declare versionConstants, a list of the constants of the library's sources that say its own version, each a file from the library's folder and the name of the constant (ERGONEX_VERSION); apply MUST write the new version into each of them, together with the record, the manifest and the package, and MUST stop with a sentence naming the file where it is missing or does not say the constant as NAME = "<version>", so that no constant is left behind at the version a library had.

Enforced (check): .github: cd commons/libraries && bun test suite/ — releasing.test.ts: the version is written into each constant the manifest names, and a missing file or constant is a sentence

Tests: passed: suite/releasing.test.ts the version is written into each constant the manifest names, and a missing file or consta

FR-021checkno test run

A number of the section of the libraries MUST belong to one library: where two libraries hold the same number in the specification (two branches each gave the next number to a library and a merge kept both), the first in the section MUST keep it and the second MUST be given the next number after the greatest, so that the generator makes the section and the rows again with one number for each library.

Enforced (check): .github: cd commons/libraries && bun test suite/ — libraries.test.ts: two libraries that hold one number are given one each, the first in the section keeping it

FR-022checkpassing

A manifest MAY declare publishes, a package of commons (@intellectual-frontiers/<name>), and bundle, one of commons, foundation, patterns, programs and standards, equal to the library's own name; the decoder MUST refuse a publishes that is no package of commons, a bundle that is not the library's name and a manifest that has both. The release (the plan, the record and the publication) MUST use the package the manifest publishes (commons 0036-distribution FR-005, FR-009).

Enforced (check): .github: cd commons/libraries && bun test suite/ — metapackages.test.ts: publishes and bundle are read, and the three refusals; releasing.test.ts: the release uses the package a manifest publishes

Tests: passed: suite/metapackages.test.ts publishes and bundle are read; a publishes that is no package, a bundle that is not the li

FR-023checkpassing

In per-library mode the library MUST make the metapackages of commons (metapackages.ts, pack-metapackage.ts, exported as ./metapackages and ./pack-metapackage): the members of each set from the manifests and ROLE_OF, their exact dependencies written to dependencies.auto.json (--check writes nothing and exits 1 where a file is stale), and the tarball of a package with no code, which passes the inspection of every library's package; and the release MUST raise a metapackage after the libraries it depends on whenever one of them is raised (commons 0036-distribution FR-006 to FR-008); in single mode it MUST make none, and it MUST make the one package (distribution.ts, pack-commons.ts, exported as ./distribution and ./pack-commons, FR-028 to FR-032; commons 0036-distribution FR-019 to FR-028).

Enforced (check): .github: cd commons/libraries && bun test suite/ — metapackages.test.ts: the members, the exact dependencies, the generator and its --check, the packer and the order in the plan

Tests: passed: suite/metapackages.test.ts the real manifests: every library declares github and npm, the five metapackages are folde; passed: suite/metapackages.test.ts the set of a role is the role's in ROLE_OF, commons holds the four, a library held back is

Cited by: metapackages, pack-metapackage

FR-024checkpassing

A manifest MAY declare held, the one typed reason not to release the library, an object of a closed set of kinds with a required text on one line: { kind: "tests-only", reason } (a tool of tests that nothing depends on at run time), { kind: "unfinished", reason, missing, liftedWhen } (missing names at least one part that is not done, liftedWhen the condition that lifts the hold) and { kind: "owner-blocked", reason } (a decision of the owner that the text states); the decoder MUST refuse any other kind, any other field, a text that is empty, padded or of more than one line, a bare sentence in place of the object, and held together with publishes or bundle, and MUST accept any distribution with it (the rule of FR-015 of commons 0027-commons-libraries, at least one registry including github, holds only where held is absent). In per-library mode a held library MUST be left out of the facts of the release (so of the record, of apply and publish and of the tags), out of every set of the metapackages (in single mode a held library is in the one package, and only SINGLE_EXCLUDED leaves one out, commons 0036-distribution FR-027), and shown as not released with its kind in the README table; it MUST still be verified, packed and proved like any other library, and repoctl status MUST show it as held.

Enforced (check): .github: cd commons/libraries && bun test suite/ — held.test.ts: the closed kinds, the refusals of the decoder, the distribution and the sets, the README row; metapackages.test.ts: a held library is not in the facts of a release

Tests: passed: suite/held.test.ts on a real repository a library with a hold is left out of the facts and the record and is ; passed: suite/held.test.ts the plan says for each library that is not released the kind of its hold and its text, --r; passed: suite/held.test.ts a held library is in no set even where it declares npm, and every hold says itself in one ; passed: suite/held.test.ts a held library may declare any distribution and is refused with publishes or bundle; witho; passed: suite/held.test.ts a library with no hold is released; a hold is one of the closed kinds with its text, an un

Cited by: libraries, releasing, Repoctl host and capabilities

FR-025checkpassing

The check of the manifests (libraries.ts --check, which repoctl check, repoctl sync and CI run) MUST fail where a library that declares a spec kit is not listed in specKits of commons/docs.config.ts, naming the library and the line to add, and repoctl new library MUST list the spec kit of the library it makes, so that the site and the tests that read the configuration are not found red after a push; a repository with no such file is asked nothing.

Enforced (check): .github: cd commons/libraries && bun test suite/ — libraries.test.ts: a spec kit that docs.config.ts does not list is a finding naming the library and the line, a listed one is none; repoctl library-commit-doctor.test.ts: new library lists its spec kit

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

Tests: passed: suite/libraries.test.ts a library with a spec kit that commons/docs.config.ts does not list is a finding that name

Cited by: libraries, Repoctl library, commit and doctor

FR-026checkpassing

A library MUST be released unless its manifest carries a hold (FR-024): release plan MUST say for each library with a hold that it is not released, with the kind and the sentence of its hold (what is missing and what lifts it, where it is unfinished), for each of the others whether it is released as it is, raised, or left alone, and why, and --raise of a library with a hold MUST be refused with its reason.

Enforced (check): .github: cd commons/libraries && bun test suite/ — held.test.ts: the plan names each library that is not released with its kind and sentence, --raise of one is refused with its reason, and on a real repository the held library is out of the steps

Tests: passed: suite/held.test.ts on a real repository a library with a hold is left out of the facts and the record and is ; passed: suite/held.test.ts the plan says for each library that is not released the kind of its hold and its text, --r

Cited by: Repoctl status and release

FR-027checkpassing

The plan MUST give each raised library a floor read from the keys of exports of the version npm holds (the last tag of a changed library, the version itself of one that is ahead of its tag and that npm holds with other files) against the keys of its package now: a key removed or renamed MUST raise it by at least the breaking level (major: the minor while the major version is 0, the major from 1.0.0), a key added by at least the feature level (minor), the greater of the floor and the Impact: of its commits MUST win, and the plan MUST state the reason; where npm does not hold the version, cannot be asked (--offline) or does not answer there MUST be no floor, never a guess. The floor sees the keys of exports and nothing behind them: a type, a signature, a default or a behaviour that changed under an unchanged key, a key that now points elsewhere, and an export of a file the package does not list are not seen, so that the Impact: of the commits remains how a breaking change under a key is declared.

Enforced (check): .github: cd commons/libraries && bun test suite/ — release-floor.test.ts: the floor of removed and added keys, the greater of it and the commits wins, 0.x and 1.x, the reason in the plan, and on a real repository against a registry simulator that serves the manifest of a version

Tests: passed: suite/release-floor.test.ts a removed or renamed key raises at least the breaking level, an added key at least the fea; passed: suite/release-floor.test.ts on a real repository whose npm is a registry simulator: a library that dropped a key since; passed: suite/release-floor.test.ts the keys of exports of the version npm holds are read from its manifest, and a version it

Cited by: pack-commons, releasing, Repoctl status and release, How works are versioned

FR-028checkpassing

The distribution mode MUST be a closed union, per-library | single, named by one constant of distribution.ts (exported as ./distribution) that every program that packs, plans, releases or generates for distribution reads; single MUST be the mode of the repository, IFC_DISTRIBUTION MUST name the other mode for one run, and a value that is no mode MUST be refused and never read as the default. The source tree MUST NOT change with the mode (the folders, their spec kits, their verify and their version fields are the same in both). The machinery of the mode that is not active MUST be switched off and not deleted: in single mode the packer of a library MUST pack nothing and say so (--check ends in 0), the metapackages MUST be made by no program, and the machinery MUST work again where IFC_DISTRIBUTION names its mode (commons 0036-distribution FR-019, FR-020).

Enforced (check): .github: cd commons/libraries && bun test suite/ — pack-commons.test.ts: the mode is one of two, the repository is in single mode, the environment names the other for one run and a value that is no mode is refused; tests/release/commons-packages.test.ts: the per-library machinery works again under IFC_DISTRIBUTION=per-library

Tests: passed: suite/pack-commons.test.ts the mode is one of two, the repository is in single mode, the environment names the other

Cited by: distribution, Repoctl host and capabilities

FR-029checkpassing

In single mode the library MUST pack the whole of commons as one package, @intellectual-frontiers/commons (pack-commons.ts, exported as ./pack-commons, run by bun tools/pack.ts in commons/commons; the reader of the structure of a source, scan.ts, tells code from comments and strings), holding every library (every folder with a manifest that is not a metapackage, a held library included, none left out but those SINGLE_EXCLUDED names): for each library the compiled modules and their declarations under <library>/dist/, the sources for the Bun condition, the files that are not TypeScript and every folder its code reads at run time (all but those NOT_RUNTIME names). The exports MUST map each library to ./<library> and ./<library>/<subpath>, and every specifier that imports a library MUST be written @intellectual-frontiers/commons/<library>[/<subpath>] in the compiled files, the declarations, the shipped sources and the examples of comments, while a name that is no import is left as it is and a specifier that names no library is a finding. The dependencies MUST be the union of the libraries' runtime dependencies and of SINGLE_DRIVERS, each exact (two versions of one package and a version that is not exact are findings), @types/node a peer where a declaration names a type of Node; the bin MUST hold every command a library declares (a name two libraries declare is a finding); and the sideEffects MUST name every file that does something when it is loaded, found by reading the compiled files (commons 0036-distribution FR-021 to FR-025, FR-030).

Enforced (check): .github: cd commons/libraries && bun test suite/ — pack-commons.test.ts: the exports of each library, the rewriting of specifiers, the union of dependencies, the commands, the files that do something when loaded, the runtime folders and the packer on the real files of a small repository; tests/release/commons-package.test.ts packs the real libraries

Tests: passed: suite/pack-commons.test.ts the packer builds the real files of a small repository into one tarball that passes its ow; passed: suite/pack-commons.test.ts a command is a launcher of the compiled module and a name that two libraries declare is a ; passed: suite/pack-commons.test.ts a file that does something when it is loaded is found, and a declaration, a guard for the ; passed: suite/pack-commons.test.ts an import of a library is written as an import of the package, in code and in the example ; passed: suite/pack-commons.test.ts each library is mapped to ./<library> and ./<library>/<subpath>, so that the subpaths of t and 2 more

Cited by: pack-commons, scan

FR-030checkpassing

The packer MUST inspect the package before it packs it and a test MUST run the same inspection on the unpacked tarball: it MUST refuse a package that lacks an entry of a library, whose entry names a file that is not in it, in which a specifier still names a library by its own package or names an entry that is no key of exports, in which a relative import or an import of a package is not satisfied, with a dependency that is not exact, or in which a file that does something when it is loaded is not in sideEffects; and the proof of the tarball MUST be a real one: installed into an empty project with npm and with Bun, every entry of every library imported on Node 26 and on Bun, the commands run, and a consumer that imports every entry type-checked by TypeScript 7 under nodenext and bundler, with and without the dom library (commons 0036-distribution FR-026).

Enforced (check): .github: bun test tests/release/commons-package.test.ts — the one package is packed from the real libraries, inspected, installed with npm and with Bun, every entry imported on Node 26 and Bun, its commands run and a consumer type-checked with and without dom; pack-commons.test.ts shows each check that matters on a copy made to fail

Tests: passed: suite/pack-commons.test.ts the packer builds the real files of a small repository into one tarball that passes its ow

FR-031checkpassing

The folder of the package, commons/commons, MUST install by itself what compiling every library needs: its devDependencies and its committed bun.lock MUST hold, each at an exact version, the union of the libraries' runtime dependencies and the drivers, typescript, @types/node, the @types/<package> a manifest names and every other third-party package that a packed source imports, derived from the manifests and the sources by pack-commons.ts --tools (pack-tools.ts, which writes them; --check writes nothing), never listed by hand; a library that needs a package the folder lacks MUST be a finding of verify that says so, and the packer MUST resolve the libraries and packages from the folder alone (commons 0036-distribution FR-029).

Enforced (check): .github: cd commons/libraries && bun test suite/ — pack-commons.test.ts: the tools of the package are derived from the manifests and the sources, a package the libraries need that the folder lacks is a finding, and the real folder is what the derivation makes; tests/release/commons-ci.test.ts: a fresh clone with only the folder installed packs the package

Written in: libraries/src/pack-tools.ts

Tests: passed: suite/pack-commons.test.ts a package the libraries need that the manifest or the lockfile of the folder lacks, or hol; passed: suite/pack-commons.test.ts in the real repository the manifest and the lockfile of commons/commons hold every package; passed: suite/pack-commons.test.ts the third-party packages of the folder of the package are linked where the sources of a li; passed: suite/pack-commons.test.ts the tools of the package are the union of the dependencies and the drivers, the compiler,

FR-032checkpassing

In single mode release plan and release apply MUST make one release, commons, tagged commons-v<version>: raised from the last tag and the files of every library since it by the greatest Impact: of the commits that touched any library (a patch where none states one) or, where it is greater, by the floor of the keys of the package's exports against the version npm holds (FR-027), a breaking impact raising the minor while the major version is 0; a version that has no tag or is ahead of its tag is released as it is unless the registry holds it with other files; a held library MUST NOT be left out of the package by its hold; the versions of the libraries MUST NOT be raised; and apply MUST refresh the lockfile of commons/commons, make the generated files, run repoctl sync and the proof of FR-030, and MUST NOT publish, tag or commit. The registries of the package MUST be the typed list SINGLE_TARGETS of distribution.ts, ["github"]: the release workflow MUST send the one tarball to the GitHub package registry with the job's token and packages: write, MUST NOT send it to npm and MUST tag after the publication, so that adding npm to the list is the only change that turns the npm target on (commons 0036-distribution FR-027, FR-028).

Enforced (check): .github: cd commons/libraries && bun test suite/ — release-single.test.ts: single mode plans one release raised by the greatest Impact across the libraries, a held library counted, and the registries are github alone, the publication sending the tarball to the GitHub package registry and tagging

Tests: passed: suite/release-single.test.ts single mode plans one release of commons: raised by the greatest Impact across all librari; passed: suite/release-single.test.ts the registries of the one package are github alone, and the publication sends the tarball

Cited by: Repoctl host and capabilities

Acceptance scenarios

  1. Given a folder commons/x/ with a manifest, When the section of the libraries is made, Then it holds one requirement for x and its row, and --check fails where either differs, per FR-001 and FR-002.
  2. Given a change to a file of one library, When the affected libraries are asked for, Then that library and each that depends on it are in the matrix and no other, per FR-003.
  3. Given the typed workflows of the repository, When the generator runs with --check, Then each file is what the model makes and a hand-written workflow is a finding, per FR-005.
  4. Given a library that is published to npm, When the packer runs, Then every export has its declaration in the tarball and a consumer type-checks against it, per FR-007.
  5. Given a change to a file of one library, When bun run dev:check runs, Then that library and the libraries whose own sources import it are type-checked and tested, and nothing else, per FR-011.
  6. Given a push, When the workflow ci runs, Then its plan names the libraries the push affects, a library that is not affected has no job, and the systems besides Linux are asked for only by a library whose record names them, per FR-012.
  7. Given libraries tagged and unchanged, a library whose files changed since its tag and one that imports it, When releasing.ts plan runs, Then the first two are raised and the importer by a patch, and the unchanged are left alone, per FR-013.
  8. Given a release made by apply, When the release workflow is run from main and asked to publish, Then the libraries are published in the order of the record, skipping what a registry has, and tagged, per FR-014 and FR-015.
  9. Given the repository, When check --all runs, Then the verify of every library runs and a failing one fails the run, per FR-008.
  1. Given a library named archon-dialect-x that declares no family, When the manifests are checked, Then a sentence names the library and the host it may be held for, per FR-016.
  2. Given a host whose table declares a dialect and a library of that dialect's name that declares its family, When the manifests are checked, Then there is no finding, and for a dialect nobody registered or a registered one nobody declared there is one, per FR-016.
  3. Given a folder commons/x/ with a manifest and no LICENSE, When license.ts --check runs, Then it exits 1, names commons/x/LICENSE and the command bun commons/libraries/src/license.ts, and running that command writes the file, per FR-019.
  4. Given a library whose manifest names the constant X_VERSION of src/v.ts and is raised by apply, When its version is written, Then the constant holds the new version, and a missing file or constant is a sentence that names it, per FR-020.
  5. Given a section in which two libraries hold one generated number, When the section is made again, Then the first keeps it and the second has the next number after the greatest, per FR-021.
  6. Given a manifest with publishes: "@intellectual-frontiers/arcactl" and a manifest whose bundle is not its name, When they are read, Then the first gives its package to the release and the second is refused, per FR-022.
  7. Given the manifests of this repository, When the metapackages are made, Then each set holds the libraries of its role at their versions and the files are what the manifests make, per FR-023.
  8. Given a manifest with a typed held and distribution: [], When it is decoded, the plan of a release is made and the sets are made, Then it decodes, the library is in no fact of the plan and in no set, the plan names it as not released with its kind and reason, and held with bundle, a bare sentence or an unknown kind is refused, per FR-024 and FR-026.
  9. Given a library whose package.json gained a link: dependency its lockfile does not have, and a library it imports that changed, When apply runs, Then the lockfiles of the libraries it releases are refreshed before the tests that install from them, which pass, per FR-014.
  10. Given a library with a spec kit that commons/docs.config.ts does not list, When the manifests are checked, Then the check fails naming the library and the line to add, per FR-025.
  11. Given a library tagged at 0.3.1 whose last published version has the key ./old that its package does not have, and commits that state a patch, When release plan runs, Then the library is raised to 0.4.0 and the plan says that an export was removed or renamed, per FR-027.
  12. Given the repository in single mode and IFC_DISTRIBUTION=per-library for one run, When the mode is read and a value that is no mode is given, Then the first names per-library, the second is refused naming the variable, and the packer of a library says it packs nothing, per FR-028.
  13. Given the libraries of a repository, When pack-commons.ts packs them, Then one tarball holds every library with its exports, its rewritten specifiers, its union of dependencies, its commands and its sideEffects, it passes its own inspection and a copy made to fail is refused, per FR-029 and FR-030.
  14. Given a library whose sources import a third-party package the folder commons/commons does not list, When pack-commons.ts --tools --check runs, Then it fails naming the package, and --tools writes the devDependencies, per FR-031.
  15. Given libraries tagged commons-v0.2.0 and commits that state a minor impact, When release plan runs in single mode, Then one release commons is planned at 0.3.0, no library is raised, and the registries are the GitHub package registry alone, per FR-032.

Out of scope

  • The harness, its rules and its levels: mizan; the ontologies: ontology; the Git hosts: githost; the test evidence: quality and test.

Edge cases

  • A manifest that is not a literal, has two exports or an unknown field: refused naming the field, per FR-001.
  • A library with a dependency that is not a library of the repository: not in the matrix, per FR-003.
  • A workflow file written by hand under .github/workflows/: a finding, never deleted, per FR-005.
  • A runner with no network for the pinned Bun: the installer fails with the pinned address and the SHA-256 it wanted, per FR-006.

Assumptions

  • Every library of the repository is a folder of commons/ with a package.json of the same name.

Open questions

  • None.

Key entities

  • Manifest - the data library.ts holds about a library.
  • Matrix - the libraries a change affects, as a workflow reads them.
  • Model - the typed values a workflow is written in.
  • Packer - the program that builds, inspects and packs a library.

Success criteria

SC-001success criterion

A person adds a library by adding a folder and running one command, and the workflows, the requirements and the package of it follow.

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

affected, changes, check, dev, distribution, family, generate-ontology, generate-workflows, Libraries, libraries, license, link, metapackages, newer, oscal-register, pack-commons, pack-library, pack-metapackage, pins, plan, publish-ontology, readme, releasing, scan, versions, workflows/definitions, workflows/model, workflows/render, Repoctl status and release, Repoctl library, commit and doctor, Repoctl host and capabilities, How works are versioned, Commons libraries, Generated workflows, Libraries by concern, Distribution

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