IF Commons GitHub

Distribution

0036Draft

0036-distribution · owner if · domain commons · part of 0027-commons-libraries

The rule

FR-001checkpassing

When a repository other than intellectual-frontiers/.github needs code of commons, it MUST get that code only by installing a published package: a public library from npm, a private package (one that belongs to a private repository) from the GitHub package registry (https://npm.pkg.github.com), with a scoped registry line and a token that may read packages in its .npmrc. Commons MUST NOT be consumed in any other way.

Enforced (check): .github: cd commons/libraries && bun test suite/ — metapackages.test.ts: AGENTS.md states the rule of consuming commons by a published package and no other way

Tests: passed: suite/metapackages.test.ts the root is private, AGENTS.md and the README state the rule, the README lists the metapac

Cited by: Repoctl, logical/hygiene, Consuming commons

FR-002checkno test run

A repository that consumes commons MUST NOT have a dependency on this repository by Git (github:intellectual-frontiers/.github, git+https://github.com/intellectual-frontiers/.github, a git: or ssh: URL of it, with or without a commit), a file: or link: dependency into a path that holds a checkout of commons, a relative import that crosses into a copy of commons, a vendored copy of a library (a folder of its own that is not under node_modules and carries a package named @intellectual-frontiers/<name> that is not the repository's own package) or a fetch of the raw source of a file of this repository. The check of FR-010 finds each of them.

Enforced (check): .github: cd commons/repoctl && bun test suite/ — hygiene.test.ts: each form the rule forbids is a finding with its code, and a repository in order has none

Cited by: Repoctl, logical/hygiene, Consuming commons

FR-003checkpassing

The root package.json of this repository MUST stay private ("private": true): it is the workspace of the development loop and is never installed by another repository. AGENTS.md MUST state the rule of FR-001 and the distribution of FR-004 in place of any other way of consuming commons.

Enforced (check): .github: cd commons/libraries && bun test suite/ — metapackages.test.ts: the root package.json is private and AGENTS.md states the rule and the distribution

Tests: passed: suite/metapackages.test.ts the root is private, AGENTS.md and the README state the rule, the README lists the metapac

Where each package is published

FR-004checkpassing

In per-library mode a library of commons MUST be published as the table says, and the registry it names is the only place a consumer takes it from; in single mode the one package of FR-021 is the only package that is published (FR-028) and every library is in it.

Packagedistribution in its manifestnpmGitHub package registryInstalled by
A public library (every library of commons)["github", "npm"]yesyes, the same tarballbun add @intellectual-frontiers/<name>@<version> from npm, or from the GitHub registry where a mirror is wanted
A private package (a package of a private repository)["github"]noyesa scoped .npmrc line and a token that reads packages
A metapackage (FR-005)["github", "npm"]yesyesthe same as a public library

The manifest MUST declare distribution: ["github"] for a private package and MUST NOT list npm for it, and the release MUST send it to the GitHub package registry alone. None of the libraries of commons is private: each declares ["github", "npm"]. A published version MUST NOT be sent again with other files: a changed library is released at a new version.

Enforced (check): .github: cd commons/libraries && bun test suite/ — metapackages.test.ts: every library declares github and npm, a manifest of github alone is read and one of npm alone is refused, and the metapackages declare both

Tests: passed: suite/metapackages.test.ts a manifest of github alone is read (a private package), one of npm alone is refused, and t

Cited by: Consuming commons

FR-005checkpassing

In per-library mode commons MUST publish five metapackages, each a library of commons with no code of its own whose manifest (library.ts) names bundle, the set it is, equal to its folder's name: @intellectual-frontiers/commons (folder commons/commons), @intellectual-frontiers/foundation, @intellectual-frontiers/patterns, @intellectual-frontiers/programs and @intellectual-frontiers/standards. A metapackage is at conformance level L0 and has no spec kit of its own; the name @intellectual-frontiers/commons is also borne by the private root package, which is not published under it.

Enforced (check): .github: cd commons/libraries && bun test suite/ — metapackages.test.ts: the five metapackages are folders named for their set with a manifest that names bundle, a bundle that is not the folder is refused, and the name of the metapackage is not linked to a checkout

Written in: foundation/library.ts, patterns/library.ts, programs/library.ts, standards/library.ts

Tests: passed: suite/metapackages.test.ts the real manifests: every library declares github and npm, the five metapackages are folde

Cited by: Libraries, metapackages, Libraries, Commons libraries

FR-006checkpassing

In per-library mode a library MUST be a member of a metapackage when its distribution names npm, it is not a metapackage and it is not held back, and the set of a role MUST be the libraries of that role in ROLE_OF of commons/libraries/src/readme.ts, the one place that gives the role of a library: foundation is foundation, pattern is patterns, program is programs and standard is standards; commons MUST hold every member of the four. A library with no role MUST be a problem and never a member of no set. A library that declares npm and is not ready to be installed MUST be in HELD_BACK of commons/libraries/src/metapackages.ts with the reason, and MUST leave that list when its owner releases it; the Archon library and its dialects, the package-managers kit and Toolchain are held back. The membership at the time of writing:

MetapackageMembers
foundationcore, crypto, formats, githost, lint, net, rdf, system, telemetry, terminal, test
patternsheadless, kanon
programsdata (the package arcactl, FR-009), ergonex, grc, integrations, integrations-github, libraries, repoctl
standardsintegrations-fhir, integrations-x12, mizan, ontology, quality
commonsevery member of the four sets

Enforced (check): .github: cd commons/libraries && bun test suite/ — metapackages.test.ts: the set of a role is the role's in ROLE_OF, commons holds the four, a library with no role is a problem, a library held back is in none

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, Libraries

FR-007checkpassing

In per-library mode the dependencies of a metapackage MUST be exactly its members, each package at exactly the version its manifest has in this repository (no range, no tag), and MUST be written by the generator bun commons/libraries/src/pack-metapackage.ts to dependencies.auto.json in the folder of the metapackage, never by hand; --check MUST write nothing and exit 1 where a file is not what the manifests make, and the generator MUST be among the generators of repoctl sync and of the release; in single mode it MUST make no file and MUST find a dependencies.auto.json that is there stale (FR-020). One version of a metapackage therefore names one coherent set of library versions, the versions of the release it is published in.

Enforced (check): .github: cd commons/libraries && bun test suite/ — metapackages.test.ts: the dependencies are the members at their exact versions, the generated files are what the manifests make and --check writes nothing

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 dependencies are the members at exact versions, the file records them, and a file that; passed: suite/metapackages.test.ts the generator writes the files, --check writes nothing, and a stale or hand-edited file is

Cited by: Libraries, pack-metapackage

FR-008checkpassing

In per-library mode the packer of a metapackage (tools/pack.ts) MUST stage a package that has index.js and index.d.ts with an empty module as its only entry, the exact dependencies of FR-007, a README (what the set holds, its install from npm and from the GitHub package registry, and the overrides that keep one copy of a library), the LICENSE made by the license generator and the SPDX identifier of the repository, MUST inspect it with the inspection of every library's package and pack it with bun pm pack. The release MUST list a metapackage in the release record after every member it depends on, and MUST raise its version, by at least a patch, whenever the version of any member changes or the membership changes, so that a new member version is never published without a metapackage that names it.

Enforced (check): .github: cd commons/libraries && bun test suite/ — metapackages.test.ts: the packer stages and inspects a metapackage and packs it, and the plan raises it after the members it depends on whenever a member is raised

Written in: foundation/tools/pack.ts, patterns/tools/pack.ts, programs/tools/pack.ts, standards/tools/pack.ts

Tests: passed: suite/metapackages.test.ts on a real repository: a metapackage is raised after the member that is raised, with its pa; passed: suite/metapackages.test.ts the packer stages a package with no code, the exact dependencies, the README and the LICEN

Cited by: Libraries, metapackages, pack-metapackage, Libraries

FR-009checkpassing

In per-library mode a manifest MAY declare publishes, the package it publishes where that is not @intellectual-frontiers/<name> (the data library publishes @intellectual-frontiers/arcactl). Where it does, the release record MUST carry that package name in each entry, the check that a version is on npm, the publication to the GitHub package registry, the comparison of the files with those npm holds, the status of repoctl and the dependency a metapackage has on the library MUST use it, and the tag of the release MUST stay <name>-v<version>.

Enforced (check): .github: cd commons/libraries && bun test suite/ — releasing.test.ts: the package a manifest publishes is the one the record, the registry check and the publication use, and the tag is the library's

Proved by: repoctl/suite/hygiene.test.ts

Tests: passed: suite/metapackages.test.ts publishes and bundle are read; a publishes that is no package, a bundle that is not the li; passed: suite/metapackages.test.ts on a real repository: a metapackage is raised after the member that is raised, with its pa; passed: suite/hygiene.test.ts status asks npm for the package a library publishes

Cited by: libraries, Libraries, Repoctl hygiene

The hygiene check

FR-010checkpassing

The program repoctl MUST have the verb hygiene, which any repository can run and which reads the repository it runs in: the package.json files outside node_modules, the lockfile (bun.lock or package-lock.json), the installed tree under node_modules, the folders and the sources of the repository. It MUST find, each with a code that repoctl explain <code> explains and the path it was found at:

  • E-HYGIENE-GIT: a dependency by Git on this repository (FR-002);
  • E-HYGIENE-PATH: a file: or link: dependency into a path that has a segment named commons with something after it;
  • E-HYGIENE-IMPORT: a relative import whose path has a segment named commons with something after it;
  • E-HYGIENE-VENDORED: a folder, outside node_modules, that is not the root package and not a workspace the root declares, whose package.json is named @intellectual-frontiers/<name>;
  • E-HYGIENE-DUPLICATE: two installed copies of one @intellectual-frontiers package (two versions in the lockfile, or two folders of it in node_modules), naming the versions and where they are;
  • E-HYGIENE-RANGE (a warning): a dependency on an @intellectual-frontiers package that is not an exact version (a range, a tag or latest).

Enforced (check): .github: cd commons/repoctl && bun test suite/ — hygiene.test.ts: the six findings are made from manifests, lockfiles, the installed tree and imports, each with its code

Proved by: repoctl/suite/hygiene.test.ts

Tests: passed: suite/hygiene.test.ts each of the six findings is made from facts, in the order of the codes

Cited by: Repoctl, logical/hygiene, Consuming commons

FR-011checkpassing

The core of the check MUST be a pure function of the facts it is given (the manifests, the lockfile, the installed tree, the imports), returning the findings as values, and the reading of files MUST be at the edge, through the ports of repoctl, so that the same facts give the same findings. It MUST read bun.lock and package-lock.json (npm lockfile versions 2 and 3), and a lockfile that cannot be read MUST fail with a finding of the environment (E-ENVIRONMENT) and a repository with none MUST warn with it, never a silent pass.

Enforced (check): .github: cd commons/repoctl && bun test suite/ — hygiene.test.ts: the core is pure, bun.lock and package-lock.json give the same duplicates and a missing lockfile is a finding

Proved by: repoctl/suite/hygiene.test.ts

Tests: passed: suite/hygiene.test.ts bun.lock and package-lock.json give the same duplicate, comments and trailing commas are r

Cited by: Repoctl, logical/hygiene-facts, logical/hygiene

FR-012checkpassing

repoctl hygiene MUST end in the statuses of every verb of repoctl (0 where there is no failure, 1 where there is one; a warning alone MUST NOT fail), and --json MUST give one document: the findings with their code, level, path, message and fix, and the counts. The verb MUST be of the public tier, a read that changes nothing, and MUST be run in CI of a consuming repository.

Enforced (check): .github: cd commons/repoctl && bun test suite/ — hygiene.test.ts: the verb ends in 1 only on a failure, a warning alone ends in 0, and --json is one document

Proved by: repoctl/suite/hygiene.test.ts

Tests: passed: suite/hygiene.test.ts on a folder: the facts are gathered through the ports, the real command ends in 1 with the

Cited by: Consuming commons

FR-013checkpassing

In the repository of commons itself (where commons/libraries/library.ts is present) the packages under commons/ are the repository's own: the verb MUST NOT report the link: dependencies of the libraries into ../ or the folders under commons/ as E-HYGIENE-PATH, E-HYGIENE-IMPORT or E-HYGIENE-VENDORED, and MUST say that it is the repository of commons; the findings of Git, duplicates and ranges MUST be made there as everywhere.

Enforced (check): .github: cd commons/repoctl && bun test suite/ — hygiene.test.ts: the repository of commons is not reported for its own packages

Proved by: repoctl/suite/hygiene.test.ts

Tests: passed: suite/hygiene.test.ts in the repository of commons the path, import and vendored findings are not made and the o

Cited by: Repoctl, logical/hygiene

The pins

FR-014reviewno test run

A consumer MUST pin an @intellectual-frontiers package at an exact version; in single mode it pins @intellectual-frontiers/commons and imports every library under it (FR-022), and in per-library mode it SHOULD pin a metapackage and take the libraries it brings, so that one release is one set; it MUST NOT hold two versions of one library in its tree, and it MAY keep one copy with overrides (npm, Bun) to the version of the metapackage. An upgrade is a new version of the metapackage, installed, followed by repoctl hygiene.

Enforced (review): 0036-distribution FR-010 — kept by the check of the exact pins (E-HYGIENE-RANGE and E-HYGIENE-DUPLICATE)

Cited by: Consuming commons

FR-015checkpassing

The packages of one release MUST be those of the release record commons/generated/release.auto.json (in single mode one entry, FR-028), published in dependency order, and a version of a library that another published package depends on MUST be on the registry before that package is.

Enforced (check): .github: cd commons/libraries && bun test suite/ — metapackages.test.ts: a metapackage is after its members in the release plan

Tests: passed: suite/metapackages.test.ts on a real repository: a metapackage is raised after the member that is raised, with its pa

Planned

FR-016noneno test run

ergonex init SHOULD write the scoped GitHub-registry line of FR-001 to the .npmrc of a repository that has a private package, taking the token from ERGONEX_GITHUB_TOKEN and never from GITHUB_TOKEN. Planned: it needs the manifest of the workspace to say which of its packages are private, which Ergonex's own specifications (ergonex 0001-ergonex, ergonex 0004-onboarding) decide first.

Enforced (none): Planned: the manifest of a workspace does not say which packages are private yet

Cited by: Consuming commons

FR-017checkno test run

commons/docs (the site generator and the ifc-docs command) MUST be published as a library, so that a consumer takes it from a registry too: it is @intellectual-frontiers/docs, a library in the sense of 0027-commons-libraries.

Enforced (check): .github: cd commons/docs && bun test suite/ — package.test.ts: the package @intellectual-frontiers/docs is a library with the command ifc-docs

The documents

FR-018checkpassing

The root README.md MUST have a section that says how other repositories use commons (the rule, the metapackages, the hygiene check, one install from npm and the scoped .npmrc of the GitHub package registry), and its generated table of the libraries MUST list the metapackages apart from the libraries and MUST say the mode and the import form of each library. The documentation site MUST have the guide commons/docs/guides/consuming-commons.md for an engineer who installs commons, with one entry in commons/docs.config.ts.

Enforced (check): .github: cd commons/libraries && bun test suite/ — metapackages.test.ts: the README has the section and the metapackage table, the guide exists with one entry in docs.config.ts

Tests: passed: suite/metapackages.test.ts the root is private, AGENTS.md and the README state the rule, the README lists the metapac

The distribution mode and the one package

FR-019checkno test run

The distribution mode MUST be a closed union, per-library | single, named by one constant of commons/libraries/src/distribution.ts that every program that packs, plans, releases or generates for distribution reads; single MUST be the mode of the repository. The environment variable 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 specifications, their verify, their Kanon layers and their version fields are the same in both.

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

Cited by: distribution, Libraries, pack-commons, Consuming commons, Docs, Libraries, Commons libraries

FR-020checkno test run

The machinery of the mode that is not active MUST be switched off and MUST NOT be deleted, so that the owner can switch back with one line: in single mode the packer of a library (tools/pack.ts) MUST pack nothing and say so (--check ends in 0, packing ends in 1 and names the package), the generator and the packer of the metapackages MUST make no file and no tarball, and release MUST plan, apply and record the one package alone; the machinery MUST work again where IFC_DISTRIBUTION names its mode, which a test proves.

Enforced (check): .github: cd commons/libraries && bun test suite/ — metapackages.test.ts: in single mode the generator of the sets makes no file and finds and removes the files that are there; release-single.test.ts: the plan is the one package's; pack-library.ts and the metapackage packer pack nothing in single mode and work where IFC_DISTRIBUTION names per-library (tests/release/commons-packages.test.ts)

Cited by: distribution, Libraries, Libraries

FR-021checkpassing

In single mode bun tools/pack.ts in commons/commons MUST pack one tarball of @intellectual-frontiers/commons that holds every library of commons, meaning every folder of commons/ with a manifest that is not a metapackage, a library with a held reason and the library lab (which has tests only) included, and none left out but those that SINGLE_EXCLUDED of distribution.ts names, with its reason (none while the owner orders every library in). The tarball MUST carry, for each library, the compiled ECMAScript modules and their declarations under <library>/dist/ at the paths its files have in its folder, the sources it ships for the Bun condition at those paths, and the files that are not TypeScript beside them; the compiler MUST be the one of the packer of a library (the base configuration of commons, TypeScript 7, preserveSymlinks), and the package MUST carry its license (PolyForm Noncommercial 1.0.0), a README, its repository (intellectual-frontiers/.github, directory commons/commons), its engines of Node 26 or later and type: module.

Enforced (check): .github: bun test ./tests/release/commons-package.test.ts — commons-package.test.ts: the one package is packed from the real libraries (all of them, lab and data included), its tarball inspected, installed with npm and with Bun; and pack-commons.test.ts on a small repository of real files

Proved by: tests/release/commons-package.test.ts

Written in: commons/library.ts, commons/tools/pack.ts

Tests: passed: tests/release/commons-package.test.ts the one package is packed from the real libraries, inspected, installed with npm and with

Cited by: Consuming commons, Libraries, Commons libraries, Libraries by concern

FR-022checkpassing

The exports of the package MUST map each library to ./<library> (its . entry) and ./<library>/<subpath> (each other key of its package), because the subpaths of libraries collide (./governance is a key of ten of them), and each entry MUST name its types file, its source for the bun condition and its compiled file for default. Every specifier that imports a library of commons, @intellectual-frontiers/<library>[/<subpath>], MUST be written @intellectual-frontiers/commons/<library>[/<subpath>] in the compiled files, the declarations and the sources the package carries (the package names itself, which Node 26, Bun and TypeScript under nodenext and bundler resolve), and in the examples of documentation comments; the sources of this repository MUST keep the name of the library (0033-kanon FR-010), and a name that is no import (a list of packages, a field of a manifest, the text of generated code) MUST be left as it is. A specifier that names no library of the package MUST be a finding and never left as it is.

Enforced (check): .github: cd commons/libraries && bun test suite/ — pack-commons.test.ts: the keys of the exports are ./<library>[/<subpath>] with their types, source and compiled file, an import is rewritten in code and in comment examples and a string is not, and no specifier of the real package names a library by its own package (tests/release/commons-package.test.ts)

Proved by: tests/release/commons-package.test.ts

Tests: passed: tests/release/commons-package.test.ts the one package is packed from the real libraries, inspected, installed with npm and with

Cited by: Libraries, scan, Consuming commons

FR-023checkpassing

The dependencies of the package MUST be the runtime dependencies of the libraries (their dependencies that are not of commons) except the packages SINGLE_PEERS of distribution.ts names, each at an exact version; two libraries that name two versions of one package, and a version that is not exact, MUST be findings. The packages that SINGLE_PEERS names MUST NOT be installed by the package: the database drivers the libraries take as ports (@duckdb/node-api, @electric-sql/pglite, pg), the packages only the documentation generator loads (shiki, beautiful-mermaid) and the TypeScript compiler (typescript) are optional peers: a consumer that uses a store of AnyFS or of Data installs its driver, a consumer that builds a site installs what Docs loads, and a consumer's own compiler is used and a second one is never installed. The range of each MUST be data of SINGLE_PEERS with the reason. Where a registry keeps peerDependenciesMeta, an optional peer MUST be a peerDependencies entry marked optional there; the GitHub package registry drops peerDependenciesMeta from the metadata a package manager resolves from (found by installing the first release that used it: npm and Bun installed every peer as a required one), so while the package is sent to it (SINGLE_TARGETS holds github) an optional peer MUST NOT be a peerDependencies entry and MUST be named, with its range, in the field ifcOptionalPeers of package.json, which no package manager reads and the inspection, the report and repoctl usage do. A declaration that names a type of Node MUST make @types/node a peer dependency (not optional, which the registry keeps).

Enforced (check): .github: cd commons/libraries && bun test suite/ — pack-commons.test.ts: the dependencies are the union of the libraries' and the drivers', exact, two versions of one package and a range are findings

Proved by: tests/release/commons-package.test.ts

Tests: passed: tests/release/commons-package.test.ts the one package is packed from the real libraries, inspected, installed with npm and with

Cited by: distribution, pack-commons, AnyFS SQL: the port

FR-024checkpassing

The bin of the package MUST hold every command that a library declares, each a launcher in bin/ that imports the compiled module and runs under Node 26 and Bun (anyfs, arcactl, ifc-docs, ergonex, repoctl), and a name that two libraries declare MUST be a finding.

Enforced (check): .github: cd commons/libraries && bun test suite/ — pack-commons.test.ts: a command is a launcher of the compiled module and a name two libraries declare is a finding; the five commands run on Node from the installed package (tests/release/commons-package.test.ts)

Proved by: tests/release/commons-package.test.ts

Tests: passed: tests/release/commons-package.test.ts the one package is packed from the real libraries, inspected, installed with npm and with

Cited by: Consuming commons, Docs

FR-025checkpassing

The sideEffects of the package MUST name every file that does something when it is loaded (a module that installs a port, such as the one of the telemetry host that installs the process tracer of system, a table made at load, a command) and, by that, MUST NOT mark such a file free of effects; the packer MUST find them by reading the compiled files, and the inspection MUST read them again.

Enforced (check): .github: cd commons/libraries && bun test suite/ — pack-commons.test.ts: a file that does something when it is loaded is found and the package that marks it free of effects is refused; the telemetry host is named in the real package (tests/release/commons-package.test.ts)

Proved by: tests/release/commons-package.test.ts

Tests: passed: tests/release/commons-package.test.ts the one package is packed from the real libraries, inspected, installed with npm and with

Cited by: Libraries, scan, Libraries

FR-026checkpassing

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 by a file or a dependency, with a dependency that is not exact, in which a file that does something when it is loaded is not in sideEffects, in which a file imports an optional peer statically (FR-033), in which a file of dist/ is not a declaration (FR-030), or that breaks the content policy or the size budget (FR-031, FR-032); 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 under bundler, once with the dom library and once without it.

Enforced (check): .github: bun test ./tests/release/commons-package.test.ts — commons-package.test.ts: the real installs with npm and Bun, every entry of every library imported on Node and Bun, a consumer type-checked with and without dom under nodenext and bundler; pack-commons.test.ts: a missing library, an unrewritten specifier, a colliding command and a missing dependency are each found on a copy made to fail

Proved by: tests/release/commons-package.test.ts

Tests: passed: tests/release/commons-package.test.ts the one package is packed from the real libraries, inspected, installed with npm and with

Cited by: Libraries, Libraries by concern

FR-027checkno test run

In single mode release plan and release apply MUST make one release, commons, whose tag is commons-v<version>: the version is raised, from the last tag commons-v* 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 (every library's keys under its name) against the version npm holds, a breaking impact raising the minor while the major version is 0 (0026-works-versioning FR-041); a version that has no tag or is ahead of its last tag is released as it is unless the registry holds it with other files (the sources by their SHA-256, with their specifiers written as the package's, and the keys of exports); a held library MUST NOT be left out of the package by its hold, and SINGLE_EXCLUDED is the only list of libraries the package leaves out. The versions of the libraries MUST NOT be raised by the release of single mode, and the release record MUST hold the one entry. apply MUST refresh the lockfile of commons/commons, make the generated files, run repoctl sync and run the proof of FR-026, and MUST NOT publish, tag or commit.

Enforced (check): .github: cd commons/libraries && bun test suite/ — release-single.test.ts: one release of commons, raised by the greatest Impact across all libraries with the rule of major version 0, a held library counted, a version ahead of its tag released as it is, the floor of the keys of exports, the record with its one entry

Cited by: Libraries, pack-commons, releasing, Libraries, How works are versioned, Libraries by concern

FR-028checkno test run

The registries the one package is sent to MUST be a typed list, SINGLE_TARGETS of distribution.ts, of the closed set github | npm, and it MUST be ["github"]: the release workflow MUST send the one tarball to the GitHub package registry (https://npm.pkg.github.com, scope @intellectual-frontiers, the package linked to this repository by its repository field) with the token of the job and packages: write, MUST NOT send it to npm, and MUST make the tag after the publication; the record MUST name the registries of its entry and the publication MUST honor them, so that adding npm to the list is the only change that turns the npm target on. The published package.json MUST carry publishConfig.registry of the GitHub package registry where the list lacks npm, and publishConfig.access where it has it. A consumer of the package MUST map the scope to the GitHub package registry in its .npmrc and, for Bun, its bunfig.toml, with a token that may read packages, and the package MUST grant the consumer repository read access.

Enforced (check): .github: cd commons/libraries && bun test suite/ — release-single.test.ts: the registries are github alone, the publication sends the tarball to the GitHub package registry and tags and asks npm for nothing, and with npm in the list sends it there too

Cited by: distribution, Consuming commons, Libraries, Commons libraries

FR-029checkfailing

The folder of the package, commons/commons, MUST install by itself what compiling every library needs, because the release workflow runs bun install --frozen-lockfile and bun run verify in that folder alone: its package.json MUST carry as devDependencies, and its committed bun.lock MUST hold, each at an exact version, the union of the runtime dependencies of the libraries and the drivers of FR-023, typescript, @types/node, the @types/<package> that a library's manifest names for one of them, and every other third-party package that a packed source imports, derived from the manifests and the sources by bun commons/libraries/src/pack-commons.ts --tools (which writes them; --check writes nothing), never listed by hand, and a library that needs a package the folder lacks MUST be a finding of bun run verify that says so. The packer MUST resolve the libraries and the third-party packages of the folder from the folder alone (it links them under commons/node_modules, which is not committed), so that a fresh clone with only the folder installed packs the package.

Enforced (check): .github: cd commons/libraries && bun test suite/ — pack-commons.test.ts: the tools are derived from the manifests and the sources, a library that needs a package the folder lacks is found in its package.json and in its bun.lock; tests/release/commons-ci.test.ts: a fresh clone with only commons/commons installed passes bun install --frozen-lockfile, bun run verify and bun tools/pack.ts

Proved by: tests/release/commons-ci.test.ts

Tests: failed: tests/release/commons-ci.test.ts a fresh clone with only commons/commons installed passes bun install --frozen-lockfile, bu

Cited by: Libraries

FR-030checkno test run

The package MUST carry, for each library, every folder of its folder that its code reads at run time, once: beside its sources, with the compiled module of each source in the same folder as the source (src/mod.ts and src/mod.js), so that a module finds the files it reads at the same relative path under Node (the compiled file) and under Bun (the source) and no file is shipped twice. dist/ of a library MUST hold the declarations only (.d.ts), and the exports MUST name the declarations in dist/, the source for bun and the compiled file beside it for default. The folders carried are every folder other than those of NOT_RUNTIME of pack-commons.ts (the tests, the specifications, the tools, the acceptance kits, the launchers the packer makes and what a build leaves), so that the data of a catalog, the guides of Docs and the installers of Ergonex are in it without a list, and a library that reads them finds them under Node and under Bun from the installed package.

Enforced (check): .github: bun test ./tests/release/commons-package.test.ts — commons-package.test.ts: the data of the NIST catalogs, the guides of Docs and the installers of Ergonex are in the tarball and the catalogs load their data from the installed package on Node and on Bun; pack-commons.test.ts: a folder a library reads is shipped beside its sources and its compiled files and the folders of NOT_RUNTIME are not

Proved by: tests/release/commons-package.test.ts

Cited by: Libraries, What a consumer uses of the package

FR-031checkno test run

The content of the package MUST be a policy the packer enforces, and what ships MUST be only what a consumer runs, types or reads: the sources and the compiled files of each library's entries, its declarations, the folders its code reads at run time (FR-030), the launchers of the commands, package.json, README.md and LICENSE. Nothing that only commons needs internally MUST ship: no test, no suite/, no specification kit, no tools/, no acceptance kit, no source map, no lockfile, no node_modules and no baseline of a check; a file of that kind in the staged package MUST be a finding that names it, and a byte-identical copy of a file beside it in another folder of the same library MUST be a finding (dist/ holds declarations and nothing else).

Enforced (check): .github: cd commons/libraries && bun test suite/ — pack-commons.test.ts: a file that only commons needs internally, a file in dist/ that is no declaration and a file shipped twice are findings of the inspection

Proved by: tests/release/commons-package.test.ts

Cited by: pack-commons

FR-032checkno test run

The package MUST have a size budget, as data of distribution.ts (SINGLE_BUDGET: the apparent bytes of the staged package, its number of files, and the bytes of the tarball), which the inspection MUST enforce (a package over it is a finding naming the figure and the budget) so that a growth is a decision and never an accident. The packer MUST write a report of what it packed, dist/package-report.json, with the bytes and the files of the package, of each library and of each kind of file (compiled, source, declaration, data, documentation), and the dependencies and peer dependencies with their ranges, and --size MUST print it as a table; the site (docs 0001-docs) MUST show it as the page quality/package (docs 0001-docs).

Enforced (check): .github: cd commons/libraries && bun test suite/ — pack-commons.test.ts: a package over its budget is a finding, and the staged package is reported by kind and by library

Proved by: tests/release/commons-package.test.ts

Cited by: distribution, pack-commons, Docs

FR-033checkno test run

A module that uses an optional peer of FR-023 MUST load it lazily and MUST say what is missing: the module MUST import it with import() where it is used and never statically at the top of a file the package's entries load, so that every entry of the package imports with none of the optional peers installed; where the peer is absent, the function that needs it MUST fail, or degrade where the output does not need it, with a message that names the package and the range to install (shiki colours the code of a page, and the page is made plain with a warning where it is absent; beautiful-mermaid draws a diagram, and the diagram stays as its source with a warning where it is absent; typescript reads the API of an area, which needs it and says so; the drivers are handed to a library by its caller, and an adapter that is handed none says which one to install). The inspection MUST find a static import of an optional peer in a file of the package.

Enforced (check): .github: cd commons/libraries && bun test suite/ — pack-commons.test.ts: a static import of an optional peer is a finding and a dynamic one is not; commons-package.test.ts imports every entry with no optional peer installed

Proved by: tests/release/commons-package.test.ts

Cited by: distribution, AnyFS SQL: the port

FR-034checkno test run

What a consumer reaches of the package MUST be answerable from the consumer's own files: repoctl usage (repoctl 0014-repoctl-usage) MUST list the libraries and the subpaths a repository imports from the package, the libraries they reach by their own imports, and the libraries and the bytes the repository never touches, so that what the package holds against what a consumer needs is measured and not guessed.

Enforced (check): .github: cd commons/repoctl && bun test suite/ — usage.test.ts: the libraries imported, reached and never touched, from the consumer's files and the installed package

Cited by: Repoctl, logical/usage, Docs, What a consumer uses of the package

Acceptance scenarios

  1. Given the manifests of this repository, When the generator runs, Then each metapackage's dependencies.auto.json holds exactly the members of its set at their versions, commons holds the members of the four others, and --check exits 0 and writes nothing, per FR-006 and FR-007.
  2. Given a manifest that declares a library with no role, When the generator runs, Then it names the library and writes nothing, per FR-006.
  3. Given a library held back, When the sets are made, Then it is in none of them, per FR-006.
  4. Given a metapackage, When it is packed, Then the tarball holds index.js, index.d.ts, the README and the LICENSE, its package.json has the exact dependencies and passes the inspection, per FR-008.
  5. Given a library of a set that the plan raises, When the plan is made, Then the metapackages that hold it are raised by at least a patch and come after it in the record, per FR-008.
  6. Given the manifest of data that says publishes: "@intellectual-frontiers/arcactl", When the plan, the record and the publication are made, Then each uses @intellectual-frontiers/arcactl for the registries and data-v<version> for the tag, per FR-009.
  7. Given a repository whose package.json depends on github:intellectual-frontiers/.github#abc, When repoctl hygiene runs, Then it exits 1 with E-HYGIENE-GIT and the path, per FR-010.
  8. Given a link:../commons/core dependency, a vendored folder vendor/core named @intellectual-frontiers/core, a relative import ../commons/core/src/mod.ts and a lockfile with two versions of @intellectual-frontiers/core, When repoctl hygiene runs, Then it reports E-HYGIENE-PATH, E-HYGIENE-VENDORED, E-HYGIENE-IMPORT and E-HYGIENE-DUPLICATE, each at its path, per FR-010.
  9. Given a dependency ^0.1.5 on an @intellectual-frontiers package and nothing else wrong, When repoctl hygiene runs, Then it reports E-HYGIENE-RANGE as a warning and exits 0, per FR-010 and FR-012.
  10. Given bun.lock and package-lock.json of the same two copies, When the check reads each, Then it finds the same duplicate, per FR-011.
  11. Given a repository in order, When repoctl hygiene --json runs, Then it prints one JSON document with no finding, per FR-012.
  12. Given this repository, When repoctl hygiene runs in it, Then the packages under commons/ and their link: dependencies are not findings, per FR-013.
  13. Given the real repository, When the tests run, Then AGENTS.md and the README state the rule and the guide exists with its entry, per FR-003 and FR-018.
  14. Given the real repository in single mode, When bun tools/pack.ts runs in commons/commons, Then one tarball holds all the libraries, passes the inspection and installs and imports with npm and with Bun, per FR-021 to FR-026.
  15. Given a package in which a library is missing, a specifier still names a library by its own package, a command is declared twice or a dependency is not declared, When it is inspected, Then each is a finding, per FR-023, FR-024 and FR-026.
  16. Given a tagged commons and a change of one library with Impact: major while the major version is 0, When release plan runs, Then one step raises the minor and tags commons-v<version>, per FR-027.
  17. Given the record of the one package and the list ["github"], When the publication runs, Then the GitHub package registry is asked and sent the tarball and npm is not, per FR-028.
  18. Given the real repository in single mode with the GitHub registry as the target, When the one package is packed, Then its dependencies are empty of drivers, of the documentation generator's packages and of the compiler, its peerDependencies name only @types/node, and ifcOptionalPeers names the drivers, the documentation generator's packages and the compiler with a range each, per FR-023; and When the package is installed from the registry into an empty project, Then none of the optional peers is installed.
  19. Given the packed tarball installed into an empty project with none of the optional peers, When every entry of every library is imported on Node 26 and on Bun, Then every entry imports, and a function that needs an absent peer says which package to install, per FR-033.
  20. Given the staged package, When it is inspected, Then dist/ of a library holds declarations only, no file of one folder is a byte-identical copy of a file of another folder of the same library, and a library that reads a file beside its module finds it under Node and under Bun, per FR-030 and FR-031.
  21. Given a staged package with a test file, a source map, a specification kit, a static import of an optional peer or more bytes than the budget, When it is inspected, Then each is a finding that names it, per FR-031, FR-032 and FR-033.
  22. Given a consumer repository and the package it installs, When repoctl usage runs, Then it lists the libraries and subpaths imported, those reached through them and those never touched with their bytes, per FR-034.

Out of scope

Edge cases

  • A repository that holds a folder commons of its own (not ours): a path or an import that goes through it is a finding where something follows the segment, and the message says what was found; the check reads a path and does not know the names of the libraries, per FR-010.
  • A lockfile with one version of a package under two paths (hoisting): one copy, no finding; two versions: E-HYGIENE-DUPLICATE, per FR-010.
  • A repository with no lockfile: the finding of the environment, and the other findings are still made, per FR-011.
  • A metapackage whose set is empty: refused by the packer, per FR-008.
  • A library with no entry that a consumer needs by name (lab has tests only): it is in the package and its entries are importable, per FR-021.

Assumptions

  • npm and Bun both read overrides of a package.json.
  • The GitHub package registry serves the scope @intellectual-frontiers to a token that may read packages of the organization.

Open questions

OQ-1open question

The terms of FR-023 and FR-033 (a peer dependency, an optional peer) are npm's own, the fields peerDependencies and peerDependenciesMeta of a manifest, and are not coined here; SPDX names such relationships (OPTIONAL_DEPENDENCY_OF and others), which this repository has not read, so the alignment is unverified. The terms of FR-031, FR-032 and FR-034 (the content policy, the size budget, the usage report) are commons' own and no standard was examined for them: no ontology term states them, and the owner decides whether they are to be classes of the packaging ontology (commons 0018-standards-first FR-005).

Key entities

  • Metapackage - in per-library mode a published package with no code whose dependencies are a set of libraries at exact versions.
  • Distribution mode - per-library or single, the one constant of distribution.ts.
  • The one package - @intellectual-frontiers/commons of single mode, all the libraries at one version.
  • Set - commons, foundation, patterns, programs or standards.
  • Finding of hygiene - a code, a level, a path, a message and a fix.

Success criteria

SC-001success criterion

A repository that installs @intellectual-frontiers/commons at one version and passes repoctl hygiene holds one copy of each library, all from a registry.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), or marked Planned
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

distribution, Libraries, libraries, metapackages, pack-commons, pack-metapackage, releasing, scan, Repoctl, logical/hygiene-facts, logical/hygiene, logical/usage, Consuming commons, Intellectual Frontiers Commons, Docs, Libraries, AnyFS SQL: the port, TypeScript practice, Repoctl hygiene, Documentation, What a consumer uses of the package, How works are versioned, Commons libraries, Libraries by concern

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