IF Commons GitHub

Native-pinned dialect

0004Active

0004-native-pinned-dialect · owner if · domain commons

Requirements

FR-001checkpassing

The dialect MUST declare its guarantees as data: the kind tool, subjects of the classes machine and workstation, a faithful plan (what it would do is found without the network), idempotence proven by its tests, and that it can destroy; and as a dialect of tools that it pins exactly, checks by hash, installs in the user scope, reaches the five platforms, takes the download of a pin and never builds from source.

Enforced (check): .github: cd commons/archon-dialect-native-pinned && bun run verify — suite/dialect.test.ts: guarantees as data and the plan file read back

Proved by: archon-dialect-native-pinned/suite/dialect.test.ts

Written in: archon-dialect-native-pinned/src/dialect.ts

Tests: passed: suite/dialect.test.ts the dialect declares its guarantees as data, and as a dialect of tools meets the strictest; passed: suite/dialect.test.ts the plan file is read back, and what is not one is refused with the reason

FR-002checkpassing

observe MUST find each tool wanted: first in the store (a copy whose install record is there and whose program is there too; the files are compared with the record by installDrift, which a caller that verifies uses), then, where the policy allows a system copy, on the PATH under the program's name and then each of its other names; it MUST ask each program its version with the tool's arguments and a limit of five seconds, and a program that cannot be asked (a hang, a crash) MUST be reported as found and unreadable and never end the run.

Enforced (check): .github: cd commons/archon-dialect-native-pinned && bun run verify — suite/dialect.test.ts: the observation of the store, the path and a program that cannot be asked

Proved by: archon-dialect-native-pinned/suite/dialect.test.ts

Written in: archon-dialect-native-pinned/src/dialect.ts, archon-dialect-native-pinned/src/observe.ts

Tests: passed: suite/dialect.test.ts Archon is given the desired state for a tool installed as pinned, a differing state for an; passed: suite/dialect.test.ts the observation finds a tool in the store, a program on the path under its names, and a pr

FR-003checkpassing

render MUST give the plan file of the tools that change something as generated output (it says so, never edited), holding for each tool its name, version, program, other names, scope, minimum and source (the address, the SHA-256, the format and the folder, or the pin and the reason it has none), and MUST NOT hold a secret; and steps MUST give the step that applies it and the step that checks it, each naming the digest of what was rendered in the path .archon/<digest>/native-pinned/plan.json.

Enforced (check): .github: cd commons/archon-dialect-native-pinned && bun run verify — suite/dialect.test.ts: the plan file rendered and the steps name its digest

Proved by: archon-dialect-native-pinned/suite/dialect.test.ts

Written in: archon-dialect-native-pinned/src/dialect.ts, archon-dialect-native-pinned/src/plan-file.ts

Tests: passed: suite/dialect.test.ts the plan file is rendered from Archon's order and plan with the real pins, says it is gene

FR-004checkpassing

In check mode the program MUST change nothing and MUST say, tool by tool, none, install or replace, ending with a status that says whether something would change; in apply mode it MUST do it, and a second apply of the same plan MUST change nothing.

Enforced (check): .github: cd commons/archon-dialect-native-pinned && bun run verify — suite/dialect.test.ts: check changes nothing, apply installs, a second apply changes nothing

Proved by: archon-dialect-native-pinned/suite/dialect.test.ts

Written in: archon-dialect-native-pinned/src/bin.ts

Tests: passed: suite/dialect.test.ts check changes nothing and says so by its status; apply installs; a second apply changes no; passed: suite/dialect.test.ts the program runs as a program: apply installs, and a second run changes nothing

FR-005checkpassing

Before it acts the program MUST say, for each tool, which program it is and where it was found or that it was not; every failure MUST name the tool, the step (lock, download, checksum, unpack, switch), what the step saw and the one action that is next.

Enforced (check): .github: cd commons/archon-dialect-native-pinned && bun run verify — suite/dialect.test.ts: failures name the tool, the step and the next action

Proved by: archon-dialect-native-pinned/suite/dialect.test.ts

Written in: archon-dialect-native-pinned/src/bin.ts

Tests: passed: suite/dialect.test.ts check changes nothing and says so by its status; apply installs; a second apply changes no; passed: suite/dialect.test.ts a wrong hash, a pin with no download and a plan that is not one are told with the step and

FR-006checkpassing

A tool that is as pinned in the store MUST be answered with no network and no write, so that a caller that asks for a tool only when it needs it pays nothing for one that is there.

Enforced (check): .github: cd commons/archon-dialect-native-pinned && bun run verify — suite/dialect.test.ts: a tool that is as pinned costs no request

Proved by: archon-dialect-native-pinned/suite/dialect.test.ts

Written in: archon-dialect-native-pinned/src/bin.ts, archon-dialect-native-pinned/src/observe.ts

Tests: passed: suite/dialect.test.ts Archon is given the desired state for a tool installed as pinned, a differing state for an; passed: suite/dialect.test.ts check changes nothing and says so by its status; apply installs; a second apply changes no

FR-007checkpassing

A tool whose pin has no download on the platform MUST be reported as such with the ontology's reason and MUST NOT be installed.

Enforced (check): .github: cd commons/archon-dialect-native-pinned && bun run verify — suite/dialect.test.ts: a pin with no download is told with its reason

Proved by: archon-dialect-native-pinned/suite/dialect.test.ts

Written in: archon-dialect-native-pinned/src/bin.ts

Tests: passed: suite/dialect.test.ts a wrong hash, a pin with no download and a plan that is not one are told with the step and

Acceptance scenarios

  1. Given the dialect, When its guarantees are read, Then they are the ones of FR-001 and the dialect of tools meets the control exact-hashed.
  2. Given a tool installed by the dialect, When it is observed, Then it is found in the store at its version, per FR-002.
  3. Given a program on the PATH that hangs when asked its version, When it is observed, Then it is reported unreadable within the limit and the run goes on, per FR-002.
  4. Given a plan, When check runs, Then nothing is written and the status says something would change, per FR-004.
  5. Given a plan, When apply runs twice, Then the second run changes nothing, per FR-004.
  6. Given a tool that is installed as pinned, When it is asked for, Then no connection is made and nothing is written, per FR-006.
  7. Given a pin with no download on the platform, When it is asked for, Then the reason is told and nothing is installed, per FR-007.

Out of scope

  • Installing the Archon way (an order and a plan of many requirements): the plan file holds only the tools; Archon orders them, per FR-003.
  • The manager dialects: packages of their own.

Edge cases

  • A program on the PATH at a version below the minimum: it does not count, per FR-002.
  • A store copy whose file was changed: it does not count and the tool is replaced, per FR-002.

Assumptions

  • Archon's plan says create, update or none for a tool requirement by comparing its desired state with what observe gives; observe gives the desired state itself for a tool that is installed as pinned.

Open questions

  • None.

Key entities

  • Dialect - the value of the port.
  • Plan file - the generated list of tools the program checks or applies.

Success criteria

SC-001success criterion

A tool that is there costs nothing to ask for.

SC-002success criterion

The dialect never installs a byte that is not the pinned artifact.

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

Native-pinned install

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