@tiphys/kernel 0.1.0 → 0.2.0

package/AGENTS.md

@@ -245,11 +245,30 @@ conversation memory is a cache and the files are the truth, and a cache that is
 never written back is lost at the next restart, which is a routine event and not
 an incident.
 
+HOW: `tiphys sync`, which is the mechanism this clause is discharged by. It is
+not a reminder to run git carefully. It enumerates what changed, asks git which
+of those paths the fleet `.gitignore` covers, commits exactly the rest, and
+pushes. The partition above is therefore DERIVED from the fleet's own ignore
+rules rather than from a reader's judgment about which of two files is durable,
+and a prefix added to that ignore set is honoured by the same derivation with
+no further edit anywhere.
+
+TWO THINGS IT REFUSES RATHER THAN GUESSES, because both are states where being
+helpful would be destructive. An ephemeral path that is ALREADY STAGED stops the
+run: git commits the index, not the pathspec it was handed, so committing at all
+would commit that path, and unstaging on your behalf is a change to work the
+command did not create. A fleet home with no remote stops the run BEFORE the
+commit, because the discipline is commit AND push and a command that did the
+first half here would have done the half that gets dropped and reported the half
+that does not.
+
 AND PUSHED, WHICH IS THE HALF THAT GETS DROPPED. Evidence that lives only on a
 long-lived side branch dies with that branch. Process paperwork reaches the
 default branch through a pull request like everything else, batched rather than
 one request per file, and it is not allowed to accumulate unpushed while the
-code it proves lands ahead of it.
+code it proves lands ahead of it. A failed push is a NONZERO exit carrying git's
+own first stderr line, never a warning printed beside a success: the work is
+committed locally and still owed to the remote, and you are the one who owes it.
 
 ## clause merge-authority: the declared mode says who signs, and for a delegated grant the signature is dual clean review
 
@@ -292,12 +311,45 @@ content of this clause: a ref update is a recorded, reversible act over reviewed
 commits, and a file edit is unreviewed work by the one role whose independence
 every later check assumes.
 
+WHICH MECHANISM ENFORCES IT, replacing nothing above. The clause was a sentence
+you were trusted to remember until M4-P9 shipped a `PreToolUse` hook for it. The
+hook draws exactly the line the two paragraphs above draw, and it draws it over
+the TARGET rather than over a tool name, because "designated merge tooling" has
+no referent in this kernel: a write resolving inside a project working tree and
+outside that clone's `.git/` is REFUSED, and a write under `.git/` is the ref
+update and is PERMITTED. Its refusal is an exit code, not a warning.
+
+THE HOTFIX CARVE-OUT IS A DECLARED ACT AND IT EXPIRES. When the pipeline is
+wedged and the fix has to be made in the tree, you write one declaration naming
+the project, the paths, the reason and an ABSOLUTE EXPIRY INSTANT, validated by
+`schemas/write-bypass.schema.json#properties.expiresAt`. Nothing about it is
+optional: a bypass with no expiry is a block switched off permanently by the
+first hotfix, which is why the expiry is required rather than encouraged. Every
+write it permits is appended to a separate evidence log, and NO DECISION EVER
+READS THAT LOG, which is constraint C-1 and is the reason the declaration and
+the evidence are two files rather than one.
+
+WHAT IT DOES NOT COVER, stated here because a partial guard read as a total one
+is worse than none. The hook adjudicates the file-writing tools. A shell command
+is NOT adjudicated, because the payload a shell tool call delivers carries the
+command string and no resolvable write target, which was measured rather than
+assumed. So the hook makes an accidental edit impossible and a deliberate one
+through a shell still yours to not do.
+
 ## clause fleet-resume-specification: what survives reclamation, what is rebuilt, and what doctor reports
 
 Assigned to this document by plan v1 PR-201. THIS CLAUSE IS A SPECIFICATION AND
-NOT A MECHANISM, and it says so at the top rather than reading as a description
-of something that runs. The machinery is deferred to a later milestone; what is
-settled here is what that machinery will have to do.
+NOT A MECHANISM: what is settled here is what the machinery has to do, and the
+commands that do it are named below rather than described here.
+
+WHICH PHASES DELIVERED IT, replacing the sentence that deferred the machinery to
+"a later milestone" and gave a reader no way to tell whether that milestone had
+arrived. `tiphys resume` (M4-P16) rebuilds the ephemeral half a clone does not
+carry, creating only what is absent and never removing anything. `tiphys sync`
+(M4-P18) commits and pushes the durable half, which is what makes "everything
+committed and pushed" below a reachable state rather than a hope. What remains
+deferred is the doctor reporting in the third paragraph, which is owned by its
+own phase; nothing else in this clause is waiting on a milestone.
 
 WHAT MUST SURVIVE a cloud fleet being reclaimed: everything committed and pushed
 under `fleet-state-commit-discipline` above. Nothing else is promised, and

package/assurance-modes.yaml

@@ -108,7 +108,8 @@ modes:
       blueprint section 8 (the mode and its pipeline); process doc section 9
       item 3 enumerated (R-096); T-003 for the fix-round-verification stage;
       DR-0012 and DR-0015 for the merge authority actually in force; DR-0016
-      for the escalation response; T-007 and D-M3-32 for the review contracts.
+      for the escalation response; DR-0035 for the fix-round ceiling; T-007 and
+      D-M3-32 for the review contracts.
     # ORDER IS LOAD-BEARING. R-024: an adversarial plan review happens before
     # anyone builds, which is a property of this sequence and not of its set,
     # and `mode-stage-order` is the check that says so.
@@ -193,8 +194,28 @@ modes:
         verdict.
     # DR-0012's two limits with DR-0016's response. DATA THE ORCHESTRATOR BRIEF
     # CITES, NOT AN ENFORCEMENT ENGINE: nothing in M3 counts fix rounds.
+    #
+    # THE FIX-ROUND NUMBER IS DR-0035'S CEILING OF 3, NOT DR-0012'S 2 (M4-P30).
+    # DR-0035 replaced the single bound with a table: the dial is the number of
+    # rounds between the clean-room reviewer and the implementer, and it runs
+    # from one round (a zero or small subject) to three (a large subject at
+    # high impact). A single integer cannot carry a table, so what this field
+    # records is the CEILING, which is the only reading under which the value
+    # is true of every phase rather than wrong for some of them. Writing 2 here
+    # made this file state a bound DR-0035 had already lifted, and the kernel's
+    # own charter had to go out of its way to avoid repeating it: charter.yaml
+    # names the BUDGET rather than a number precisely because the two documents
+    # disagreed. They no longer do.
+    #
+    # NOTHING READS THIS VALUE, and the derivation is published rather than
+    # asserted: `grep -rn 'max-fix-rounds-after-review' --include='*.ts'
+    # --include='*.mjs' src/ bin/ scripts/` returns zero hits, so no code path
+    # branches on it. The readers are this file's schema, the test that pins
+    # the shipped values, and `tiphys mode show`, which prints whatever is
+    # here. See delivery/work-history/m4-p30.md:1 for the full output and for
+    # the regions that derivation did NOT cover.
     escalation-bounds:
-      max-fix-rounds-after-review: 2
+      max-fix-rounds-after-review: 3
       recurrence-of-high-in-one-component: 1
       on-exceeded: fresh-implementer-and-third-contract
 

package/dist/bin/tiphys.js

@@ -1,14 +1,92 @@
 #!/usr/bin/env node
-import { EX_USAGE, run } from "../src/cli.js";
+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();
 }
-try {
-    process.exitCode = await run(process.argv.slice(2));
+/**
+ * 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;
+    });
 }
-catch (error) {
-    const usage = error?.usage === true;
-    const message = error instanceof Error ? error.message : String(error);
-    process.stderr.write(`tiphys: ${singleLine(message)}\n`);
-    process.exitCode = usage ? EX_USAGE : 1;
+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>;