@tiphys/kernel 0.1.0 → 0.2.0

package/dist/src/hooks.js

@@ -29,9 +29,71 @@ export function turnEndHookPath(fleet, taskId) {
 }
 /**
  * Generate the hook script. The turn-end path is baked in as a literal,
- * so the hook needs no fleet resolution and no environment at all.
+ * so the hook needs no fleet resolution.
+ *
+ * THE CHILD-OBSERVED POINTER RECORD (CR-B-001, the half that closes the hole
+ * rather than the half that stops mis-asserting it).
+ *
+ * `observeNames`, when given, is baked in as a literal array and the hook
+ * writes an `env` object holding what each of those names ACTUALLY IS in the
+ * environment the hook was launched with, or `null` where the name is unset.
+ * The kernel compares those against the harness-owned paths it handed over.
+ *
+ * WHY THIS IS STRONGER THAN AN ADAPTER'S REPORT AND WHY IT IS NOT PROOF.
+ * This script is written BY THE KERNEL and, for every adapter that honours
+ * the documented contract, runs in the SAME environment as the payload (the
+ * built-in adapter spreads the same `request.env` into both spawnSync calls,
+ * and M2R-004 edit 4 is the record of why a second unscrubbed launch is
+ * itself the leak). Against an adapter that does not invoke this script at
+ * all it proves nothing, and the record no longer says otherwise.
+ *
+ * THE COST SENTENCE THAT STOOD HERE IS WITHDRAWN, BECAUSE IT WAS REFUTED BY
+ * MEASUREMENT (CR-F-CRED-001, MEDIUM).
+ *
+ * It read: an adapter that quietly reverted `HOME` for the payload "has to
+ * revert it for the payload and NOT for the hook, which means launching two
+ * children with two different environments and is a substantially different
+ * act from passing a mutated copy once". Two children is one way to do it and
+ * it is not the cheap way. The cheap way is ONE child with the mutated
+ * environment plus a single `writeFileSync` of the turn-end path, which is
+ * STRICTLY LESS work than the honest path, because the honest path also
+ * spawns the hook. The turn-end path is handed to the adapter beside
+ * `hookPath`, and this generated script names it as a literal, so an adapter
+ * that never runs it can still produce a byte-identical record.
+ *
+ * WHY A NONCE DOES NOT CLOSE THIS, stated because it is the obvious repair and
+ * it was considered and refused rather than overlooked. Baking a per-task
+ * secret into this script and requiring it in the record moves the forgery
+ * from "know the path" to "read the file", and the adapter is HANDED the path
+ * of this file: it runs at the same uid, on the same filesystem, in a
+ * directory it must be able to read to invoke the hook at all. A guard whose
+ * condition the adversary can satisfy by reading one file is green and
+ * worthless, which is this repository's own recorded shape (T-008's
+ * postscript, the red-witness rule one level up). No artifact this script can
+ * write is unforgeable by a party that can read this script.
+ *
+ * So the repair is on the RECORD rather than on the check: the value is
+ * `turn-end-record`, it names the artifact the values were read from, and
+ * `CredentialHandoverRecord` (src/task.ts) says the artifact is
+ * adapter-reachable. A dishonest adapter is still not caught here, and that
+ * residue is declared at delivery/work-history/m4-p8.md item 3; what changed
+ * is that `meta.json` no longer positively asserts a child-side observation
+ * that no child made.
+ *
+ * The hook still reads no environment it was not told to read, and a hook
+ * generated with no `observeNames` behaves exactly as it did before.
  */
-export function renderTurnEndHook(turnEndFile) {
+export function renderTurnEndHook(turnEndFile, observeNames) {
+    const observing = observeNames !== undefined && observeNames.length > 0;
+    const envLines = observing
+        ? `const observed = {};
+for (const name of ${JSON.stringify([...observeNames])}) {
+  const value = process.env[name];
+  observed[name] = typeof value === "string" ? value : null;
+}
+record.env = observed;
+`
+        : "";
     return `#!/usr/bin/env node
 // Generated by tiphys spawn (kernel plan v1, M1-P4 step 3). Invoked by the
 // executor adapter when the payload command exits, with the payload's exit
@@ -46,16 +108,17 @@ if (!Number.isInteger(exitCode)) {
   );
   process.exit(64);
 }
-writeFileSync(
+const record = { endedAt: new Date().toISOString(), exitCode };
+${envLines}writeFileSync(
   ${JSON.stringify(turnEndFile)},
-  \`\${JSON.stringify({ endedAt: new Date().toISOString(), exitCode }, null, 2)}\\n\`,
+  \`\${JSON.stringify(record, null, 2)}\\n\`,
 );
 `;
 }
 /** Write the hook for a task and return its path. */
-export function writeTurnEndHook(fleet, taskId) {
+export function writeTurnEndHook(fleet, taskId, observeNames) {
     const path = turnEndHookPath(fleet, taskId);
-    writeFileSync(path, renderTurnEndHook(turnEndPath(fleet, taskId)), {
+    writeFileSync(path, renderTurnEndHook(turnEndPath(fleet, taskId), observeNames), {
         mode: 0o755,
     });
     return path;

package/dist/src/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * THE KERNEL'S PUBLIC ENTRY POINT (kernel plan M4, M4-P4 criteria 7 and 8).
+ *
+ * Until this phase `@tiphys/kernel` declared `bin` and nothing else
+ * (package.json:14): no `main`, no `exports`, no `types`, and no
+ * `src/index.ts`. A separately published plugin could therefore not import
+ * `ExecutorAdapter` at all, which made the executor seam unreachable from
+ * outside this repository however well the interface was written.
+ *
+ * WHAT IS PUBLISHED HERE IS A COMMITMENT AND IS DELIBERATELY SMALL. An
+ * `exports` map is a semver promise and a patch release cannot take one back,
+ * so this file names the adapter CONTRACT and nothing else. In particular it
+ * does not export `spawnTask`, the fleet accessors, the gate runner or
+ * anything under `src/exec/`: those are the kernel's internals, they change
+ * without notice, and `package.json`'s `exports` map has no wildcard subpath
+ * precisely so that they stay unreachable through the package name
+ * (criterion 8, whose dangerous state is an `exports` map written
+ * `"./*": "./dist/src/*"`, which satisfies criterion 7 and publishes the
+ * entire kernel as API).
+ *
+ * THE TWO VALUES ARE PART OF THE CONTRACT, not a convenience. An adapter
+ * author has to answer two questions that types cannot answer at runtime:
+ * which names may appear in `requires` (the closed set the kernel checks
+ * against, src/spawn.ts's `requirableRequestFields`), and which name is
+ * reserved for the built-in adapter (`BUILT_IN_ADAPTER_NAME`, refused by the
+ * loader). Publishing the answers is cheaper than publishing a document that
+ * drifts from them.
+ */
+export type { ExecutorAdapter, ExecutorRecord, ExecutorRequest, LaunchOutcome, } from "./spawn.ts";
+export { requirableRequestFields } from "./spawn.ts";
+export { BUILT_IN_ADAPTER_NAME } from "./adapters/load.ts";

package/dist/src/index.js

@@ -0,0 +1,30 @@
+/**
+ * THE KERNEL'S PUBLIC ENTRY POINT (kernel plan M4, M4-P4 criteria 7 and 8).
+ *
+ * Until this phase `@tiphys/kernel` declared `bin` and nothing else
+ * (package.json:14): no `main`, no `exports`, no `types`, and no
+ * `src/index.ts`. A separately published plugin could therefore not import
+ * `ExecutorAdapter` at all, which made the executor seam unreachable from
+ * outside this repository however well the interface was written.
+ *
+ * WHAT IS PUBLISHED HERE IS A COMMITMENT AND IS DELIBERATELY SMALL. An
+ * `exports` map is a semver promise and a patch release cannot take one back,
+ * so this file names the adapter CONTRACT and nothing else. In particular it
+ * does not export `spawnTask`, the fleet accessors, the gate runner or
+ * anything under `src/exec/`: those are the kernel's internals, they change
+ * without notice, and `package.json`'s `exports` map has no wildcard subpath
+ * precisely so that they stay unreachable through the package name
+ * (criterion 8, whose dangerous state is an `exports` map written
+ * `"./*": "./dist/src/*"`, which satisfies criterion 7 and publishes the
+ * entire kernel as API).
+ *
+ * THE TWO VALUES ARE PART OF THE CONTRACT, not a convenience. An adapter
+ * author has to answer two questions that types cannot answer at runtime:
+ * which names may appear in `requires` (the closed set the kernel checks
+ * against, src/spawn.ts's `requirableRequestFields`), and which name is
+ * reserved for the built-in adapter (`BUILT_IN_ADAPTER_NAME`, refused by the
+ * loader). Publishing the answers is cheaper than publishing a document that
+ * drifts from them.
+ */
+export { requirableRequestFields } from "./spawn.js";
+export { BUILT_IN_ADAPTER_NAME } from "./adapters/load.js";

package/dist/src/lock.d.ts

@@ -51,9 +51,19 @@
  *
  * Exclusion domain (PR-201, DR-0007 stated honestly): the lease excludes
  * within one filesystem and one clock, the fleet home the lock file lives
- * in. Cross-environment exclusion for a fleet shared through a git remote
- * is M4 residue and is not claimed here. Mutations of the lock file made
- * outside this module (manual edits) are not covered by the contract.
+ * in. Mutations of the lock file made outside this module (manual edits)
+ * are not covered by the contract.
+ *
+ * CROSS-ENVIRONMENT EXCLUSION IS A SECOND LAYER ABOVE THIS ONE (M4-P21),
+ * and it is OFF unless the fleet home declares it. When the fleet's own
+ * `package.json` carries `tiphys.sharedExclusion`, every mutation below
+ * first asks `src/exclusion.ts` for a verdict from the shared register on
+ * the fleet's git remote, and only a won verdict reaches the local lease.
+ * With the field ABSENT, `readSharedExclusion` returns before spawning
+ * anything and every path in this module behaves exactly as it did, which
+ * is the property M4-P21 criterion 1 asserts. The refusal never touches the
+ * lock file, which is what makes the fail-closed behaviour on an
+ * unreachable register observable (criterion 7): no local lease appears.
  *
  * Renewal discipline (PR-203): the default lease lasts 900 seconds and
  * the holder renews at or before half-life (renewByMs). Holdership on
@@ -77,15 +87,39 @@ export type ObservedLease = {
     raw: string;
     lease: Lease | undefined;
 };
+/**
+ * What the shared exclusion layer decided. Present only when the fleet home
+ * declares the layer; the CLI prints `line` verbatim, and `line` always
+ * names which of the two staleness bases reached the verdict, which is
+ * M4-P21 criterion 6.
+ *
+ * THE VERDICT IS CARRIED AS TEXT ON PURPOSE, not as a discriminated field.
+ * The C-2 structural inspection over this file (test/lock.test.ts:534,
+ * M1-P3 criterion 10) forbids a whole vocabulary of process-probing words
+ * from `src/lock.ts`, and it is a blunt case-insensitive grep, which is the
+ * property that makes it hard to defeat by accident. Naming the field after
+ * that vocabulary would have reddened it for a reason that has nothing to do
+ * with C-2, and widening the grep to let this through would weaken a guard
+ * this module is the whole reason for. The classification itself lives in
+ * `src/exclusion.ts`, which no such grep covers, and any caller needing it
+ * as a value reads it there.
+ */
+export interface SharedNote {
+    line: string;
+    envId: string;
+}
 export type LeaseOutcome = {
     ok: true;
     lease: Lease;
+    shared?: SharedNote;
 } | {
     ok: true;
     lease: null;
+    shared?: SharedNote;
 } | {
     ok: false;
     reason: string;
+    shared?: SharedNote;
     /**
      * True when the operation failed because a mutation claim file
      * was still present after the bounded wait (CR-204). A stale
@@ -97,8 +131,40 @@ export type LeaseOutcome = {
     claimTimeout?: boolean;
 };
 export declare function renderLease(lease: Lease): string;
-/** Read the current lock file state: absent, or present with raw bytes. */
+/**
+ * Read the current lock file state: absent, or present with raw bytes.
+ *
+ * THE ENTRY TYPE IS ESTABLISHED BEFORE THE OPEN (T-008's shape in shipped
+ * code). A bare `readFileSync` here blocked FOREVER with zero output on a
+ * named pipe at the lease path, and took `lock status`, `lock acquire`,
+ * `lock renew` and `lock release` with it, while `tiphys doctor` returned in
+ * the same second against the same FIFO with "is a named pipe, not a regular
+ * file, so it was not opened". Two readers of one path, one of which
+ * established the type; this is now the same reader.
+ *
+ * A refusal THROWS rather than returning a fourth `ObservedLease` variant.
+ * The function already threw on every non-ENOENT error, so the contract its
+ * callers were written against is unchanged, and bin/tiphys.ts turns the
+ * throw into one diagnostic line and a nonzero exit.
+ */
 export declare function observeLease(lockPath: string): ObservedLease;
+/**
+ * THE ONE EXPIRY COMPARISON IN THE KERNEL (M4-P17 criterion 2).
+ *
+ * `isExpired` below needs a whole `Lease`, and doctor's lock check does not
+ * have one: it reads the lease file defensively and holds only `holderId` and
+ * `expiresAt`, because a lease file that fails `parseLease` must still produce
+ * a diagnosis rather than nothing. Before this phase that forced doctor to
+ * carry its own `Date.parse(...) <= Date.now()`, which is a SECOND comparison
+ * of the same property, free to drift from this one. The boundary is where
+ * that drift shows: `<=` makes expiry INCLUSIVE, so a lease whose `expiresAt`
+ * is exactly the current millisecond is expired, and a second copy written
+ * with `<` disagrees for exactly one millisecond and agrees everywhere else.
+ * A disagreement that narrow is not something a reviewer finds by reading.
+ *
+ * So the comparison lives here once and both callers reach it.
+ */
+export declare function expiryHasPassed(expiresAt: string, nowMs: number): boolean;
 export declare function isExpired(lease: Lease, nowMs: number): boolean;
 /** The renew-by deadline (half-life of the current term), for holders. */
 export declare function renewByMs(lease: Lease): number;
@@ -126,6 +192,12 @@ export interface AcquireOptions {
     takeover?: boolean;
     durationSeconds?: number;
     nowMs?: number;
+    /**
+     * The fleet home this lock belongs to. Derived from lockPath when absent;
+     * named explicitly only by callers whose lock path is not the fleet's
+     * canonical one.
+     */
+    fleetRoot?: string;
     /**
      * Staging seam for deterministic race witnesses: the decision is made
      * against this pre-observed state instead of a fresh read, and the
@@ -142,6 +214,8 @@ export declare function acquireLease(lockPath: string, options?: AcquireOptions)
 export interface RenewOptions {
     durationSeconds?: number;
     nowMs?: number;
+    /** See AcquireOptions.fleetRoot. */
+    fleetRoot?: string;
     /** Staging seam for deterministic race witnesses; see AcquireOptions. */
     observed?: ObservedLease;
 }
@@ -156,6 +230,10 @@ export declare function renewLease(lockPath: string, holderId: string, options?:
 export interface ReleaseOptions {
     /** Staging seam for deterministic race witnesses; see AcquireOptions. */
     observed?: ObservedLease;
+    /** See AcquireOptions.fleetRoot. */
+    fleetRoot?: string;
+    /** Decision clock, for the shared layer. Defaults to Date.now(). */
+    nowMs?: number;
 }
 /**
  * Release the lease held by holderId. Expiry does not block a release