The engine named Stolos MUST be retired: no library, package or command of commons MUST be named stolos, and what it did that is general MUST be done by libraries of commons/, while what is particular to one fleet MUST live in that fleet's own repository.
Enforced (review): 0034-archon FR-001 — a reviewer checks that no package, folder or command of commons is named stolos and that what the retired engine did that is general is done by a library
Compatibility with the engine that is retired (its formats, tags, releases, contracts, specifications and fleets) MUST NOT be a requirement of any library of commons, and a library MUST NOT carry a shim, a re-export or a migration path for it.
Enforced (review): 0034-archon FR-002 — a reviewer checks that no library carries a shim, re-export or migration path for the retired engine
A fleet MUST be an assembly: its repository MUST consume libraries as dependencies by package name at exact versions, MUST hold its own data (its machines, tags, requirements and assurance profile) and MUST compose the libraries it chose in its own composition root; no fleet MUST need code of another fleet.
Enforced (review): 0034-archon FR-003 — a reviewer checks that a fleet repository names its libraries by package at exact versions and holds its own data and composition root
commons/archon, the package @intellectual-frontiers/archon, MUST be a library at conformance level L1 (0028-conformance-levels) that is Kanon (0033-kanon, with the instances, plugins and family of its FR-019 to FR-024): its Governance layer MUST state requirements and the approval policy of a fleet (FR-014), its Logical layer MUST make from them an order (the typed desired state of a subject: a machine, a device, a workstation or a cloud account) and a plan (what differs between the observed state and the order, with a hash a person can sign), and its Physical layer MUST hold the surfaces that face a caller (the command line, a tool server, forced commands over SSH) and the port that dialects implement.
Enforced (review): 0034-archon FR-004 — a reviewer checks the manifest and the Kanon table of archon: governance, logical and physical hold what FR-004 says
A dialect MUST be a package of its own named archon-dialect-<tool> (ansible, opentofu, dsc, cloud-init), a plugin of the command MUST be a package of its own named archon-<noun> (server, device, boot, tag, key, comply, connect, console, mcp), and the library manifest MUST say which of the two a package is (the field family, 0027-commons-libraries, with the reserved names of commons/libraries) and MUST declare each dialect as an instance of the dialect port and each plugin as a plugin of the host (0033-kanonFR-019 to FR-024); a plugin MUST reach archon and every other package only through its public exports, and MUST NOT import another plugin.
Enforced (review): 0034-archon FR-005 — a reviewer checks the names and the family field of each dialect and plugin package; the import check of 0033-kanon holds the public-exports rule
The command a person types MUST be archon, one program for every machine, composed from the command branches of the plugins a fleet chose (the composition of commons/headless): where a verb runs (here or on a target) MUST be the reach policy of its action, and which verbs a caller sees MUST be its governance (audience, effect, tier), so that the same command runs on a PC and on a server.
Enforced (review): 0034-archon FR-006 — a reviewer checks that one program is composed from the command branches of the chosen plugins and that reach and tier are governance, not code
archon MUST NOT implement what an existing tool does well: it MUST render the tool's input from an order, run the tool through the Executor port of commons/headless (here or by SSH), and read the tool's result into a typed outcome; it MUST NOT hold a module library, a provider library or a state store of its own beyond what commons/estate and commons/data provide.
Enforced (review): 0034-archon FR-007 — a reviewer checks that archon renders, runs through the Executor port and reads results, and holds no engine, module library or state store
A dialect MUST declare as data the kinds of resource it can carry out, whether it has a check mode, whether it is idempotent and whether it can destroy; and the model MUST say, for each annotation of a requirement and each dialect, whether it is expressed, carried or unexpressed with the reason (0033-kanonFR-005), so that a requirement that needs a faithful plan and is aimed at a dialect with no check mode is a named finding, never a surprise.
Enforced (review): 0034-archon FR-008 — a reviewer checks that each dialect declares its guarantees as data and that the model gives expressed, carried or unexpressed per annotation and dialect
The choice of a dialect for a resource MUST be policy, not code: a fleet MUST choose by the kind of resource and the kind of subject, and the library MUST give presets named for the approach (the default, pull-approved-tips, has a machine pull the tip its fleet approved and converge itself, so that a controller needs no copy of a tool it cannot run; push-from-controller is allowed only where the controller can run the tool).
Enforced (review): 0034-archon FR-009 — a reviewer checks that the choice of dialect is policy and that the presets are named for the approach
A system MUST be observed by one library and changed by another: commons/integrations and osquery observe and MUST NOT write, and a dialect changes; no client of ours MUST both read and write the same thing.
Enforced (review): 0034-archon FR-010 — a reviewer checks that no client both reads and writes the same system
What a dialect renders (an inventory, a playbook, a configuration of OpenTofu in JSON, a document of DSC, a cloud-init document) MUST be generated, MUST say so in the file, MUST NOT be edited by hand, and MUST be committed only where a reviewer needs to see it; it is output, and it is the one exception to the rule that everything of ours is configured in TypeScript.
Enforced (review): 0034-archon FR-011 — a reviewer checks that rendered output is generated, marked as such and not edited by hand
A dialect MUST pin the version of its tool (and of its collections, providers or resources) and MUST carry a conformance suite that runs the real tool, including the property that applying an order twice changes nothing the second time; a dialect that cannot show that property MUST say so in the matrix of FR-008.
Enforced (review): 0034-archon FR-012 — a reviewer checks each dialect's pins and that its conformance suite runs the real tool, including applying an order twice
The dialects of the first release MUST be the ones in this list, and each MUST say what its tool is and is not used for: Ansible for the configuration of hosts that run Linux (and of Windows hosts as managed nodes over SSH, from a Linux or macOS controller, because Windows cannot be an Ansible control node), OpenTofu for resources managed through an API, which is how archon converges cloud accounts as infrastructure as code (AWS, Azure, Google Cloud, Cloudflare and other providers: accounts, networks, DNS, identities, storage and the machines that run in them) and also DNS and network controllers, Microsoft DSC for a Windows workstation that converges itself, cloud-init and Ubuntu autoinstall for the first boot, and commons/data for databases.
Enforced (review): 0034-archon FR-013 — a reviewer checks the first dialects and what each says its tool is and is not used for
A fleet MUST declare an assurance profile when it is initialized, solo (one person: an authenticated push to the fleet's remote and a typed confirmation, a key optional), team (a signature of a listed signer, with a passphrase or a hardware-backed key, a recovery key and an audit mail of every change) or regulated (hardware-backed keys, a second approver for a change of tier or a destructive change, a signed hash of the plan and a ledger of evidence kept off the machine); each control of a profile MUST be a requirement, so that a fleet can override one control with typed data and a recorded reason, and the profile MUST never be chosen for a fleet by default without the person being told what it means.
Enforced (review): 0034-archon FR-014 — a reviewer checks that the three profiles and their controls are requirements, that a control can be overridden with a recorded reason, and that no profile is chosen without telling the person
Whatever the profile, these MUST hold: a secret MUST NOT be in a model, a specification, a commit, a log or a report; no library MUST store or see a passphrase; an agent MUST propose and a person MUST approve, and no agent MUST be able to approve; a destructive action MUST need the marker of its requirement and a confirmation typed by a person.
Enforced (review): 0034-archon FR-015 — a reviewer checks the floor: no secret, no stored passphrase, no agent approval, destructive actions need the marker and a typed confirmation
The profile in force for a tip MUST be the one of the last tip that was approved: a commit MUST NOT lower its own bar, and the lowering of a profile MUST be judged by the rules of the profile it leaves and MUST be recorded with its reason.
Enforced (review): 0034-archon FR-016 — a reviewer checks that the profile in force is the last approved tip's, with a test of a commit that lowers its own profile
Initializing a fleet MUST ask who administers it, whether any machine is reachable from the internet, whether it holds regulated data and whether a hardware key is at hand, MUST recommend a profile and MUST say in plain words what the profile allows (for solo: anyone who can push to the repository can change the machines); a check of the fleet MUST report whether the controls of its profile hold (for example, the protection of the default branch on its Git host), and a weaker profile MUST be reported as a decision with its date and never as a failure.
Enforced (review): 0034-archon FR-017 — a reviewer checks the questions of initialization, the recommendation, the plain statement of what the profile allows and the report of weaker profiles as decisions
archon and each package named in FR-004 and FR-005 MUST have its own specification kit in its own folder, MUST be released as <name>-v<version> (0026-works-versioning), and MUST be reviewed adversarially (by readers that try to break its design, not to polish it) before its first release and at the end of each phase of the plan, every finding being closed or recorded as a Decision.
Enforced (review): 0034-archon FR-018 — a reviewer checks that each library has its own spec kit and release name and that each adversarial review's findings are closed or recorded as Decisions
The first release of archon MUST wait for one slice to pass in virtual machines of lab on Linux: a fleet of one server converging the keys of its administrator and a baseline from an approved tip, with its state read back through osquery; and the measures of the first dialect (the fidelity of its plan, its idempotence, the finding of drift, the gate of destruction and the time) MUST be written in that dialect's specification.
Enforced (review): 0034-archon FR-019 — a reviewer checks that the first release waits for the slice in lab virtual machines and that the first dialect's measures are in its specification
The repository of the retired engine MUST be archived when FR-019 holds, and deleted only after a complete backup and at the explicit request of the owner; its open tickets MUST each be moved to a checklist item of the one ticket that tracks the subject (FR-021) or closed as superseded, one by one, before it is deleted.
Enforced (review): 0034-archon FR-020 — a reviewer checks that the old repository is archived, backed up and deleted only at the owner's request, with its tickets moved or closed one by one
The work of this specification and of every library it names MUST be tracked in ONE parent ticket for each piece of work (for the retirement of the engine, one ticket in this repository): every sub-task, whether a library, a dialect, a plugin, a phase or a review, MUST be an item of that ticket's body written as a checklist line (- [ ], checked when it is done), and the detail of an item MUST be a comment on that ticket; a separate ticket for a library, a phase or a sub-task MUST NOT be opened, and where one was opened its content MUST be moved to the parent and the extra ticket MUST be deleted.
Enforced (review): 0034-archon FR-021 — a reviewer checks that the work is one parent ticket with checklist items and comments, and that no ticket exists for a library, phase or sub-task
Every row below is a candidate that was named when this specification was written; none was read again in this work, so each is marked as not verified and each row marked unaligned is open to a Decision of the owner (0018-standards-firstFR-005).
Term
Standard and term
Relation
Verified
Requirement; order
NIST SP 800-128, Guide for Security-Focused Configuration Management of Information Systems: the baseline configuration
closeMatch
no
Assurance profile
NIST SP 800-63B: the authenticator assurance levels (AAL1 to AAL3)
broadMatch (levels of authentication, where a profile is also the policy of approval)
no
Plan; the loop of a machine that follows its fleet
the reconciliation loop of Kubernetes controllers
closeMatch
no
Order of resources and their dependencies
OASIS TOSCA, Topology and Orchestration Specification for Cloud Applications
broadMatch
no
Desired state of a host; its verification
SCAP (XCCDF and OVAL)
broadMatch
no
Dialect
the SQL dialects of commons/data; no standard names the term
Given a fleet repository, When its dependencies are read, Then each library is named by package at an exact version and the repository has its own fleet.ts and composition root, and none is copied from another fleet, per FR-003.
Given a plugin package that imports another plugin or a private file of archon, When the check of 0033-kanon runs, Then it is a finding (layers/private or layers/around), per FR-005.
Given an order with a requirement that needs a faithful plan, When it is aimed at a dialect with no check mode, Then the matrix names the annotation unexpressed with its reason, per FR-008.
Given an order and a dialect, When the order is applied twice, Then the second application changes nothing, per FR-012.
Given a fleet of profile team and a commit that changes fleet.ts to solo, When a machine follows the tip, Then it refuses the commit, because the profile in force is that of the last approved tip, per FR-016.
Given a fleet of profile solo and an agent that pushes a change, When the machine follows the tip, Then the change is not applied until a person has approved it, per FR-015.
Given a person who initializes a fleet and answers that one person administers it, that nothing is reachable from the internet and that nothing is regulated, When the initialization recommends a profile, Then it recommends solo and says that anyone who can push to the repository can change the machines, per FR-017.
Given a Windows machine and a controller that is a Windows PC, When the default preset is used, Then the machine converges itself with its dialect and the controller runs no copy of Ansible, per FR-009 and FR-013.
Given an order whose subject is a cloud account (for example an AWS account, an Azure subscription or a Cloudflare zone), When it is aimed at the OpenTofu dialect, Thenarchon renders the infrastructure as code for it, shows a plan with a hash a person can approve and applies only that plan, per FR-007, FR-013 and FR-014.
Given a new library of this work, When its work is planned, Then it is a - [ ] line in the body of the one parent ticket with its detail in a comment of that ticket, and no ticket of its own exists, per FR-021.
A migration of any fleet, format or specification of the retired engine (FR-002).
A console framework: the pages a person sees are projected from governance and from the logical schema of commons/data.
Bespoke probes of facts that osquery gives.
A cloud provider's own console or API client: the dialect renders the tool's input and reads its result, and a cloud's resources are the provider's of the tool.
The libraries that archon uses (commons/headless, commons/data, commons/integrations, commons/grc, commons/kanon), which have their own specifications and owners; this specification states only what it needs of them.
A machine that cannot run the tool of its dialect (a Windows controller and Ansible): the preset of FR-009 gives it a dialect it can run, or the requirement is unexpressed for it, never silently skipped, per FR-008 and FR-009.
A tool that has no check mode for a resource: its plan is not faithful, and the matrix says so, per FR-008; the requirement can still be applied if its effect class allows it.
A fleet that wants a control its profile does not have: it adds a requirement of its own with a reason, and the profile stays what it declared, per FR-014.
A profile that is lowered by a person who holds the profile's authority: allowed, judged by the profile it leaves, and recorded with its reason, per FR-016.
A dialect whose tool changes its licence or its input between versions: the pin holds the fleet, and the conformance suite finds the change before a release, per FR-012.
Ansible, OpenTofu, Microsoft DSC and cloud-init remain available and maintained for the versions each dialect pins; the state of each at the date of writing was read from its public announcements and not from this repository.
The Executor port of commons/headless (local and SSH targets) is what every dialect runs through, and its check-mode semantics and the composition of command branches are provided by that library's owner.
A fleet can reach npm to install its libraries; no token is needed for a public package.
Whether the name archon is free of a collision in the registers of trademarks and in software registries (the name is the retired engine's own command; this repository can show only that no term of its own clashes).
Whether Ansible's licence (GPL, to be confirmed against its text) allows the packaging of the dialect as designed (rendering and calling the program, copying none of its code), and the licences of the collections each dialect pins.
The providers for each cloud (AWS, Azure, Google Cloud) and for Cloudflare must be pinned and reviewed as the community provider for a network controller is (OQ-4), including their licences and what each can and cannot read back as a plan.
Whether the boot server of the retired engine (TFTP and HTTP, about 4,700 lines) stays small enough to keep, or whether dnsmasq or MAAS is better; neither was evaluated.
A fleet repository holds its data and a composition root of a few dozen lines, and every capability it uses comes from a published library at an exact version.
A fleet of one person and a fleet of a regulated organization both use archon, and what differs between them is the assurance profile and the dialects chosen, as data.