@tiphys/kernel 0.0.0 → 0.2.0

package/checklists/plan-review.yaml

@@ -0,0 +1,103 @@
+# THE ADVERSARIAL PLAN-REVIEW CHECKLIST (kernel plan M3, M3-P7 step 2).
+#
+# Run against a PLAN, before any of it is dispatched. The three canonical
+# probes are R-026b, R-027 and R-028a, and each one is written to be
+# unanswerable without opening something: R-027 carries the process document's
+# own zero-amount-rows illustration, and R-028a names the artifact that counts
+# as proof so a testability claim cannot be admired instead of tested.
+kind: checklist
+id: plan-review
+applies-to: >-
+  a plan document before dispatch, read adversarially: the reviewer is looking
+  for the phase that cannot be built as written, not for reasons to approve.
+
+probes:
+  # R-026b. Hidden dependencies and semantic coupling ABOVE the file-overlap
+  # floor. File overlap is what the M5 pre-pass computes mechanically; this
+  # probe is the part no pre-pass reaches.
+  - id: hidden-dependency-above-file-overlap
+    probe: >-
+      Which phases share MEANING rather than files? Two phases with disjoint
+      file lists still collide when one renames a key the other reads, changes
+      a value's vocabulary, moves an ordering another relies on, or changes
+      what a shared registry row means. The file-overlap pre-pass computes the
+      floor and cannot see any of those. Name each pair you found, the shared
+      concept, and the phase whose assumption breaks; then name the pairs you
+      examined and cleared, because a list of collisions with no stated scope
+      is indistinguishable from a search that looked in the wrong place.
+    applies-to: plan-structure
+    evidence-required: true
+
+  - id: grounding-names-a-real-artifact
+    probe: >-
+      Does each phase's `grounding` name artifacts that will EXIST when it
+      starts, and does its `blocked-by` follow from that rather than from
+      habit? A `blocked-by` naming a phase whose artifacts the grounding never
+      mentions is an ordering habit serialising work that could run in
+      parallel; the reverse, a grounding consuming a phase the `blocked-by`
+      does not name, is a phase that will be dispatched before its inputs
+      exist. Check both directions per phase and say which you found.
+    applies-to: plan-structure
+    evidence-required: true
+
+  # R-027. Probe every fix shape for THE STATE THAT CAN NO LONGER EXIT, with
+  # the process document's own illustration carried in the probe text so the
+  # question cannot be answered from the phrase alone.
+  - id: fix-shape-state-that-cannot-exit
+    probe: >-
+      For every fix this plan proposes, what state does it create that can no
+      longer be exited? The process document's own illustration: a repair that
+      writes rows with a ZERO amount leaves records that are structurally
+      valid, that every later query counts, and that no reconciliation can
+      distinguish from real ones, so the system can enter that state and never
+      leave it. Walk each fix and name the state, the transition INTO it, and
+      the transition OUT of it. A fix with no stated exit is the finding.
+    applies-to: fix-shapes
+    evidence-required: true
+
+  - id: fix-shape-partial-application
+    probe: >-
+      What does each fix leave behind if it is interrupted halfway? Name the
+      point of no return in each one, and whether re-running it from the start
+      is safe. A fix that is only correct when it completes is a fix that has
+      not been designed for the case it exists to handle.
+    applies-to: fix-shapes
+    evidence-required: true
+
+  # R-028a. TEST THE TESTABILITY CLAIMS. The accepted evidence is the M2-P2
+  # red-witness harness's own evidence file, not the plan's assertion that
+  # something is testable.
+  - id: testability-claim-tested
+    probe: >-
+      For every claim in this plan that something is testable, guarded or
+      witnessed, what is the accepted proof? The harness's captured evidence
+      file (`witness-records.json`, whose per-member `runs[].exitCode` and
+      `failedNamedTests` record what actually ran) is the proof; the plan's
+      own sentence is not. Where no such file can exist yet because the
+      behaviour is not built, say so in those words and mark the claim as
+      owed, rather than letting an untested assertion pass as a tested one.
+    applies-to: testability
+    evidence-required: true
+
+  - id: acceptance-criterion-is-falsifiable
+    probe: >-
+      Is each acceptance criterion FALSIFIABLE? "Works correctly" is banned;
+      the register is a command, its exit code and a count ("node --test exits
+      0 and reports N tests, N greater than zero"). Quote every criterion that
+      names no command, no observable output and no count, and propose the
+      falsifiable form. A criterion nobody can fail is a criterion nobody has
+      to meet.
+    applies-to: testability
+    evidence-required: true
+
+  - id: hazard-class-is-not-the-criteria-reworded
+    probe: >-
+      Does each phase's declared hazard class name something its own
+      acceptance criteria CANNOT reach? T-007 records a phase meeting fifteen
+      of fifteen executed criteria while live-locking every supervision
+      command. A hazard class that is the criteria list reworded reproduces
+      that failure while appearing to fix it. For each class, name the
+      criterion that reaches it or state that none does and name the
+      instrument that does.
+    applies-to: plan-structure
+    evidence-required: true

package/dist/bin/tiphys.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/tiphys.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+import { run, usageLine } from "../src/cli.js";
+/**
+ * THE TOP-LEVEL ERROR PRESENTATION HANDLER (kernel plan M3, M3-P1 step 8b;
+ * D-M3-21).
+ *
+ * `delivery/STATE.md` carried this as an unowned seam: "clean presentation of
+ * a load-time configuration error ... a seam no M1 phase owns". M3-P1 owns it
+ * because M3-P1 is the first phase to add commands whose ordinary input is a
+ * HAND-AUTHORED FILE that will routinely be malformed, and a validator that
+ * answers malformed YAML with a stack trace is a validator nobody trusts
+ * (DR-0013 YAML clause 4).
+ *
+ * The rule: a thrown error from any subcommand is ONE diagnostic line on
+ * stderr and a nonzero exit. Never a stack trace, on either stream.
+ *
+ * THE DOCUMENTED USAGE-MARKING MECHANISM IS GONE, and its removal is the
+ * fix rather than the loss. This docblock used to promise that "an `Error`
+ * carrying `usage: true` exits 64", with an `UsageMarkedError` interface
+ * beside it, and a grep over `src/` and `bin/` found ZERO code that ever set
+ * the field: every command reaches EX_USAGE by returning it from its own
+ * handler. A comment describing a contract nothing implements is how the
+ * next implementer reaches for a mechanism that silently does nothing, so
+ * the branch and the sentence are removed together and `EX_USAGE` stays the
+ * value handlers return.
+ *
+ * SCOPE IS EXACTLY THIS HANDLER, THE HELP AFFORDANCE, AND EPIPE (D-M3-21
+ * plus the DR-0047 sweep's two CLI findings). Nothing else in this file
+ * changes, because a dispatcher is the last place to accumulate incidental
+ * edits.
+ */
+function singleLine(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+/**
+ * AN EXIT CODE MUST NOT CONTRADICT THE STATE THE COMMAND LEFT BEHIND.
+ *
+ * Measured before this handler existed: `tiphys lock acquire --duration 900 |
+ * head -1` printed the acquired line, exited 1 on an unhandled EPIPE, and
+ * left BOTH layers mutated, the local lease on disk and the shared register
+ * advanced to the next counter. A wrapper of the shape
+ * `if ! tiphys lock acquire | grep -q acquired` therefore took its failure
+ * branch while holding the fleet, which is the one wrong conclusion the
+ * exclusion commands must never produce.
+ *
+ * EPIPE ONLY, and that word is load-bearing. A consumer closing the pipe is
+ * not a failure of the command; any OTHER write error still surfaces, so
+ * this does not become a blanket swallow of output failures. Both streams
+ * are covered because a short consumer of stderr is the same hazard as a
+ * short consumer of stdout.
+ */
+function ignoreEpipe(stream) {
+    stream.on("error", (error) => {
+        if (error.code === "EPIPE") {
+            return;
+        }
+        throw error;
+    });
+}
+ignoreEpipe(process.stdout);
+ignoreEpipe(process.stderr);
+/**
+ * THE HELP AFFORDANCE (DR-0047 sweep, group cli, CR-F04).
+ *
+ * `tiphys --help` exited 64 with ZERO bytes on stdout and the usage line on
+ * stderr, so `tiphys --help | less` showed nothing, while this project's own
+ * evidence uses `tiphys --help` as a probe. That satisfied M1-P1 criterion 4
+ * to the letter, because `--help` is an unknown subcommand, and it is still
+ * the first thing a consumer types.
+ *
+ * The usage text is `usageLine()`, which src/cli.ts DERIVES from the dispatch
+ * table, so this cannot drift from the commands that exist. M1-P1 criterion
+ * 4's contract is untouched: an unknown subcommand still prints usage to
+ * STDERR with an EMPTY stdout and exit 64, and the help words alone print to
+ * STDOUT with exit 0.
+ */
+const HELP_WORDS = new Set(["--help", "-h", "help"]);
+const argv = process.argv.slice(2);
+if (argv.length === 1 && HELP_WORDS.has(argv[0])) {
+    process.stdout.write(`${usageLine()}\n`);
+    process.exitCode = 0;
+}
+else {
+    try {
+        process.exitCode = await run(argv);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`tiphys: ${singleLine(message)}\n`);
+        process.exitCode = 1;
+    }
+}

package/dist/src/adapters/load.d.ts

@@ -0,0 +1,202 @@
+import type { Fleet } from "../fleet.ts";
+import type { ExecutorAdapter } from "../spawn.ts";
+/**
+ * ADAPTER SELECTION AND LOADING (kernel plan M4, M4-P4; M4-D-03 at
+ * delivery/plan/m4-intake.md:729).
+ *
+ * THE RESOLUTION ROOT IS THE WHOLE SECURITY PROPERTY, and it is the reason
+ * this module exists rather than a one-line `await import(specifier)` at the
+ * spawn call site. Loading an adapter executes third-party code INSIDE the
+ * orchestrator process, the same process that holds delegated merge
+ * authority under DR-0012. DR-0029 Part 2c's untrusted-project-content
+ * boundary does not exist and M4-D-23 recommends it is not built in M4, so
+ * the only mitigation available is WHERE the code is resolved from:
+ *
+ *   - the FLEET HOME is owner-controlled and already pins `@tiphys/kernel`
+ *     exactly, which is what makes it a boundary at all;
+ *   - the PROJECT CLONE is the thing under review and may contain anything
+ *     a contributor pushed, including a `node_modules/` directory.
+ *
+ * So resolution is rooted at `<fleet home>/package.json` rather than at this
+ * module or at `process.cwd()`. A plain `await import(specifier)` resolves
+ * relative to THIS MODULE's URL, which is the kernel checkout, and
+ * `import.meta.resolve(specifier, parent)` silently ignores its second
+ * argument unless Node is started with `--experimental-import-meta-resolve`
+ * (measured on v26.6.0, 2026-09-17: the parent was ignored and the specifier
+ * resolved from the CALLER's file). Both of those are the shape this module
+ * refuses to be.
+ *
+ * THE ROOTING IS NOT BY ITSELF THE PROPERTY, AND THE SENTENCE THAT STOOD HERE
+ * SAID IT WAS (CR-B-004, re-raised as CR-F-CRED-002 and CH-002).
+ *
+ * Until this round this paragraph asserted, without qualification, that
+ * "NOTHING here ever consults the project clone". That is true of BARE
+ * specifiers, which is the only shape M4-P4 criterion 2's witness exercises:
+ * `createRequire` walks the fleet home and its PARENTS looking for
+ * `node_modules`, and the project clone sits BELOW the fleet home at
+ * `<fleet>/projects/<name>`, so no such walk reaches it. It was FALSE of the
+ * module. Measured at `ad2428b`, with a module in the project clone that drops
+ * a sentinel on import: a bare specifier did not evaluate it, an ABSOLUTE
+ * specifier did, and the fleet-relative `./projects/demo/evil.mjs` did,
+ * because a relative path does not walk up looking for `node_modules`, it
+ * walks DOWN the tree the rooting chose.
+ *
+ * The mechanism is a constraint that holds for one INPUT SHAPE, documented as
+ * holding for the module. Both halves are now checked against the RESOLVED
+ * REAL PATH, which is the only thing that describes where the code actually
+ * comes from, rather than against the specifier's spelling:
+ *
+ *   - a resolved path inside `<fleet>/projects/` is refused WHATEVER the
+ *     specifier's shape, because the project tree is the thing under review;
+ *   - a PATH-SHAPED specifier (absolute, or beginning `./` or `../`) whose
+ *     resolved path is outside the fleet home is refused, because an absolute
+ *     specifier can point anywhere and a relative one can climb out with
+ *     `../`. A BARE specifier is exempt from the second check only, because
+ *     `createRequire`'s parent walk legitimately finds a hoisted
+ *     `node_modules` above the fleet home, and refusing that would break an
+ *     ordinary install rather than a hazard.
+ *
+ * `realpathSync` is used for both, so a symlink planted inside the fleet home
+ * pointing into the project clone is refused by the same check rather than by
+ * a second one.
+ *
+ * WHAT IS STILL NOT DEFENDED, said here so the next reader does not re-derive
+ * it: an operator who types an absolute path INTO the fleet home gets what
+ * they typed, and the fleet home is owner-controlled by assumption. This moves
+ * the boundary to the fleet home for every specifier shape; it does not defend
+ * inside it.
+ *
+ * WHAT THIS MODULE DOES NOT DEFEND. Once a specifier resolves inside the
+ * fleet home, its code runs. A legitimate fleet-home adapter that is later
+ * compromised is not covered by anything here, and no criterion of this
+ * phase claims otherwise: this phase MOVES the boundary to the fleet home,
+ * it does not defend inside it. That residue is M4-D-23's, stated rather
+ * than implied.
+ */
+/**
+ * The built-in adapter's name, and the one name a loaded adapter may not
+ * claim (M4-P4 criterion 5).
+ *
+ * IT LIVES HERE RATHER THAN IN `src/spawn.ts` so that the runtime import
+ * edge runs one way only: `src/spawn.ts` imports this value, and this module
+ * imports nothing but a TYPE back. A value-level cycle between the launch
+ * module and the loader would evaluate one of them inside the other's
+ * temporal dead zone the first time an import order changed, which is a
+ * failure nothing in the suite would predict.
+ *
+ * The launch record's `adapter` field (src/spawn.ts:113) is the only thing
+ * that ever says what ran. A loaded adapter naming itself after the built-in
+ * one makes every later record ambiguous, and the ambiguity is unresolvable
+ * after the fact because the record is the only witness. This is the
+ * misattribution guard src/gates/schemas/release-record.schema.json:26
+ * already instantiates for release records, applied one layer down.
+ */
+export declare const BUILT_IN_ADAPTER_NAME = "subprocess";
+/**
+ * The fleet-home `package.json` field that names a default adapter, as a
+ * JSON pointer written out in the one place that reads it.
+ *
+ * `tiphys.adapter` rather than a top-level key: the kernel's own
+ * `package.json` already namespaces its configuration under `tiphys`
+ * (package.json:52), so a fleet home carrying kernel configuration uses the
+ * same namespace rather than inventing a second convention.
+ */
+export declare const FLEET_ADAPTER_FIELD = "tiphys.adapter";
+export type AdapterSelection = {
+    ok: true;
+    adapter: ExecutorAdapter | undefined;
+    origin: string;
+} | {
+    ok: false;
+    reason: string;
+};
+export type AdapterLoad = {
+    ok: true;
+    adapter: ExecutorAdapter;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * The specifier the fleet home declares as its default, if any.
+ *
+ * READ THROUGH `readRegularFileIfPresent`, never `readFileSync`: the fleet
+ * home is a directory this process does not own the contents of, and a FIFO
+ * at `package.json` would hang the spawn rather than refuse it. That is the
+ * hazard CR-520 records for `meta.json`, one path along.
+ *
+ * A fleet home with no `package.json`, no `tiphys` object, or no `adapter`
+ * key declares NOTHING, which is a different fact from declaring something
+ * unusable: the first yields `undefined` and the built-in default, the
+ * second is a refusal naming the field.
+ */
+export declare function fleetAdapterSpecifier(fleet: Fleet): {
+    ok: true;
+    specifier: string | undefined;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * THE CONTAINMENT RULES, applied to the RESOLVED REAL PATH (CR-F-CRED-002,
+ * CH-002). Exported so a test can drive both rules directly without staging a
+ * module on disk for every member; `loadAdapter` is the only caller in `src/`.
+ *
+ * Returns a refusal reason, or undefined to allow. Both rules name the
+ * resolved path, because an operator reading the refusal has to be able to see
+ * WHERE the specifier landed, which is precisely the thing the specifier's own
+ * spelling hides.
+ */
+export declare function refuseResolvedAdapterPath(fleet: Fleet, specifier: string, origin: string, resolved: string): string | undefined;
+export declare function loadAdapter(fleet: Fleet, specifier: string, origin: string): Promise<AdapterLoad>;
+/**
+ * IS THIS AN ADAPTER (M4-P4 criterion 4)?
+ *
+ * The three shapes the criterion names are three ways a module can be
+ * IMPORTABLE and not be an adapter, and each of them is silent at the import
+ * itself: a module with no default export, a default export with no `launch`,
+ * and a `launch` that is not callable. Left unchecked, the first two surface
+ * as `TypeError: adapter.launch is not a function` thrown out of `spawnTask`
+ * AFTER pool create has made a worktree, a branch and a pool record, which is
+ * the same "refusal that arrives as a crash, after creation" shape M4-P3's
+ * requirement checks exist to prevent (src/spawn.ts's checkAdapterRequirements).
+ *
+ * A FOURTH CHECK IS HERE THAT THE CRITERION DOES NOT NAME, and it is declared
+ * rather than smuggled: the adapter's `name` must be a non-empty string.
+ * Criterion 5 refuses one particular name, and `undefined` written into the
+ * launch record's `adapter` field would defeat the whole point of that
+ * criterion by making the record say nothing at all. A guard on the value of
+ * a field that may be absent is a guard that cannot go red for the absent
+ * case.
+ *
+ * Every refusal names the SPECIFIER and the member, because an operator
+ * reading it has a module to go and fix and needs to know which one.
+ */
+export declare function checkAdapterShape(module: unknown, specifier: string, origin: string, resolved: string): AdapterLoad;
+/**
+ * WHICH ADAPTER THIS SPAWN USES, AND WHY (M4-P4 criteria 1 and 6).
+ *
+ * WHICH SOURCE WINS, and it is explicit in the record rather than silent:
+ * the `--adapter` FLAG outranks the fleet-home default, and the fleet-home
+ * default outranks the built-in one.
+ *
+ * THE WORDING IS DELIBERATE AND IS NOT A STYLE CHOICE. The word this sentence
+ * would naturally use is claimed by four rows of
+ * delivery/plan/cutover/retirement-inventory.json, which assert that no kernel
+ * artifact states an authority order among charter, plan and decision records
+ * and enumerate BY NAME the `src/` files allowed to carry the token. A new
+ * file carrying it reddens `scripts/check-retirement-inventory.mjs`, correctly,
+ * because the checker cannot tell a benign use from a refuting one without a
+ * human reading it. This use is benign and incidental, so the token is not
+ * used here rather than the rows being widened from a phase that does not own
+ * that document. A flag is a per-spawn instruction and
+ * a fleet-home field is a standing one, so the narrower statement wins; the
+ * opposite order would make the flag unusable on any fleet that declared a
+ * default.
+ *
+ * `undefined` for the adapter means USE THE BUILT-IN ONE, and it is returned
+ * as `undefined` rather than as `subprocessAdapter` so that this module
+ * imports nothing but a type from `src/spawn.ts`. See BUILT_IN_ADAPTER_NAME
+ * above for why the import edge runs one way.
+ */
+export declare function selectAdapter(fleet: Fleet, flagSpecifier: string | undefined): Promise<AdapterSelection>;