@tiphys/kernel 0.0.0 → 0.2.0

package/dist/src/spawn.d.ts

@@ -0,0 +1,482 @@
+import type { ChildEnvExtension } from "./exec/env.ts";
+import type { Fleet } from "./fleet.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.
+ *
+ * Order, exactly as the plan states it: liveness-guard check (M1-P5; a
+ * documented no-op seam in this phase), holdership check, pool create,
+ * brief assembly, meta write, executor launch. The holdership check runs
+ * before pool create because its refusal must create nothing
+ * (criterion 12).
+ *
+ * Rollback contract, stated narrowly because the broad version would not
+ * be honest (the lesson M1-P3's destroy paid for four times over):
+ *
+ *   - A failure BEFORE pool create removes nothing, because nothing was
+ *     created. In particular a duplicate task id leaves any pre-existing
+ *     tasks/<id>/ byte-identical: this command writes nothing under
+ *     tasks/ until pool create has succeeded (criterion 4, PR-005).
+ *   - A failure AFTER pool create and BEFORE the payload starts removes
+ *     exactly what this invocation created (the files it wrote, the task
+ *     directory when it created it, and the pool worktree) and nothing
+ *     else (criterion 5). This holds for a step that RETURNS a failure
+ *     and for one that THROWS: every write in that window goes through
+ *     runStep, because an unwrapped raise walked past the rollback
+ *     entirely and orphaned the worktree, the branch and the pool record
+ *     (F-2). The worktree is untouched at that point, so
+ *     the removal passes the ordinary pool destroy gates and needs no
+ *     force flag: --discard and --delete-branch-force are deliberately
+ *     NOT passed, so a worktree that somehow is not pristine refuses and
+ *     survives rather than being destroyed by a cleanup path.
+ *   - Once the PAYLOAD HAS STARTED, nothing is ever rolled back. The
+ *     worktree may hold real work by then, and a cleanup that removed it
+ *     would be M1-P3's V-1 data-loss defect with a different name. A
+ *     failure after that point reports what happened and changes
+ *     nothing.
+ *
+ * Substrate: everything here is substrate-neutral except the executor,
+ * which sits behind ExecutorAdapter (DR-0007). M1 ships exactly one
+ * adapter, the local subprocess one.
+ */
+/** What the adapter is asked to do. Everything crosses as files and exit codes. */
+export interface ExecutorRequest {
+    taskId: string;
+    /** cwd for the payload: the task worktree. */
+    worktree: string;
+    /** argv of the payload, argv[0] being the program. */
+    command: string[];
+    /** Script the adapter invokes with the payload exit code when it exits. */
+    hookPath: string;
+    /** Where the adapter writes its launch record. */
+    recordPath: string;
+    /** Optional non-completion deadline in seconds (PR-207). */
+    deadlineSeconds: number | undefined;
+    /**
+     * The EXACT environment for BOTH children this launch produces: the
+     * payload and the turn-end hook (M2-P8, M2R-004 edit 4). Built by
+     * `buildChildEnv` (src/exec/env.ts): allowlisted names only, with the
+     * five credential-store pointers redirected to harness-owned paths.
+     * `undefined` means the children inherit the parent's environment
+     * UNCHANGED, and is only ever passed under `allowPrCredentials`, the
+     * 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.
+ */
+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
+ * contract is: write the launch record tasks/<id>/executor.json at
+ * launch, launch the payload in the task worktree, and ensure the
+ * turn-end file is written with the payload exit code on completion. All
+ * state crosses this boundary through files and exit codes, never
+ * through terminal inspection (FM-055: pane scraping is a race farm;
+ * FM-060: every toolbelt boundary is a subprocess with an exit code).
+ * A multiplexer-window adapter and a cloud-session adapter are further
+ * adapters against this same interface, not kernel changes (M4 era).
+ */
+export interface ExecutorAdapter {
+    readonly name: string;
+    /**
+     * 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 {
+    adapter: string;
+    launchedAt: string;
+    /**
+     * Absolute ISO-8601 instant by which the task must have completed,
+     * present only when --deadline was passed. Recorded as an instant
+     * rather than as the raw seconds so the M1-P5 watcher compares it
+     * against the clock directly, the way it already compares lease
+     * expiry, instead of re-deriving it from launchedAt. The plan fixes
+     * the field name and its optionality, not its units; this is the
+     * 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
+ * test's stub payload uses).
+ *
+ * The payload runs to COMPLETION before this returns: the kernel never
+ * 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
+ * exactly that distinction.
+ */
+export declare const subprocessAdapter: ExecutorAdapter;
+/**
+ * Liveness-guard seam (plan step 4). The guard itself is M1-P5 work; in
+ * this phase it is a documented no-op, so that P5 adds a body here
+ * rather than a new call site in the middle of the spawn sequence.
+ */
+export declare function livenessGuard(fleet: Fleet): GuardResult;
+/**
+ * Tokenise --exec. M1 supports a program plus plain arguments separated
+ * by whitespace; there is no shell and no quoting. Anything richer is an
+ * adapter's business (M4 era), not a string this kernel re-parses.
+ */
+export declare function parseExecCommand(command: string): string[];
+export interface SpawnOptions {
+    taskId: string;
+    project: string;
+    briefFile: string;
+    shape: TaskShape;
+    exec: string;
+    deadlineSeconds: number | undefined;
+    /** Passed straight through to pool create (EXT-F-03); see spawnTask. */
+    offline: boolean;
+    /**
+     * DECLARED ESCAPE HATCH from the credential scrub (M2-P8 criterion 1).
+     * When true, both children inherit the parent environment unchanged,
+     * including any pull-request-capable credential the parent holds. This
+     * exists for the orchestrator's own spawns, never for an implementer
+     * 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;
+    exitCode: number;
+}
+export type SpawnResult = {
+    ok: true;
+    value: SpawnSuccess;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * One spawn. See the module docs for the rollback contract.
+ *
+ * --offline is passed straight through to pool create and is the only
+ * way a fleet can reach an offline base. meta.baseOffline is then COPIED
+ * from the pool record the create returned, never recomputed from this
+ * flag: pool create attempts the fetch even under --offline and records
+ * offline false when it succeeds, so a spawn that trusted its own flag
+ * would mark a perfectly fetched base as offline (PR-212, and the
+ * provenance inversion measured as V-2 in M1-P3).
+ */
+export declare function spawnTask(fleet: Fleet, options: SpawnOptions): Promise<SpawnResult>;