instar 0.28.102 → 0.28.103

package/dist/remediation/Remediator.d.ts

@@ -0,0 +1,288 @@
+/**
+ * Remediator — Tier-1 orchestrator skeleton for the Self-Healing Remediator v2.
+ *
+ * SELF-HEALING-REMEDIATOR-V2-SPEC §A1 (F-8), §A2 (lock-bound co-existence),
+ * §A3 (RemediationContext as capability token), §A4 (deadline enforcement),
+ * §A6 (errorCode provenance — free-text rejected at registry-load),
+ * §A21 (verify-failed strict typing — distinct from verify-inconclusive),
+ * §A36 (essential-runbook validator), §A57 (Tier-1 subset).
+ *
+ * Scope of this PR (Tier-1 subset per A57):
+ *   - Match incoming `NormalizedDegradationEvent` against registered runbooks
+ *     using `eventPrefilter` (errorCode + provenance) and `match()`.
+ *   - Acquire in-flight `MachineLock` keyed by `tupleHash = sha256(runbookId +
+ *     signatureHash)`. Detect existing in-flight lock with same tuple →
+ *     `covered-by-inline`.
+ *   - Issue a `RemediationContext` carrying:
+ *       - attemptId (uuid),
+ *       - runbookId,
+ *       - lockHandle (from MachineLock),
+ *       - auditToken (leaf key from RemediationKeyVault, audit context),
+ *       - abortSignal wired to deadline via AbortController,
+ *       - expiresAt + monotonicDeadline.
+ *   - Declare intent via IntentJournal.
+ *   - Audit-append `started` + final outcome via AuditWriter.
+ *   - Enforce `expectedRuntimeMs` deadline. surfaceCallable that hangs past the
+ *     deadline trips the AbortController and yields `aborted-deadline`.
+ *   - On surfaceCallable success → call `runbook.verify(ctx)` and audit the
+ *     result with the verified taxonomy (A21).
+ *   - On surfaceCallable failure → audit `verify-failed` without calling
+ *     `verify()` (a failed surface cannot return a healthy outcome).
+ *
+ * Explicitly OUT of scope (Tier-2 per A57):
+ *   - Trust elevation source.
+ *   - Probe authentication.
+ *   - Capability token HMAC enforcement on the surface side.
+ *   - Supervisor handshake.
+ *   - Runbook registry validation against a signed manifest.
+ *
+ * Audit-token issuance per call uses `RemediationKeyVault.deriveLeafKey('audit',
+ * null)` (the audit context shares one machine-wide leaf per §A20). The actual
+ * verification of that token happens inside `AuditWriter.append()`'s injected
+ * `tokenVerifier` — the writer is the authority, the dispatcher merely issues.
+ */
+import type { NormalizedDegradationEvent } from '../monitoring/DegradationReporter.js';
+import type { ErrorProvenance } from '../monitoring/ErrorCodeExtractor.js';
+import type { RemediationKeyVault } from './RemediationKeyVault.js';
+import type { MachineLock, InFlightHandle } from './MachineLock.js';
+import type { IntentJournal } from './IntentJournal.js';
+import type { AuditWriter } from './audit/AuditWriter.js';
+import type { TrustElevationSource, RunbookTransition, CanTransitionContext } from './TrustElevationSource.js';
+import type { ServerSupervisor, RegisteredRemediator, RestartRequestedReply } from '../lifeline/ServerSupervisor.js';
+export type BlastRadius = 'process' | 'machine' | 'fleet';
+export type Reversibility = 'reversible' | 'irreversible';
+export interface RemediationContext {
+    attemptId: string;
+    runbookId: string;
+    lockHandle: InFlightHandle;
+    auditToken: Buffer;
+    abortSignal: AbortSignal;
+    /** Wall-clock expiry (informational; the monotonic deadline is authoritative). */
+    expiresAt: number;
+    /** `process.hrtime.bigint()` at issuance + expectedRuntimeMs converted to ns. */
+    monotonicDeadline: bigint;
+    /**
+     * §A3 capability-token HMAC over {attemptId, runbookId, expiresAt,
+     * monotonicDeadline}, signed with the per-runbook capability leaf. The
+     * surface MUST verify this via `verifyRemediationContext(ctx, keyVault)`
+     * before treating the call as Remediator-authorized.
+     *
+     * Optional on the type so unit tests that only need the structural shape
+     * (e.g. `RemediatorInvocationContext` in NativeModuleHealer) compile
+     * without re-deriving signatures. Production paths always set it.
+     */
+    hmac?: Buffer;
+}
+export interface ExecutionResult {
+    outcome: 'success' | 'failure';
+    details: Record<string, unknown>;
+}
+export interface VerifyOutcome {
+    outcome: 'verified-healthy' | 'verify-failed' | 'verify-inconclusive';
+    reason: string;
+}
+export interface ApprovedRunbook {
+    id: string;
+    priority: number;
+    surface: string;
+    /**
+     * §A6: provenance MUST NOT include `'free-text'`. Validator at
+     * registerRunbook() refuses such matchers.
+     */
+    eventPrefilter: {
+        errorCode: string[];
+        provenance: ErrorProvenance[];
+    };
+    match: (event: NormalizedDegradationEvent) => boolean;
+    preconditions: (event: NormalizedDegradationEvent) => Promise<boolean>;
+    surfaceCallable: (ctx: RemediationContext) => Promise<ExecutionResult>;
+    verify: (ctx: RemediationContext) => Promise<VerifyOutcome>;
+    blastRadius: BlastRadius;
+    reversibility: Reversibility;
+    expectedRuntimeMs: number;
+    /** §A36: only valid when blastRadius === 'machine'. */
+    essential?: boolean;
+}
+export type DispatchOutcome = {
+    outcome: 'no-matching-runbook';
+} | {
+    outcome: 'covered-by-inline';
+    existingAttemptId: string;
+} | {
+    outcome: 'verified-healthy';
+    attemptId: string;
+} | {
+    outcome: 'verify-failed';
+    attemptId: string;
+} | {
+    outcome: 'verify-inconclusive';
+    attemptId: string;
+} | {
+    outcome: 'aborted-deadline';
+    attemptId: string;
+};
+export interface RemediatorOptions {
+    stateDir: string;
+    keyVault: RemediationKeyVault;
+    machineLock: MachineLock;
+    intentJournal: IntentJournal;
+    auditWriter: AuditWriter;
+    /**
+     * HMAC signer/verifier pair used to sign the in-flight lock envelope. In
+     * production the dispatcher derives these from
+     * `keyVault.deriveLeafKey('inflight', surfaceId)` per-runbook. Tests inject
+     * a fixed pair for determinism. If omitted, the dispatcher derives the
+     * pair at acquire-time using the keyVault's `inflight` context.
+     */
+    lockSigner?: (payload: Buffer) => Buffer;
+    lockVerifier?: (payload: Buffer, signature: Buffer) => boolean;
+    /**
+     * F-5 trust-elevation source (Tier-2). When present, lifecycle-transition
+     * methods (e.g. promote/un-quarantine) consult it before mutating runbook
+     * state. Optional so existing Tier-1 tests + the Tier-1 dispatch path
+     * continue to work without wiring the source.
+     */
+    trustSource?: TrustElevationSource;
+    /**
+     * F-6 supervisor handshake (Tier-2). When present, the Remediator
+     * registers itself with the supervisor at construction and uses it to
+     * issue planned restarts via `requestPlannedRestart()` below.
+     */
+    serverSupervisor?: ServerSupervisor;
+    /**
+     * §A52 probe-source registry. Maps `probeId` → declared verify-scope
+     * (the list of subsystems the probe is allowed to report on) + the per-
+     * probe leaf-key verifier. Events whose provenance is `'probe-id'`
+     * MUST carry a signed envelope referencing a registered probe; events
+     * referencing an unregistered probe are routed to `audit-rejected.jsonl`.
+     *
+     * Tier-3 wires the full fleet; F-8-rest accepts the registry shape so
+     * one example probe (LifelineProbe) can flow end-to-end.
+     */
+    probeSourceRegistry?: ProbeSourceRegistry;
+}
+/**
+ * §A40 + §A52 — per-probe authentication + scope binding. Probes that
+ * emit `provenance: 'probe-id'` events MUST sign the envelope using their
+ * `probe`-context leaf key. The Remediator verifies the signature, then
+ * enforces that `event.subsystem ∈ scope` (the probe's declared
+ * `__verifyScope`).
+ */
+export interface ProbeSourceRegistry {
+    /**
+     * Returns the declared verify-scope for the given probeId. An empty
+     * scope means the probe has not been migrated to A52 enforcement
+     * (Tier-3 fleet work) — its events will be routed to audit-rejected
+     * on signed-probe-id flow.
+     */
+    getScope(probeId: string): ReadonlyArray<string>;
+    /**
+     * Verifies the signature on a probe-signed envelope. `probeId` selects
+     * the leaf key (derived from the `probe`-context). `body` is the
+     * canonical envelope bytes — see `canonicalProbeEnvelopeBody()` below.
+     *
+     * Returns `false` (never throws) for any verification failure: unknown
+     * probe, length mismatch, HMAC mismatch.
+     */
+    verify(probeId: string, body: Buffer, signature: Buffer): boolean;
+}
+/**
+ * §A40 probe-envelope signed payload. The probe emits this on the
+ * `NormalizedDegradationEvent`'s `source.probeSignature` field (additive —
+ * unset for legacy emit-sites and for non-probe provenances).
+ */
+export interface ProbeSignatureEnvelope {
+    probeId: string;
+    subsystem: string;
+    outcome: string;
+    reason: string;
+    /** Monotonic timestamp (Number from performance.now()) at probe-side issuance. */
+    monotonicTs: number;
+    /** HMAC over `canonicalProbeEnvelopeBody(envelope)` using the probe leaf key. */
+    signature: Buffer;
+}
+export declare class Remediator implements RegisteredRemediator {
+    private readonly opts;
+    private readonly runbooks;
+    /** Pending restart requestIds → resolver fns awaiting `onRestartComplete`. */
+    private pendingRestartResolvers;
+    private lastRestartRequestRunbookId;
+    constructor(opts: RemediatorOptions);
+    /**
+     * Per-runbook capability leaf key used to sign `restart-requested`
+     * payloads. The supervisor verifies via the SAME leaf because both sides
+     * share the F-1 keyVault.
+     */
+    getCapabilityLeafKey(): Buffer;
+    /**
+     * Supervisor → Remediator callback. Fires once per accepted
+     * `restart-requested` after the server recovers. Resolves any pending
+     * `requestPlannedRestart()` waiter.
+     */
+    onRestartComplete(req: {
+        requestId: string;
+    }): void;
+    /**
+     * Issue a planned restart through the F-6 handshake. Signs the payload
+     * with the capability leaf for `runbookId`, hands to the supervisor.
+     * Returns the supervisor's reply.
+     */
+    requestPlannedRestart(args: {
+        runbookId: string;
+        attemptId: string;
+        blastRadius: BlastRadius;
+    }): Promise<RestartRequestedReply | {
+        accepted: false;
+        reason: 'no-supervisor';
+    }>;
+    /**
+     * Consult the trust-elevation source for a lifecycle transition. When
+     * `trustSource` is unset, the Remediator falls back to `{allowed: true,
+     * reason: 'no-trust-source-wired'}` — Tier-1 behavior.
+     */
+    canTransition(runbookId: string, transition: RunbookTransition, context?: CanTransitionContext): Promise<{
+        allowed: boolean;
+        reason: string;
+    }>;
+    /**
+     * Register a runbook. Enforces §A6 (no free-text prefilter) and §A36
+     * (essential ⇒ blastRadius === 'machine'). Rejection throws.
+     */
+    registerRunbook(runbook: ApprovedRunbook): void;
+    /**
+     * Dispatch a normalized degradation event. Resolves to a `DispatchOutcome`
+     * describing the terminal state of the attempt (or the reason it never
+     * started).
+     *
+     * Note: this method never throws on policy-level rejections; it returns a
+     * structured outcome. It MAY throw on infrastructure failures (lock
+     * acquisition error, audit write error not classified as token-rejected).
+     */
+    dispatch(event: NormalizedDegradationEvent): Promise<DispatchOutcome>;
+    private matchRunbook;
+    private resolveLockKey;
+    private auditAppend;
+    private auditAppendNoAttempt;
+}
+/**
+ * §A40 canonical probe envelope serialization. Both the probe (signer) and
+ * the Remediator (verifier) MUST agree on this byte layout exactly.
+ *
+ *   tag | probeId* | subsystem* | outcome* | reason* | monotonicTs(u64be)
+ *
+ *   * = uint32be length prefix followed by utf-8 body.
+ */
+export declare function canonicalProbeEnvelopeBody(env: Pick<ProbeSignatureEnvelope, 'probeId' | 'subsystem' | 'outcome' | 'reason' | 'monotonicTs'>): Buffer;
+/**
+ * §A52 default `ProbeSourceRegistry` impl backed by a keyVault + a
+ * `probeId → __verifyScope` map. Production callers wire one of these at
+ * Remediator construction; tests can pass an inline stub.
+ */
+export declare class DefaultProbeSourceRegistry implements ProbeSourceRegistry {
+    private readonly keyVault;
+    private readonly scopes;
+    constructor(keyVault: Pick<RemediationKeyVault, 'deriveLeafKey'>, scopes: Record<string, ReadonlyArray<string>>);
+    getScope(probeId: string): ReadonlyArray<string>;
+    verify(probeId: string, body: Buffer, signature: Buffer): boolean;
+}
+//# sourceMappingURL=Remediator.d.ts.map

package/dist/remediation/Remediator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Remediator.d.ts","sourceRoot":"","sources":["../../src/remediation/Remediator.ts"],"names":[],"mappings":"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"}