@tiphys/kernel 0.1.0 → 0.2.0

package/dist/src/spawn.d.ts

@@ -1,5 +1,6 @@
+import type { ChildEnvExtension } from "./exec/env.ts";
 import type { Fleet } from "./fleet.ts";
-import type { GuardResult, TaskMeta, TaskShape } from "./task.ts";
+import type { CredentialHandoverRecord, GuardResult, PayloadClass, TaskMeta, TaskShape } from "./task.ts";
 /**
  * tiphys spawn (kernel plan v1, M1-P4 step 4): worktree, brief, turn-end
  * hook, task meta and the executor launch in ONE command.
@@ -62,7 +63,155 @@ export interface ExecutorRequest {
      * declared escape hatch; an adapter must never widen it on its own.
      */
     env: Record<string, string> | undefined;
+    /**
+     * THE ASSEMBLED BRIEF, and it is NOT optional (M4-P3 criterion 1).
+     *
+     * The brief is the agent payload's entire input, and until this phase the
+     * request did not carry it at all, although the call site already had it:
+     * `assembleBrief` returns the path and `spawnTask` pushes it onto
+     * `createdFiles` before the launch. So an optional `briefPath` would be an
+     * optionality the kernel never exercises, which is a field that cannot go
+     * red: every production path supplies it and no test could construct the
+     * absent case without inventing one.
+     *
+     * The three fields below it are `string | undefined` for the opposite
+     * reason: nothing in the kernel produces them, they arrive from the caller,
+     * and an adapter that needs one says so through `requires` rather than
+     * hoping.
+     */
+    briefPath: string;
+    /**
+     * The role the payload is being asked to play, verbatim as the caller named
+     * it. The kernel neither interprets it nor holds a vocabulary for it; the
+     * role briefs are a shipped artifact and the mapping from a role to a brief
+     * is the plugin's business.
+     */
+    role: string | undefined;
+    /**
+     * THE DECLARED TIER, VERBATIM, AND NEVER A MODEL NAME (M4-P3, the
+     * zero-vendor-names requirement). Whatever `role-model-config.yaml`
+     * declares, `strongest` or `cheaper` or anything else, crosses this seam
+     * unaltered. The tier-to-model mapping lives in the plugin: a mapping in
+     * `src/` is what would close off every harness that is not the one it names
+     * (delivery/plan/m4-intake.md:377).
+     */
+    declaredTier: string | undefined;
+    /**
+     * The delivery phase this task belongs to, CARRIED and never DERIVED.
+     *
+     * The scope gate derives a phase id from a branch name, and M4-D-22 leaves
+     * open whether that convention is the kernel's or the delivering project's.
+     * A kernel that derived the phase id from a branch here would settle
+     * M4-D-22 by accident, and a shipped constant is the hardest kind of
+     * decision to renumber.
+     */
+    phaseId: string | undefined;
 }
+/** The closed set of names an adapter may name in `requires`, in field order. */
+export declare function requirableRequestFields(): readonly string[];
+/**
+ * THE ADAPTER CONTRACT CHECK (M4-P3 criterion 3): a requirement naming a
+ * field that does not exist is a DEFECT IN THE ADAPTER, refused when the
+ * adapter is taken up and before anything is created.
+ *
+ * IT IS A DIFFERENT QUESTION FROM `checkAdapterRequirements` BELOW, AND THE
+ * ORDER IS LOAD-BEARING. The presence test there answers "is this field
+ * absent", and an unknown key is absent too, so a single check written that
+ * way would answer a defect in the adapter with a message about a missing
+ * flag: an operator would go looking for a `--modelName` that the kernel has
+ * no field for and could never accept. Running this one FIRST is what keeps
+ * the two answers distinct, and `test/spawn.test.ts` asserts that they say
+ * structurally different things rather than merely both refusing.
+ */
+export declare function checkAdapterContract(adapter: ExecutorAdapter): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * THE DECLARED-REQUIREMENT CHECK (M4-P3 criterion 2): a field the adapter
+ * declared it needs, and the spawn was not given, is a USAGE ERROR, and a
+ * usage error creates nothing.
+ *
+ * THE DANGEROUS STATE THIS EXISTS FOR is not "an adapter gets undefined". It
+ * is an adapter DISCOVERING that it got undefined, and raising, after pool
+ * create has already made a worktree, a branch and a pool record. That is the
+ * measured `--deadline` defect at src/commands/spawn.ts:81 with a new field:
+ * a value the kernel could not represent used to raise inside the adapter,
+ * after the creation, and the repair was to refuse at parse time. This is the
+ * same repair one field along, and it is the reason the check runs at the top
+ * of `spawnTask` rather than beside the launch where the request is built.
+ */
+export declare function checkAdapterRequirements(adapter: ExecutorAdapter, options: SpawnOptions): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * THE CREDENTIAL POLICY CHECK (M4-P8 steps 2, 3 and 5), and it runs before
+ * ANYTHING is resolved, loaded or created.
+ *
+ * Three refusals, in this order, and the order is the fail-closed one:
+ *
+ *   1. an absent or unrecognised `payloadClass`. Checked first so that
+ *      refusal 2 never has to reason about an unknown value: without this,
+ *      `payloadClass !== "project"` would read an omission as permission.
+ *   2. the declared escape hatch asked for on a PROJECT payload. This is
+ *      the pairing the phase exists to refuse: `allowPrCredentials` hands
+ *      the parent environment over UNCHANGED (see ExecutorRequest.env),
+ *      credentials and all, and M2-P8 criterion 1 wrote it for the
+ *      orchestrator's own spawns only. Until this phase the option was
+ *      reachable from the library seam with nothing between it and a
+ *      project payload.
+ *   3. an extension entry the child must not carry, which is the same
+ *      vocabulary check `buildChildEnv` makes, made EARLIER. The
+ *      duplication is deliberate and is not two implementations: both call
+ *      `refuseExtraAllowlist`. Making it here as well is what keeps a
+ *      rejected widening from costing a worktree, a branch and a pool
+ *      record, because `buildChildEnv` does not run until after pool
+ *      create.
+ *
+ * It returns a reason rather than throwing, because every refusal on this
+ * path must be able to say "nothing was created" in the same sentence.
+ */
+export declare function checkCredentialPolicy(options: SpawnOptions): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Pointer evidence: what the five credential-store redirections actually
+ * were where the payload ran, and where that observation came from.
+ */
+export interface RedirectionEvidence {
+    source: "turn-end-record" | "adapter";
+    /** Observed value per name; `null` for a name that was unset. */
+    values: Readonly<Record<string, string | null>>;
+}
+/**
+ * COMPARE THE HANDOVER (M4-P8 criterion 6, repaired for CR-B-001).
+ *
+ * `handed` is what the kernel built and passed, `reported` is the name set
+ * the adapter says it launched with, `pointers` is what the five
+ * CREDENTIAL_STORE_REDIRECTIONS actually were where the payload ran.
+ *
+ * TWO PROPERTIES, AND THE STATUS SAYS WHICH WERE CHECKED. The name-set
+ * comparison alone used to be written down as `compared`, which an operator
+ * reads as "the handover was verified"; an adapter that keeps the name set
+ * byte-identical and puts `HOME` and `XDG_CONFIG_HOME` back to their real
+ * paths defeats the M2R-004 defense entirely and was recorded as clean. See
+ * `CredentialHandoverRecord` for the five status values and for why the
+ * VALUES are still never written into the record.
+ *
+ * The pointer comparison is by value and the values are DISCARDED: only the
+ * names that differ survive into `changedRedirections`. A name the kernel
+ * never handed over is not compared, because there is no handed value to
+ * compare it against, and the name-set arms are what speak to that case.
+ */
+export declare function compareHandover(handed: Record<string, string> | undefined, reported: readonly string[] | undefined, pointers?: RedirectionEvidence): CredentialHandoverRecord;
 /**
  * Launch outcomes. The distinction between a payload that never started
  * and one that did is load-bearing: only the first authorizes rollback.
@@ -70,12 +219,53 @@ export interface ExecutorRequest {
 export type LaunchOutcome = {
     kind: "completed";
     exitCode: number;
+    /**
+     * THE NAMES THE ADAPTER REPORTS IT ACTUALLY LAUNCHED WITH (M4-P8
+     * criterion 6). Optional, and the optionality is honest rather than
+     * lenient: an adapter written before this phase reports nothing, and
+     * a kernel that refused every silent adapter would be refusing on an
+     * absence of evidence. What the kernel DOES refuse is a reported set
+     * that DIFFERS from the one it handed over, which is the adapter
+     * saying, in its own record, that it widened the environment.
+     *
+     * It is NOT on `ExecutorRecord`: that document has a shipped schema
+     * with `additionalProperties: false`, and this value is a report to
+     * the kernel rather than a durable launch fact for an operator.
+     *
+     * A DISHONEST ADAPTER IS NOT CAUGHT HERE, and nothing in this field
+     * pretends otherwise: an adapter that widens `env` and reports the
+     * kernel's set is caught by the child-written probe instead, which
+     * is why criterion 5 asserts on a file the CHILD wrote.
+     */
+    launchedEnvNames?: readonly string[];
+    /**
+     * THE FIVE CREDENTIAL-STORE POINTERS AS THE ADAPTER LAUNCHED THEM
+     * (CR-B-001). Optional for the same honest reason `launchedEnvNames`
+     * is, and WEAKER than the kernel's own evidence: it is the adapter's
+     * word about its own behaviour. The kernel prefers the turn-end record
+     * the generated hook normally writes and falls back to this, and the
+     * record says which ARTIFACT it read (`redirectionSource`). That is a
+     * weaker claim than which PARTY observed the values, and it used to be
+     * spelled as the stronger one; see CredentialHandoverRecord in
+     * src/task.ts for the measurement that changed the word.
+     */
+    launchedRedirections?: Readonly<Record<string, string | null>>;
 } | {
     kind: "launch-failed";
     reason: string;
 } | {
     kind: "incomplete";
     reason: string;
+    /**
+     * WHAT AN ADAPTER THAT COULD NOT CONFIRM COMPLETION STILL LAUNCHED
+     * WITH (CR-B-003). The payload RAN on this arm, so the handover is a
+     * real question here and the kernel now asks it; before this round the
+     * comparison sat after the `incomplete` return and `meta.json` carried
+     * no `handover` key at all, so a widening on this arm was recorded
+     * nowhere. Optional for the same reason as on the `completed` arm.
+     */
+    launchedEnvNames?: readonly string[];
+    launchedRedirections?: Readonly<Record<string, string | null>>;
 };
 /**
  * The ExecutorAdapter interface (DR-0007, M1-P4 grounding). The ENTIRE
@@ -90,7 +280,40 @@ export type LaunchOutcome = {
  */
 export interface ExecutorAdapter {
     readonly name: string;
-    launch(request: ExecutorRequest): LaunchOutcome;
+    /**
+     * WHAT THIS ADAPTER CANNOT LAUNCH WITHOUT (M4-P3 criteria 2 and 3).
+     *
+     * Every name is a field of `ExecutorRequest`. The kernel cannot know what
+     * a given adapter needs, so the adapter DECLARES it and the kernel refuses
+     * BEFORE it creates anything, rather than handing over an `undefined` that
+     * the adapter discovers once a worktree, a branch and a pool record exist.
+     *
+     * REQUIRED, never optional: an optional declaration would let an adapter
+     * omit it and get the old behaviour back silently, which is the thing this
+     * field exists to stop. An adapter that needs nothing declares `[]`, and
+     * that is a statement rather than a default.
+     */
+    readonly requires: readonly string[];
+    /**
+     * ASYNCHRONOUS since M4-P2. An agent turn is long and a subprocess is
+     * short: a window adapter or a cloud-session adapter cannot express
+     * "the turn ended" in a synchronous return, so the signature that only
+     * ever fitted the local subprocess case is the one that changes.
+     *
+     * This is NOT permission to background (constraint C-3). The kernel
+     * AWAITS this promise inside `spawnTask`, so the command still ends
+     * after the payload does; awaiting a call is not outliving it, and
+     * delivery/plan/kernel-plan-v1.md:311 already puts process ownership in
+     * the harness rather than the kernel.
+     *
+     * The three-armed outcome is unchanged and is still the whole contract:
+     * only `launch-failed` authorises rollback, because only `launch-failed`
+     * asserts that the payload never started. An adapter that cannot tell
+     * returns `incomplete` and the kernel touches nothing. What DID change
+     * is that `completed` is no longer taken on the adapter's word: see the
+     * completion precondition in `spawnTask`.
+     */
+    launch(request: ExecutorRequest): Promise<LaunchOutcome>;
 }
 /** The launch record (JSON per DR-0006, shape per PR-207). */
 export interface ExecutorRecord {
@@ -106,6 +329,25 @@ export interface ExecutorRecord {
      * choice, recorded rather than assumed.
      */
     deadline?: string;
+    /**
+     * WHAT WAS REQUESTED, NOT WHAT WAS RESOLVED (M4-P3 criterion 6).
+     *
+     * The declared tier the request carried, copied verbatim. Optional in the
+     * same sense `deadline` is: present exactly when the request carried one,
+     * absent otherwise, never the string "undefined".
+     *
+     * THERE IS NO RESOLVED MODEL HERE, and the absence is a decision rather
+     * than an omission. This record is written BEFORE the payload starts,
+     * which is the whole basis of the launch-failed-versus-incomplete
+     * distinction, while a harness that requests one model and is served
+     * another resolves mid-turn. A resolved model in a launch record would
+     * therefore be a value nobody could have observed at the moment it was
+     * written. M4-P7 carries the resolved half, at turn end, where it can be
+     * true.
+     */
+    requestedTier?: string;
+    /** The role the request carried, copied verbatim. See `requestedTier`. */
+    requestedRole?: string;
 }
 /**
  * The local subprocess adapter, the one M1 ships (and the one the exit
@@ -115,6 +357,13 @@ export interface ExecutorRecord {
  * auto-backgrounds anything (plan constraint C-3, FM-054), so there is
  * no daemonize path here to forget to guard.
  *
+ * `async` since M4-P2, and its BODY IS UNCHANGED: every statement below
+ * is still synchronous, `spawnSync` is still what runs both children, and
+ * the promise this now returns is already settled by the time the first
+ * `await` on it runs. The keyword is there because the INTERFACE is async
+ * for the adapters that need it, not because this adapter gained a
+ * concurrency path to get wrong.
+ *
  * It runs without a shell on purpose. Under a shell a missing payload
  * binary arrives as an ordinary exit code 127, indistinguishable from a
  * payload that ran and failed, and spawn's rollback rule turns on
@@ -150,7 +399,63 @@ export interface SpawnOptions {
      * payload; default is false and the scrub is on.
      */
     allowPrCredentials?: boolean;
+    /**
+     * WHOSE AUTHORITY THIS PAYLOAD RUNS UNDER (M4-P8 step 2). REQUIRED, and
+     * there is NO DEFAULT anywhere on this path, in the type or at runtime.
+     *
+     * A default would be the whole defect: `allowPrCredentials` is reachable
+     * from the library seam, which is where the plugin sits, and the pairing
+     * this field exists to refuse is the escape hatch on a project payload.
+     * If omission meant "orchestrator", a caller would acquire the
+     * orchestrator's authority by leaving a field out, which is the quietest
+     * way there is to reach a credential. `spawnTask` therefore refuses an
+     * absent or unrecognised value before it creates or loads anything,
+     * rather than trusting the type: TypeScript is a compile-time promise and
+     * the consumer that matters here is a JavaScript plugin.
+     */
+    payloadClass: PayloadClass;
+    /**
+     * PER-INVOCATION ALLOWLIST EXTENSIONS, EACH WITH THE REASON IT WAS
+     * GRANTED (M4-P8 step 3). Absent means none, which is the measured
+     * minimum for model authentication in the probed container
+     * (delivery/verification/m4-prototype-probes.md:33).
+     *
+     * The reason is DATA and a blank one is refused, so a widening cannot be
+     * granted without leaving behind something a later reader can check; the
+     * granted set is copied into meta.json verbatim. The kernel refuses any
+     * entry naming a variable in the walked gh-token or dangerous vocabulary,
+     * so this field cannot be used to re-admit a credential.
+     */
+    extraAllowlist?: readonly ChildEnvExtension[];
+    /**
+     * The three caller-supplied request fields (M4-P3 criterion 1, M4-D-05).
+     * Each is `string | undefined` because nothing in the kernel produces one;
+     * `briefPath` is not here because `assembleBrief` does produce it.
+     */
+    role: string | undefined;
+    declaredTier: string | undefined;
+    phaseId: string | undefined;
+    /**
+     * AN ADAPTER OBJECT SUPPLIED DIRECTLY, which only the kernel's own tests
+     * do. It outranks `adapterSpecifier` because it is not a request to
+     * resolve anything: there is nothing to root, nothing to load, and no
+     * trust boundary to cross.
+     */
     adapter?: ExecutorAdapter;
+    /**
+     * THE `--adapter` SPECIFIER, verbatim as the operator typed it (M4-P4
+     * criterion 1). `undefined` means the flag was absent, which is NOT the
+     * same as an empty one: an absent flag falls through to the fleet home's
+     * declared default and then to the built-in adapter, and each of those
+     * three outcomes is named in the launch record rather than being silent
+     * (criterion 6).
+     *
+     * The specifier is not resolved here. It is handed to `selectAdapter`,
+     * which roots Node module resolution at the FLEET HOME and never at the
+     * project clone; see src/adapters/load.ts for why that root is the whole
+     * security property of this phase.
+     */
+    adapterSpecifier?: string;
 }
 export interface SpawnSuccess {
     meta: TaskMeta;