instar 1.3.894 → 1.3.896

package/dist/core/FailureEpisodeLatch.d.ts

@@ -33,6 +33,12 @@ export interface FailureRecord {
     /** Consecutive failures including this one. */
     failures: number;
 }
+export interface FailureEpisodeSnapshot {
+    schemaVersion: 1;
+    failingSince: number | null;
+    failures: number;
+    signaledFor: number | null;
+}
 export declare class FailureEpisodeLatch {
     private readonly signalAfterMs;
     private readonly now;
@@ -46,5 +52,7 @@ export declare class FailureEpisodeLatch {
         recovered: boolean;
         failures: number;
     };
+    snapshot(): FailureEpisodeSnapshot;
+    restore(snapshot: FailureEpisodeSnapshot): void;
 }
 //# sourceMappingURL=FailureEpisodeLatch.d.ts.map

package/dist/core/FailureEpisodeLatch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FailureEpisodeLatch.d.ts","sourceRoot":"","sources":["../../src/core/FailureEpisodeLatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,WAAW,uBAAuB;IACtC,qEAAqE;IACrE,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,iEAAiE;IACjE,cAAc,EAAE,OAAO,CAAC;IACxB,uFAAuF;IACvF,YAAY,EAAE,OAAO,CAAC;IACtB,oCAAoC;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IAKnC,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,QAAQ,CAAK;IACrB,oFAAoF;IACpF,OAAO,CAAC,WAAW,CAAuB;gBAE9B,IAAI,EAAE,uBAAuB;IAKzC,aAAa,IAAI,aAAa;IAc9B,aAAa,IAAI;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE;CAQ1D"}
+{"version":3,"file":"FailureEpisodeLatch.d.ts","sourceRoot":"","sources":["../../src/core/FailureEpisodeLatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,WAAW,uBAAuB;IACtC,qEAAqE;IACrE,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,iEAAiE;IACjE,cAAc,EAAE,OAAO,CAAC;IACxB,uFAAuF;IACvF,YAAY,EAAE,OAAO,CAAC;IACtB,oCAAoC;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,aAAa,EAAE,CAAC,CAAC;IACjB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IAKnC,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,QAAQ,CAAK;IACrB,oFAAoF;IACpF,OAAO,CAAC,WAAW,CAAuB;gBAE9B,IAAI,EAAE,uBAAuB;IAKzC,aAAa,IAAI,aAAa;IAc9B,aAAa,IAAI;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE;IASzD,QAAQ,IAAI,sBAAsB;IAIlC,OAAO,CAAC,QAAQ,EAAE,sBAAsB,GAAG,IAAI;CAWhD"}

package/dist/core/FailureEpisodeLatch.js

@@ -55,5 +55,19 @@ export class FailureEpisodeLatch {
         this.signaledFor = null;
         return { recovered, failures };
     }
+    snapshot() {
+        return { schemaVersion: 1, failingSince: this.failingSince, failures: this.failures, signaledFor: this.signaledFor };
+    }
+    restore(snapshot) {
+        const finiteNullable = (value) => value === null || (typeof value === 'number' && Number.isFinite(value) && value >= 0);
+        if (snapshot?.schemaVersion !== 1 || !finiteNullable(snapshot.failingSince) || !Number.isInteger(snapshot.failures) || snapshot.failures < 0 ||
+            !finiteNullable(snapshot.signaledFor) || (snapshot.signaledFor !== null && snapshot.signaledFor !== snapshot.failingSince) ||
+            (snapshot.failingSince === null && snapshot.failures !== 0) || (snapshot.failingSince !== null && snapshot.failures === 0)) {
+            throw new Error('invalid FailureEpisodeLatch snapshot');
+        }
+        this.failingSince = snapshot.failingSince;
+        this.failures = snapshot.failures;
+        this.signaledFor = snapshot.signaledFor;
+    }
 }
 //# sourceMappingURL=FailureEpisodeLatch.js.map

package/dist/core/FailureEpisodeLatch.js.map

@@ -1 +1 @@
-{"version":3,"file":"FailureEpisodeLatch.js","sourceRoot":"","sources":["../../src/core/FailureEpisodeLatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAmBH,MAAM,OAAO,mBAAmB;IACb,aAAa,CAAS;IACtB,GAAG,CAAe;IACnC,4EAA4E;IAC5E,uEAAuE;IACvE,0EAA0E;IAC1E,oDAAoD;IAC5C,YAAY,GAAkB,IAAI,CAAC;IACnC,QAAQ,GAAG,CAAC,CAAC;IACrB,oFAAoF;IAC5E,WAAW,GAAkB,IAAI,CAAC;IAE1C,YAAY,IAA6B;QACvC,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC;QACxC,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;IAClC,CAAC;IAED,aAAa;QACX,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,cAAc,GAAG,IAAI,CAAC,YAAY,KAAK,IAAI,CAAC;QAClD,IAAI,IAAI,CAAC,YAAY,KAAK,IAAI;YAAE,IAAI,CAAC,YAAY,GAAG,GAAG,CAAC;QACxD,IAAI,CAAC,QAAQ,EAAE,CAAC;QAChB,MAAM,YAAY,GAAG,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC;QAC7C,IAAI,YAAY,GAAG,KAAK,CAAC;QACzB,IAAI,YAAY,IAAI,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,WAAW,KAAK,IAAI,CAAC,YAAY,EAAE,CAAC;YACjF,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,YAAY,CAAC;YACrC,YAAY,GAAG,IAAI,CAAC;QACtB,CAAC;QACD,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC;IACjF,CAAC;IAED,aAAa;QACX,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC/B,MAAM,SAAS,GAAG,QAAQ,GAAG,CAAC,CAAC;QAC/B,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QACzB,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;QAClB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;QACxB,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC;IACjC,CAAC;CACF"}
+{"version":3,"file":"FailureEpisodeLatch.js","sourceRoot":"","sources":["../../src/core/FailureEpisodeLatch.ts"],"names":[],"mappings":"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"}

package/dist/core/SelfHealGate.d.ts

@@ -0,0 +1,148 @@
+import { type FailureEpisodeSnapshot } from './FailureEpisodeLatch.js';
+import type { Admission, AdmissionToken, AdmitOpts, DerivedTarget } from '../monitoring/selfaction/types.js';
+export type SelfHealSeverity = 'recoverable' | 'irreversible' | 'data-loss' | 'security' | 'unknown';
+export type SelfHealEvidenceCode = 'source-absent' | 'schema-stale' | 'repaired' | 'already-healthy' | 'malformed-json' | 'access-denied' | 'io-error' | 'symlink-refused' | 'non-regular-refused' | 'sqlite-busy' | 'fence-stale' | 'verification-failed';
+export type SelfHealRemediationResult = {
+    outcome: 'healed' | 'pending-restart' | 'not-healed';
+    evidence: SelfHealEvidenceCode;
+};
+type NoticeReason = 'unknown-severity' | 'irreversible' | 'data-loss' | 'security' | 'latency' | 'max-attempts' | 'wall-clock' | 'flap' | 'state-failure';
+type NoticeState = {
+    state: 'pending' | 'enqueued';
+    id: string;
+};
+type RestartState = {
+    state: 'required' | 'requested';
+    requestingBootId: string;
+    stableRequestId: string;
+};
+export interface SelfHealNotice {
+    id: string;
+    controllerId: string;
+    reason: NoticeReason;
+    priority: 'HIGH' | 'URGENT';
+}
+export interface SelfHealAuditEvent {
+    at: number;
+    controllerId: string;
+    event: string;
+    reason?: string;
+    attempt?: number;
+    elapsedMs?: number;
+}
+export interface SelfHealSpec<Ctx> {
+    id: string;
+    controllerResource: 'hardware-bound' | 'pool-shared';
+    episodeAuthority: 'process-local' | 'durable-machine-local';
+    classId: string;
+    severity(ctx: Ctx): SelfHealSeverity;
+    dedupeKey(ctx: Ctx): string;
+    eligible(ctx: Ctx): {
+        eligible: boolean;
+        fence: string | null;
+    };
+    remediation(ctx: Ctx): SelfHealRemediationResult;
+    maxAttempts: number;
+    maxWallClockMs: number;
+    backoffMs(attempt: number): number;
+    notificationLatencyCeilingMs: number;
+    flap: {
+        maxRecoveries: number;
+        windowMs: number;
+    };
+    remediationActions: {
+        operation: string;
+        idempotencyGuard: string;
+        compensation: string;
+    };
+    restartVerified?(ctx: Ctx): boolean;
+}
+export type SelfHealResult = {
+    outcome: 'healed' | 'attempted' | 'backoff' | 'busy' | 'governed' | 'exhausted' | 'invalid-severity' | 'state-failure';
+    reason: string;
+    noticeAttempted?: boolean;
+    noticeReason?: NoticeReason;
+    tokenValid?: boolean;
+};
+export interface SelfHealEpisodeRecord {
+    schemaVersion: 1;
+    key: string;
+    revision: number;
+    status: 'active' | 'recovered' | 'exhausted';
+    startedAt: number;
+    attempts: number;
+    nextEligibleAt: number;
+    latch: FailureEpisodeSnapshot;
+    notices: Partial<Record<NoticeReason, NoticeState>>;
+    recoveries: number[];
+    restart: RestartState | null;
+    updatedAt: number;
+}
+export interface SelfHealEpisodeStore {
+    load(key: string): SelfHealEpisodeRecord | null;
+    create(record: SelfHealEpisodeRecord): SelfHealEpisodeRecord | null;
+    mutate(key: string, expectedRevision: number, update: (record: SelfHealEpisodeRecord) => SelfHealEpisodeRecord, guard?: () => boolean): SelfHealEpisodeRecord | null;
+    appendAudit?(event: SelfHealAuditEvent): void;
+    close?(): void;
+}
+export declare class InMemorySelfHealEpisodeStore implements SelfHealEpisodeStore {
+    private readonly rows;
+    readonly audits: SelfHealAuditEvent[];
+    load(key: string): SelfHealEpisodeRecord | null;
+    create(record: SelfHealEpisodeRecord): SelfHealEpisodeRecord | null;
+    mutate(key: string, expectedRevision: number, update: (record: SelfHealEpisodeRecord) => SelfHealEpisodeRecord, guard?: () => boolean): SelfHealEpisodeRecord | null;
+    appendAudit(event: SelfHealAuditEvent): void;
+}
+export declare class SqliteSelfHealEpisodeStore implements SelfHealEpisodeStore {
+    private readonly db;
+    private readonly unregisterSqlite;
+    constructor(dbPath: string);
+    load(key: string): SelfHealEpisodeRecord | null;
+    create(record: SelfHealEpisodeRecord): SelfHealEpisodeRecord | null;
+    mutate(key: string, expectedRevision: number, update: (record: SelfHealEpisodeRecord) => SelfHealEpisodeRecord, guard?: () => boolean): SelfHealEpisodeRecord | null;
+    appendAudit(event: SelfHealAuditEvent): void;
+    close(): void;
+}
+export interface SelfHealGateDeps {
+    admit(target: DerivedTarget, opts: AdmitOpts): Promise<Admission>;
+    consumeToken(token: AdmissionToken, controllerId: string, opts: {
+        targetKey: string;
+        nowMs: number;
+    }): {
+        proceed: boolean;
+        valid: boolean;
+        reason?: string;
+    };
+    notify(notice: SelfHealNotice): void | Promise<void>;
+    audit(event: SelfHealAuditEvent): void;
+    now?: () => number;
+    episodeStore?: SelfHealEpisodeStore;
+    bootId?: string;
+    requestRestart?: (stableRequestId: string) => boolean;
+}
+export declare class SelfHealGate<Ctx> {
+    private readonly spec;
+    private readonly deps;
+    private readonly now;
+    private readonly store;
+    private readonly bootId;
+    private readonly stateFailureNotices;
+    constructor(spec: SelfHealSpec<Ctx>, deps: SelfHealGateDeps);
+    needsRestartVerification(ctx: Ctx): boolean;
+    attempt(ctx: Ctx): Promise<SelfHealResult>;
+    recordHealthy(ctx: Ctx): SelfHealResult;
+    private attemptInner;
+    private runAdmitted;
+    private requestPendingRestart;
+    private ensureNotice;
+    private noticeAndReturn;
+    private exhaust;
+    private stateFailure;
+    private stateFailureWithNotice;
+    private key;
+    private newEpisode;
+    private cas;
+    private audit;
+}
+export {};
+//# sourceMappingURL=SelfHealGate.d.ts.map

package/dist/core/SelfHealGate.d.ts.map

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

package/dist/core/SelfHealGate.js

@@ -0,0 +1,391 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import Database from 'better-sqlite3';
+import { FailureEpisodeLatch } from './FailureEpisodeLatch.js';
+import { registerSqliteHandle } from './SqliteRegistry.js';
+function cloneRecord(record) { return structuredClone(record); }
+function validateRecord(value) {
+    if (!value || typeof value !== 'object')
+        throw new Error('invalid self-heal episode');
+    const r = value;
+    if (r.schemaVersion !== 1 || typeof r.key !== 'string' || r.key.length < 1 || r.key.length > 240)
+        throw new Error('invalid self-heal episode');
+    for (const n of [r.revision, r.startedAt, r.attempts, r.nextEligibleAt, r.updatedAt])
+        if (!Number.isFinite(n) || n < 0)
+            throw new Error('invalid self-heal episode');
+    if (!Number.isInteger(r.revision) || !Number.isInteger(r.attempts) || !['active', 'recovered', 'exhausted'].includes(r.status))
+        throw new Error('invalid self-heal episode');
+    if (!Array.isArray(r.recoveries) || r.recoveries.length > 64 || r.recoveries.some((n) => !Number.isFinite(n) || n < 0))
+        throw new Error('invalid self-heal episode');
+    const latch = new FailureEpisodeLatch({ signalAfterMs: 1 });
+    latch.restore(r.latch);
+    return r;
+}
+export class InMemorySelfHealEpisodeStore {
+    rows = new Map();
+    audits = [];
+    load(key) { const row = this.rows.get(key); return row ? cloneRecord(row) : null; }
+    create(record) { if (this.rows.has(record.key))
+        return null; const row = validateRecord(cloneRecord(record)); this.rows.set(row.key, row); return cloneRecord(row); }
+    mutate(key, expectedRevision, update, guard) {
+        const current = this.rows.get(key);
+        if (!current || current.revision !== expectedRevision)
+            return null;
+        if (guard && !guard())
+            return null;
+        const next = validateRecord(update(cloneRecord(current)));
+        if (next.key !== key || next.revision !== expectedRevision + 1)
+            throw new Error('self-heal mutation must increment revision once');
+        if (current.status === 'exhausted' && next.status !== 'exhausted')
+            throw new Error('self-heal exhausted state is monotonic');
+        this.rows.set(key, cloneRecord(next));
+        return cloneRecord(next);
+    }
+    appendAudit(event) { this.audits.push(structuredClone(event)); }
+}
+export class SqliteSelfHealEpisodeStore {
+    db;
+    unregisterSqlite;
+    constructor(dbPath) {
+        const parent = path.dirname(dbPath);
+        fs.mkdirSync(parent, { recursive: true, mode: 0o700 });
+        const ps = fs.lstatSync(parent);
+        if (!ps.isDirectory() || ps.isSymbolicLink())
+            throw new Error('unsafe self-heal store parent');
+        if (fs.existsSync(dbPath)) {
+            const st = fs.lstatSync(dbPath);
+            if (!st.isFile() || st.isSymbolicLink())
+                throw new Error('unsafe self-heal store file');
+        }
+        this.db = new Database(dbPath, { timeout: 100 });
+        this.db.pragma('journal_mode = WAL');
+        this.db.pragma('busy_timeout = 100');
+        this.db.exec('CREATE TABLE IF NOT EXISTS self_heal_episodes (episode_key TEXT PRIMARY KEY, revision INTEGER NOT NULL, payload TEXT NOT NULL, updated_at INTEGER NOT NULL); CREATE TABLE IF NOT EXISTS self_heal_audit (id INTEGER PRIMARY KEY, at_ms INTEGER NOT NULL, controller_id TEXT NOT NULL, event TEXT NOT NULL, reason TEXT, attempt INTEGER, elapsed_ms INTEGER);');
+        try {
+            fs.chmodSync(dbPath, 0o600);
+        }
+        catch { /* non-posix */ }
+        this.unregisterSqlite = registerSqliteHandle(() => { try {
+            this.db.close();
+        }
+        catch { /* already closed */ } });
+    }
+    load(key) { const row = this.db.prepare('SELECT payload FROM self_heal_episodes WHERE episode_key=?').get(key); return row ? validateRecord(JSON.parse(row.payload)) : null; }
+    create(record) {
+        const row = validateRecord(cloneRecord(record));
+        const tx = this.db.transaction(() => {
+            const count = this.db.prepare('SELECT COUNT(*) AS n FROM self_heal_episodes').get().n;
+            if (count >= 256)
+                return false;
+            return this.db.prepare('INSERT OR IGNORE INTO self_heal_episodes(episode_key,revision,payload,updated_at) VALUES(?,?,?,?)').run(row.key, row.revision, JSON.stringify(row), row.updatedAt).changes === 1;
+        });
+        try {
+            return tx() ? cloneRecord(row) : null;
+        }
+        catch (error) {
+            if (/busy|locked/i.test(String(error)))
+                return null;
+            throw error;
+        }
+    }
+    mutate(key, expectedRevision, update, guard) {
+        const tx = this.db.transaction(() => {
+            const current = this.load(key);
+            if (!current || current.revision !== expectedRevision)
+                return null;
+            if (guard && !guard())
+                return null;
+            const next = validateRecord(update(cloneRecord(current)));
+            if (next.key !== key || next.revision !== expectedRevision + 1)
+                throw new Error('self-heal mutation must increment revision once');
+            if (current.status === 'exhausted' && next.status !== 'exhausted')
+                throw new Error('self-heal exhausted state is monotonic');
+            const changed = this.db.prepare('UPDATE self_heal_episodes SET revision=?,payload=?,updated_at=? WHERE episode_key=? AND revision=?').run(next.revision, JSON.stringify(next), next.updatedAt, key, expectedRevision).changes;
+            return changed === 1 ? next : null;
+        });
+        try {
+            const row = tx();
+            return row ? cloneRecord(row) : null;
+        }
+        catch (error) {
+            if (/busy|locked/i.test(String(error)))
+                return null;
+            throw error;
+        }
+    }
+    appendAudit(event) { this.db.prepare('INSERT OR REPLACE INTO self_heal_audit(id,at_ms,controller_id,event,reason,attempt,elapsed_ms) VALUES(?,?,?,?,?,?,?)').run(event.at % 1024, event.at, event.controllerId, event.event, event.reason ?? null, event.attempt ?? null, event.elapsedMs ?? null); }
+    close() { this.unregisterSqlite(); this.db.close(); }
+}
+export class SelfHealGate {
+    spec;
+    deps;
+    now;
+    store;
+    bootId;
+    stateFailureNotices = new Set();
+    constructor(spec, deps) {
+        this.spec = spec;
+        this.deps = deps;
+        if (spec.controllerResource !== 'hardware-bound')
+            throw new Error('v1 SelfHealGate refuses pool-shared controllers');
+        if (!Number.isInteger(spec.maxAttempts) || spec.maxAttempts < 1 || spec.maxAttempts > 32)
+            throw new Error('invalid maxAttempts');
+        for (const value of [spec.maxWallClockMs, spec.notificationLatencyCeilingMs, spec.flap.maxRecoveries, spec.flap.windowMs])
+            if (!Number.isFinite(value) || value <= 0)
+                throw new Error('invalid SelfHealGate bound');
+        this.now = deps.now ?? Date.now;
+        this.store = deps.episodeStore ?? new InMemorySelfHealEpisodeStore();
+        this.bootId = deps.bootId ?? crypto.randomUUID();
+    }
+    needsRestartVerification(ctx) { return this.store.load(this.key(ctx))?.restart !== null; }
+    async attempt(ctx) { const began = this.now(); try {
+        return await this.attemptInner(ctx);
+    }
+    catch {
+        return this.stateFailureWithNotice('store-operation-failed');
+    }
+    finally {
+        this.audit({ event: 'attempt-finished', elapsedMs: Math.max(0, this.now() - began) });
+    } }
+    recordHealthy(ctx) {
+        const current = this.store.load(this.key(ctx));
+        if (!current)
+            return { outcome: 'healed', reason: 'already-healthy' };
+        if (current.status === 'exhausted')
+            return { outcome: 'exhausted', reason: 'terminal' };
+        if (current.restart)
+            return { outcome: 'governed', reason: 'restart-verification-required' };
+        const next = this.cas(current, (row) => ({ ...row, status: 'recovered', recoveries: [...row.recoveries, this.now()].slice(-64), restart: null }));
+        return next ? { outcome: 'healed', reason: 'recorded-healthy' } : { outcome: 'busy', reason: 'revision-conflict' };
+    }
+    async attemptInner(ctx) {
+        const key = this.key(ctx);
+        let row = this.store.load(key);
+        if (!row) {
+            const fresh = this.newEpisode(key);
+            row = this.store.create(fresh) ?? this.store.load(key);
+        }
+        if (!row)
+            return this.stateFailureWithNotice('create-failed');
+        if (row.status === 'active') {
+            const now = this.now();
+            const recent = row.recoveries.filter((at) => now - at <= this.spec.flap.windowMs);
+            if (now - row.startedAt >= this.spec.maxWallClockMs)
+                return this.exhaust(row, 'wall-clock');
+            if (recent.length >= this.spec.flap.maxRecoveries)
+                return this.exhaust(row, 'flap');
+            if (row.attempts >= this.spec.maxAttempts && !row.restart)
+                return this.exhaust(row, 'max-attempts');
+        }
+        if (row.restart) {
+            if (row.restart.state === 'required')
+                return this.requestPendingRestart(row);
+            if (row.restart.requestingBootId === this.bootId)
+                return { outcome: 'attempted', reason: 'restart-awaiting-new-boot' };
+            let verified = false;
+            try {
+                verified = this.spec.restartVerified?.(ctx) === true;
+            }
+            catch {
+                verified = false;
+            }
+            if (!verified) {
+                let severity;
+                try {
+                    severity = this.spec.severity(ctx);
+                }
+                catch {
+                    severity = 'unknown';
+                }
+                if (severity === 'unknown')
+                    return this.noticeAndReturn(row, 'unknown-severity', 'invalid-severity');
+                return { outcome: 'attempted', reason: 'restart-verification-not-healthy' };
+            }
+            const closed = this.cas(row, (r) => ({ ...r, status: 'recovered', restart: null, recoveries: [...r.recoveries, this.now()].slice(-64) }));
+            return closed ? { outcome: 'healed', reason: 'restart-verified' } : { outcome: 'busy', reason: 'revision-conflict' };
+        }
+        let severity;
+        try {
+            severity = this.spec.severity(ctx);
+        }
+        catch {
+            severity = 'unknown';
+        }
+        if (!['recoverable', 'irreversible', 'data-loss', 'security'].includes(severity))
+            return this.noticeAndReturn(row, 'unknown-severity', 'invalid-severity');
+        if (severity !== 'recoverable') {
+            const notice = await this.ensureNotice(row, severity);
+            row = notice.row;
+        }
+        if (row.status === 'recovered') {
+            const now = this.now();
+            const reset = this.cas(row, (r) => ({ ...r, status: 'active', startedAt: now, attempts: 0, nextEligibleAt: 0, latch: emptyLatch(), notices: {}, restart: null }));
+            if (!reset)
+                return { outcome: 'busy', reason: 'revision-conflict' };
+            row = reset;
+        }
+        if (row.status === 'exhausted')
+            return { outcome: 'exhausted', reason: 'terminal' };
+        const latch = new FailureEpisodeLatch({ signalAfterMs: this.spec.notificationLatencyCeilingMs, now: this.now });
+        latch.restore(row.latch);
+        const failure = latch.recordFailure();
+        const detected = this.cas(row, (r) => ({ ...r, latch: latch.snapshot() }));
+        if (!detected)
+            return { outcome: 'busy', reason: 'revision-conflict' };
+        row = detected;
+        if (failure.shouldSignal) {
+            const notice = await this.ensureNotice(row, 'latency');
+            row = notice.row;
+        }
+        const now = this.now();
+        const recent = row.recoveries.filter((at) => now - at <= this.spec.flap.windowMs);
+        if (now - row.startedAt >= this.spec.maxWallClockMs)
+            return this.exhaust(row, 'wall-clock');
+        if (recent.length >= this.spec.flap.maxRecoveries)
+            return this.exhaust(row, 'flap');
+        if (row.attempts >= this.spec.maxAttempts)
+            return this.exhaust(row, 'max-attempts');
+        if (row.nextEligibleAt > now)
+            return { outcome: 'backoff', reason: 'not-eligible-yet' };
+        const eligibility = safeEligible(this.spec, ctx);
+        if (!eligibility.eligible || !eligibility.fence)
+            return { outcome: 'governed', reason: 'fence-stale' };
+        const target = { key: keyHash(key), classId: this.spec.classId, keyIsVolatile: false };
+        const admission = await this.deps.admit(target, { incarnation: eligibility.fence, eligible: () => safeEligible(this.spec, ctx).fence === eligibility.fence, onAdmitted: (token) => { void this.runAdmitted(ctx, target, token).catch(() => { void this.stateFailureWithNotice('queued-attempt-failed'); }); }, lane: 'job', nowMs: now });
+        if (admission.outcome !== 'allow')
+            return { outcome: 'governed', reason: admission.outcome };
+        return this.runAdmitted(ctx, target, admission.token);
+    }
+    async runAdmitted(ctx, target, token) {
+        let row = this.store.load(this.key(ctx));
+        if (!row || row.status !== 'active')
+            return { outcome: 'governed', reason: 'episode-not-active' };
+        const latch = new FailureEpisodeLatch({ signalAfterMs: this.spec.notificationLatencyCeilingMs, now: this.now });
+        latch.restore(row.latch);
+        const failure = latch.recordFailure();
+        const observed = this.cas(row, (r) => ({ ...r, latch: latch.snapshot() }));
+        if (!observed)
+            return { outcome: 'busy', reason: 'revision-conflict' };
+        row = observed;
+        if (failure.shouldSignal) {
+            const notice = await this.ensureNotice(row, 'latency');
+            row = notice.row;
+        }
+        const now = this.now();
+        const recent = row.recoveries.filter((at) => now - at <= this.spec.flap.windowMs);
+        if (now - row.startedAt >= this.spec.maxWallClockMs)
+            return this.exhaust(row, 'wall-clock');
+        if (recent.length >= this.spec.flap.maxRecoveries)
+            return this.exhaust(row, 'flap');
+        if (row.nextEligibleAt > now)
+            return { outcome: 'backoff', reason: 'not-eligible-yet' };
+        const eligibility = safeEligible(this.spec, ctx);
+        if (!eligibility.eligible || !eligibility.fence)
+            return { outcome: 'governed', reason: 'fence-stale' };
+        const consumed = this.deps.consumeToken(token, this.spec.id, { targetKey: target.key, nowMs: this.now() });
+        if (!consumed.proceed)
+            return { outcome: 'governed', reason: consumed.reason ?? 'token-refused', tokenValid: consumed.valid };
+        const again = safeEligible(this.spec, ctx);
+        if (!again.eligible || again.fence !== eligibility.fence)
+            return { outcome: 'governed', reason: 'fence-stale', tokenValid: consumed.valid };
+        if (row.attempts >= this.spec.maxAttempts)
+            return this.exhaust(row, 'max-attempts');
+        const claim = this.cas(row, (r) => ({ ...r, attempts: r.attempts + 1 }), () => {
+            const live = safeEligible(this.spec, ctx);
+            return live.eligible && live.fence === eligibility.fence;
+        });
+        if (!claim)
+            return { outcome: 'governed', reason: 'fence-stale-or-revision-conflict' };
+        row = claim;
+        let result;
+        try {
+            result = this.spec.remediation(ctx);
+            if (result && typeof result.then === 'function')
+                throw new Error('async remediation forbidden');
+        }
+        catch {
+            result = { outcome: 'not-healed', evidence: 'io-error' };
+        }
+        if (result.outcome === 'healed') {
+            const closed = this.cas(row, (r) => ({ ...r, status: 'recovered', recoveries: [...r.recoveries, this.now()].slice(-64) }));
+            return closed ? { outcome: 'healed', reason: result.evidence, tokenValid: consumed.valid } : { outcome: 'busy', reason: 'revision-conflict' };
+        }
+        if (result.outcome === 'pending-restart') {
+            const stableRequestId = `self-heal:${keyHash(row.key)}:${row.startedAt}`;
+            const pending = this.cas(row, (r) => ({ ...r, restart: { state: 'required', requestingBootId: this.bootId, stableRequestId } }));
+            return pending ? this.requestPendingRestart(pending) : { outcome: 'busy', reason: 'revision-conflict' };
+        }
+        const failed = this.cas(row, (r) => ({ ...r, nextEligibleAt: this.now() + Math.max(0, this.spec.backoffMs(row.attempts)) }));
+        return failed ? { outcome: 'attempted', reason: result.evidence, tokenValid: consumed.valid } : { outcome: 'busy', reason: 'revision-conflict' };
+    }
+    requestPendingRestart(row) {
+        if (!row.restart)
+            return { outcome: 'state-failure', reason: 'restart-state-missing' };
+        const ok = this.deps.requestRestart?.(row.restart.stableRequestId) ?? false;
+        if (!ok)
+            return { outcome: 'attempted', reason: 'restart-request-failed' };
+        if (row.restart.state === 'requested')
+            return { outcome: 'attempted', reason: 'restart-requested' };
+        const requested = this.cas(row, (r) => ({ ...r, restart: r.restart ? { ...r.restart, state: 'requested' } : null }));
+        return requested ? { outcome: 'attempted', reason: 'restart-requested' } : { outcome: 'busy', reason: 'revision-conflict' };
+    }
+    async ensureNotice(row, reason) {
+        const existing = row.notices[reason];
+        if (existing?.state === 'enqueued')
+            return { row, attempted: false };
+        const id = existing?.id ?? `self-heal:${keyHash(row.key)}:${reason}:${row.startedAt}`;
+        if (!existing) {
+            const pending = this.cas(row, (r) => ({ ...r, notices: { ...r.notices, [reason]: { state: 'pending', id } } }));
+            if (!pending)
+                return { row: this.store.load(row.key) ?? row, attempted: false };
+            row = pending;
+        }
+        try {
+            await this.deps.notify({ id, controllerId: this.spec.id, reason, priority: ['irreversible', 'data-loss', 'security'].includes(reason) ? 'URGENT' : 'HIGH' });
+        }
+        catch {
+            this.audit({ event: 'notice-enqueue-failed', reason });
+            return { row, attempted: true };
+        }
+        const enqueued = this.cas(row, (r) => ({ ...r, notices: { ...r.notices, [reason]: { state: 'enqueued', id } } }));
+        return { row: enqueued ?? row, attempted: true };
+    }
+    async noticeAndReturn(row, reason, outcome) { const notice = await this.ensureNotice(row, reason); return { outcome, reason, noticeAttempted: notice.attempted, noticeReason: reason }; }
+    async exhaust(row, reason) { const notice = await this.ensureNotice(row, reason); row = notice.row; const terminal = this.cas(row, (r) => ({ ...r, status: 'exhausted' })); return terminal ? { outcome: 'exhausted', reason, noticeAttempted: notice.attempted, noticeReason: reason } : { outcome: 'busy', reason: 'revision-conflict' }; }
+    stateFailure(reason) { this.audit({ event: 'state-failure', reason }); return { outcome: 'state-failure', reason }; }
+    async stateFailureWithNotice(reason) {
+        this.audit({ event: 'state-failure', reason });
+        const id = `self-heal:${this.spec.id}:state-failure:${this.bootId}`;
+        if (!this.stateFailureNotices.has(id)) {
+            try {
+                await this.deps.notify({ id, controllerId: this.spec.id, reason: 'state-failure', priority: 'HIGH' });
+                this.stateFailureNotices.add(id);
+            }
+            catch {
+                this.audit({ event: 'notice-enqueue-failed', reason: 'state-failure' });
+            }
+        }
+        return { outcome: 'state-failure', reason, noticeAttempted: true, noticeReason: 'state-failure' };
+    }
+    key(ctx) { const d = this.spec.dedupeKey(ctx); if (!/^[a-z0-9][a-z0-9._:-]{0,119}$/i.test(d))
+        throw new Error('invalid self-heal dedupe key'); return `${this.spec.id}:${d}`; }
+    newEpisode(key) { const now = this.now(); return { schemaVersion: 1, key, revision: 0, status: 'active', startedAt: now, attempts: 0, nextEligibleAt: 0, latch: emptyLatch(), notices: {}, recoveries: [], restart: null, updatedAt: now }; }
+    cas(row, update, guard) { return this.store.mutate(row.key, row.revision, (r) => ({ ...update(r), revision: r.revision + 1, updatedAt: this.now() }), guard); }
+    audit(input) { const event = { ...input, at: this.now(), controllerId: this.spec.id }; try {
+        this.store.appendAudit?.(event);
+    }
+    catch { /* secondary sink below */ } try {
+        this.deps.audit(event);
+    }
+    catch { /* metadata audit best effort */ } }
+}
+function safeEligible(spec, ctx) { try {
+    return spec.eligible(ctx);
+}
+catch {
+    return { eligible: false, fence: null };
+} }
+function emptyLatch() { return { schemaVersion: 1, failingSince: null, failures: 0, signaledFor: null }; }
+function keyHash(value) { return crypto.createHash('sha256').update(value).digest('hex').slice(0, 24); }
+//# sourceMappingURL=SelfHealGate.js.map