@tiphys/kernel 0.0.0 → 0.2.0

package/dist/src/gates/release.d.ts

@@ -0,0 +1,283 @@
+import type { GateStatus } from "./result.ts";
+import type { SchemaDocument } from "./validate.ts";
+/**
+ * THE RELEASE-VERIFICATION CONTRACT (kernel plan M2, M2-P7 step 3; DR-0014;
+ * delivery/verification/release-verification-interface.md).
+ *
+ * ONE post-merge verification contract with two registry entries (`deploy`
+ * and `migrations`). The kernel owns the SUBJECT, the CLOCK, the LOOP and
+ * the OUTCOME MAPPING; an adapter owns the platform mapping and nothing
+ * else. An adapter is an executable named by committed configuration,
+ * spawned as a subprocess with a request file path in argv, performing ONE
+ * bounded observation per invocation and writing its response to a
+ * kernel-supplied record path. It returns an OUTCOME, never a status path:
+ * JSON-pointer extraction exists only inside the http-json adapter's own
+ * configuration, and the kernel never learns what a statusPath is.
+ *
+ * WHY THE BOUNDARY IS A PROCESS (M2-D-07, investigation section 5): it
+ * works for any language, and it makes the per-attempt timeout ENFORCEABLE
+ * rather than promised. The kernel terminates an attempt that overruns
+ * (`spawnSync`'s `timeout` and `killSignal` options) and records that
+ * attempt as `error`, so an adapter that hangs cannot hang the kernel.
+ *
+ * C-2 EXEMPTION, STATED WHERE THE TERMINATION HAPPENS AND NOWHERE ELSE.
+ * C-2 forbids pid, process liveness, signals and /proc FOR IDENTITY OR
+ * EXCLUSION. The per-attempt termination above is neither: it is a timeout
+ * bound on a child this kernel itself spawned and still holds the handle
+ * of, it probes nothing, identifies nothing and excludes nothing, and no
+ * pid is ever read, recorded or compared. That is the one place any kill
+ * may appear in this module or its adapters, and it appears as a spawn
+ * option, not as a process.kill call.
+ *
+ * NO FAILURE VOCABULARY SHIPS (plan step 2, T-003 lesson 4). No
+ * non-success platform state was ever captured, so none is named anywhere
+ * in this module or its adapters. The safe rule instead: one satisfying
+ * value per configured adapter; every other observed value is recorded
+ * verbatim and treated as `pending` until the deadline, at which point it
+ * becomes red naming the last observed value. Unknown never becomes green.
+ *
+ * NEVER auto-background (C-3): the loop is a foreground await, every spawn
+ * is spawnSync, nothing is detached and nothing is unref'd.
+ */
+/** The one declaration path (design decision D-p7-1 in the work history). */
+export declare const DECLARATION_PATH = "release-verification.json";
+/** The contract versions this kernel accepts (fail-closed rule 6). */
+export declare const ACCEPTED_CONTRACT_VERSIONS: readonly string[];
+/**
+ * The subject: what the kernel knows for certain the moment a merge
+ * happens. Platform vocabulary (deployment id, workflow run id, migration
+ * set) is the adapter's, and the kernel never learns it.
+ */
+export interface ReleaseSubject {
+    repository: string;
+    integrationRef: string;
+    mergedSha: string;
+    mergedAt: string;
+    phaseId: string;
+}
+export declare const SUBJECT_FIELDS: readonly (keyof ReleaseSubject)[];
+/**
+ * The outcome vocabulary, six values. There is deliberately no `unknown`,
+ * no `skipped` and no `warn`: a soft state is where a false green hides
+ * (M2-C-3).
+ */
+export type VerificationOutcome = "satisfied" | "failed" | "pending" | "absent" | "not-applicable" | "error";
+export declare const VERIFICATION_OUTCOMES: readonly VerificationOutcome[];
+/**
+ * THE TOTAL MAPPING to GateResult status, implemented in exactly one place
+ * (plan step 3). `satisfied` is green with `units` 1 per verification
+ * satisfied (or the adapter's own examined count, D-p7-3). `pending` and
+ * `absent` are NEVER terminal: they are loop states, and the two entries
+ * below are reachable only through the deadline conversion in
+ * `runVerification`, which turns both into red with TEXTUALLY DISTINCT
+ * reasons: `deadline reached, last observed <value>` for pending and
+ * `deadline reached, no release object for subject` for absent. An adapter
+ * cannot make pending mean pass.
+ */
+export declare const OUTCOME_TO_STATUS: Readonly<Record<VerificationOutcome, GateStatus>>;
+export declare const DEADLINE_REASON_ABSENT = "deadline reached, no release object for subject";
+export declare function deadlineReasonPending(lastObserved: string): string;
+/** The kernel's clock. No defaults anywhere: the numbers are the project's. */
+export interface VerificationClock {
+    intervalMs: number;
+    deadlineMs: number;
+    attemptTimeoutMs: number;
+    maxAttempts?: number;
+}
+/** What the adapter wrote, after the seven rules accepted it. */
+export interface AdapterResponse {
+    contractVersion: string;
+    adapter: string;
+    subject: ReleaseSubject;
+    outcome: VerificationOutcome;
+    resolved?: {
+        kind: string;
+        id: string;
+        createdAt?: unknown;
+    } & Record<string, unknown>;
+    observedAt: string;
+    observation?: {
+        raw?: unknown;
+        detail: string;
+    };
+    reason?: string;
+    units?: number;
+    precondition?: {
+        id: string;
+        evidence?: string[];
+    };
+    transport?: {
+        httpStatus?: number;
+    };
+}
+/** One attempt's record: number, instant, outcome, identity, transport. */
+export interface AttemptRecord {
+    attempt: number;
+    at: string;
+    outcome: VerificationOutcome | "invalid";
+    detail: string;
+    resolved?: unknown;
+    transport: {
+        exitCode: number | null;
+        signal: string | null;
+        terminatedByTimeout: boolean;
+        httpStatus?: number;
+    };
+    /**
+     * The older-than-the-merge observation (investigation guarantee 9,
+     * section 8 item 8): recorded, deliberately NOT promoted to an error
+     * until one real counter-example settles whether a platform reuses or
+     * backdates a record on redeploy.
+     */
+    releaseObjectOlderThanMerge?: boolean;
+}
+export type VerificationVerdict = {
+    kind: "satisfied";
+    units: number;
+    detail: string;
+    resolved: unknown;
+} | {
+    kind: "failed";
+    reason: string;
+} | {
+    kind: "not-applicable";
+    declared: boolean;
+    reason: string;
+    preconditionId: string;
+    evidence: string[];
+} | {
+    kind: "error";
+    reason: string;
+} | {
+    kind: "deadline";
+    lastOutcome: "pending" | "absent";
+    reason: string;
+};
+export interface VerificationRun {
+    verdict: VerificationVerdict;
+    attempts: AttemptRecord[];
+    /** Paths relative to evidenceDir, in creation order. */
+    evidence: string[];
+}
+export declare function responseSchema(): SchemaDocument;
+export declare function declarationSchema(): SchemaDocument;
+/**
+ * THE SEVEN FAIL-CLOSED RULES on an adapter response (plan step 3), each
+ * corresponding to a way a verifier can be fooled. Rule 1 (exit 0 with no
+ * response written) is enforced by the caller, which owns the file's
+ * existence; rules 2 to 7 are here. The subject echo (rule 3) is checked
+ * field by field BEFORE the outcome is read, so an adapter that verified
+ * something else cannot have its outcome looked at for this subject.
+ */
+export type ResponseValidation = {
+    ok: true;
+    response: AdapterResponse;
+} | {
+    ok: false;
+    rule: number;
+    reason: string;
+};
+export declare function validateAdapterResponse(body: string, subject: ReleaseSubject): ResponseValidation;
+/**
+ * The encoded forms of a credential value the kernel can derive from the
+ * value alone (CR-P7H-3). Redacting only the verbatim bytes let a trivially
+ * reversible copy through: an adapter emitting the token as a standalone
+ * base64 blob (an HTTP Basic `Authorization: Basic <base64(token)>` of the
+ * token) leaked a recoverable secret into the stderr evidence. Each form here
+ * is a DETERMINISTIC, enumerable transform of the same value, so the set is
+ * bounded and cheap.
+ *
+ * WHAT THIS DOES NOT COVER, stated so a green is auditable rather than
+ * silently partial (never soften a work history): forms that fold in bytes
+ * the kernel does not hold, e.g. base64 of `"user:" + value` for a full Basic
+ * credential PAIR (the username is the project's, not the kernel's), or a
+ * value re-encoded by a transport the kernel never sees (gzip, hex, a second
+ * base64 round). Those are residue the reference adapters do not produce; a
+ * third-party adapter that composes a credential with unknown surrounding
+ * bytes owns that redaction, and the guarantee scoped here is the value and
+ * its own single-step base64 and percent encodings.
+ */
+export declare function secretForms(value: string): string[];
+/**
+ * Replace every resolved credential VALUE, and its enumerable encoded forms
+ * (see secretForms), with a named placeholder, everywhere in the text.
+ */
+export declare function redactSecrets(text: string, secrets: readonly {
+    name: string;
+    value: string;
+}[]): string;
+export interface RunVerificationOptions {
+    verification: string;
+    subject: ReleaseSubject;
+    adapter: string[];
+    config: unknown;
+    clock: VerificationClock;
+    /** Absolute directory the attempt evidence is written into. */
+    evidenceDir: string;
+    /** Resolved credential values, for redaction only. Never written. */
+    secrets?: readonly {
+        name: string;
+        value: string;
+    }[];
+}
+/**
+ * THE KERNEL-OWNED LOOP. One bounded adapter observation per attempt, one
+ * record per attempt, foreground polling (C-3), verdict at the deadline.
+ * `pending` and `absent` loop; everything else is terminal, including every
+ * fail-closed violation (design decision D-p7-5: a broken adapter cannot
+ * reach a verdict, and M2-C-3 makes that `error` now, not red later).
+ */
+export declare function runVerification(options: RunVerificationOptions): Promise<VerificationRun>;
+export interface DeclaredVerification {
+    mode: "none" | "adapter";
+    reason?: string;
+    adapter?: string[];
+    config?: unknown;
+    clock?: VerificationClock;
+    credentials?: string[];
+}
+export interface Declaration {
+    version: number;
+    repository: string;
+    integrationRef: string;
+    verifications: {
+        deploy?: DeclaredVerification;
+        migrations?: DeclaredVerification;
+    };
+}
+export type DeclarationLoad = {
+    ok: true;
+    declaration: Declaration;
+    /** sha256 hex of the blob bytes read from the governing ref. */
+    sha256: string;
+    /** The resolved commit sha of the governing ref. */
+    ref: string;
+    refSha: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Read the declaration from a COMMITTED ref, never from the working tree
+ * (design decision D-p7-2; the anti-widening rule of plan step 7, same as
+ * the scope auditor's: a phase must not be able to switch off, inside its
+ * own branch, the check that would have caught it). The record carries the
+ * declaration blob's sha256 so a reviewer can see which text authorized
+ * whatever happened.
+ */
+export declare function loadDeclaration(ref: string, cwd: string): DeclarationLoad;
+/**
+ * THE GATE ENTRY, shared by the two thin entry points. The manifest keeps
+ * two static entries exactly as section 1.4 declares them; this function is
+ * what each names. Returns the process exit code.
+ *
+ * The governing ref is `--base` when supplied (the anti-widening read),
+ * else HEAD: always a COMMITTED state, so the subject's mergedSha and
+ * mergedAt are the resolved commit's, and an uncommitted edit can neither
+ * enable, disable nor reconfigure a verification. R-032's blocking half:
+ * the verdict record this gate writes is keyed to that sha in its detail
+ * line, and the consumption contract is that THE NEXT DISPATCH REQUIRES A
+ * GREEN VERDICT RECORD FOR THE MERGED SHA; the enforcement is wired at M4
+ * with the pilot (M2-D-11), and M2 adds no dispatch block to spawn.
+ */
+export declare function runReleaseGate(name: "deploy" | "migrations", args: string[]): Promise<number>;