@relkit/supervisor 0.0.0

package/dist/drain.d.ts

@@ -0,0 +1,35 @@
+import type { SupervisorCandidateToken } from "./state-machine-types.js";
+import { type SupervisorDrainLease, type SupervisorDrainOptions, type SupervisorDrainReport, type SupervisorDrainWorkOptions } from "./drain-types.js";
+export * from "./drain-types.js";
+export { drainPreviousGeneration } from "./drain-state.js";
+export declare const DEFAULT_SUPERVISOR_DRAIN_TIMEOUT_MS = 1000;
+export declare class SupervisorDrainError extends Error {
+    readonly code: "RELKIT_DRAIN_STATE_INVALID" | "RELKIT_DRAIN_TOKEN_MISMATCH";
+    constructor(code: SupervisorDrainError["code"], message: string);
+}
+/** Owns admission and bounded cleanup for one retired generation token. */
+export declare class SupervisorGenerationDrain {
+    readonly token: SupervisorCandidateToken;
+    readonly deadlineMs: number;
+    private readonly now;
+    private readonly candidate;
+    private readonly providers;
+    private readonly onReport;
+    private readonly work;
+    private readonly idleWaiters;
+    private nextWorkId;
+    private accepting;
+    private shutdown;
+    constructor(options: SupervisorDrainOptions);
+    get inFlight(): number;
+    get acceptingWork(): boolean;
+    /** Creates a generation-scoped cancellation signal; returns undefined after drain starts. */
+    track(token: SupervisorCandidateToken, options?: SupervisorDrainWorkOptions): SupervisorDrainLease | undefined;
+    /** Waits for work, interrupts the remainder, and releases resources at one bounded deadline. */
+    drain(): Promise<SupervisorDrainReport>;
+    private run;
+    private release;
+    private waitForIdle;
+}
+export declare function createSupervisorDrain(options: SupervisorDrainOptions): SupervisorGenerationDrain;
+//# sourceMappingURL=drain.d.ts.map

package/dist/drain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drain.d.ts","sourceRoot":"","sources":["../src/drain.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAI1B,KAAK,0BAA0B,EAChC,MAAM,kBAAkB,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,eAAO,MAAM,mCAAmC,OAAQ,CAAC;AAKzD,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,EAAE,4BAA4B,GAAG,6BAA6B,CAAC;gBAChE,IAAI,EAAE,oBAAoB,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM;CAKhE;AACD,2EAA2E;AAC3E,qBAAa,yBAAyB;IACpC,QAAQ,CAAC,KAAK,EAAE,wBAAwB,CAAC;IACzC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsC;IAChE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqC;IAC/D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqC;IAC9D,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAkC;IACvD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAyB;IACrD,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,SAAS,CAAQ;IACzB,OAAO,CAAC,QAAQ,CAA6C;gBACjD,OAAO,EAAE,sBAAsB;IAmB3C,IAAI,QAAQ,IAAI,MAAM,CAErB;IACD,IAAI,aAAa,IAAI,OAAO,CAE3B;IACD,6FAA6F;IAC7F,KAAK,CACH,KAAK,EAAE,wBAAwB,EAC/B,OAAO,GAAE,0BAA+B,GACvC,oBAAoB,GAAG,SAAS;IAenC,gGAAgG;IAChG,KAAK,IAAI,OAAO,CAAC,qBAAqB,CAAC;YAKzB,GAAG;IAsEjB,OAAO,CAAC,OAAO;IAOf,OAAO,CAAC,WAAW;CAepB;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,yBAAyB,CAEhG"}

package/dist/drain.js

@@ -0,0 +1,178 @@
+import { closeAction, resourceAction } from "./drain-cleanup.js";
+import { validateSupervisorToken } from "./state-machine-telemetry.js";
+import {} from "./drain-types.js";
+export * from "./drain-types.js";
+export { drainPreviousGeneration } from "./drain-state.js";
+export const DEFAULT_SUPERVISOR_DRAIN_TIMEOUT_MS = 1_000;
+export class SupervisorDrainError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "SupervisorDrainError";
+        this.code = code;
+    }
+}
+/** Owns admission and bounded cleanup for one retired generation token. */
+export class SupervisorGenerationDrain {
+    token;
+    deadlineMs;
+    now;
+    candidate;
+    providers;
+    onReport;
+    work = new Map();
+    idleWaiters = new Set();
+    nextWorkId = 0;
+    accepting = true;
+    shutdown;
+    constructor(options) {
+        validateSupervisorToken(options.token);
+        if (options.candidate !== undefined && !sameToken(options.candidate.token, options.token)) {
+            throw new SupervisorDrainError("RELKIT_DRAIN_TOKEN_MISMATCH", "The candidate token does not match the retired generation.");
+        }
+        const deadlineMs = options.deadlineMs ?? DEFAULT_SUPERVISOR_DRAIN_TIMEOUT_MS;
+        if (!Number.isSafeInteger(deadlineMs) || deadlineMs < 0) {
+            throw new RangeError("Supervisor drain deadline must be a non-negative safe integer.");
+        }
+        this.token = Object.freeze({ ...options.token });
+        this.deadlineMs = deadlineMs;
+        this.now = options.now ?? Date.now;
+        this.candidate = options.candidate;
+        this.providers = Object.freeze([...(options.providers ?? [])]);
+        this.onReport = options.onReport;
+    }
+    get inFlight() {
+        return this.work.size;
+    }
+    get acceptingWork() {
+        return this.accepting;
+    }
+    /** Creates a generation-scoped cancellation signal; returns undefined after drain starts. */
+    track(token, options = {}) {
+        validateSupervisorToken(token);
+        if (!this.accepting || !sameToken(token, this.token))
+            return undefined;
+        const id = ++this.nextWorkId;
+        const tracked = {
+            controller: new AbortController(),
+            interrupt: options.interrupt,
+        };
+        this.work.set(id, tracked);
+        return Object.freeze({
+            token: this.token,
+            signal: tracked.controller.signal,
+            release: () => this.release(id),
+        });
+    }
+    /** Waits for work, interrupts the remainder, and releases resources at one bounded deadline. */
+    drain() {
+        this.shutdown ??= this.run();
+        return this.shutdown;
+    }
+    async run() {
+        this.accepting = false;
+        const startedAt = this.now();
+        const deadlineAt = startedAt + this.deadlineMs;
+        const initialInFlight = this.work.size;
+        let interrupted = 0;
+        let timedOut = !(await this.waitForIdle(deadlineAt));
+        if (timedOut) {
+            const pending = [...this.work.values()];
+            for (const work of pending) {
+                if (work.controller.signal.aborted)
+                    continue;
+                work.controller.abort(new Error("Retired generation drain deadline expired."));
+                interrupted += 1;
+                try {
+                    void Promise.resolve(work.interrupt?.("Retired generation drain deadline expired.")).catch(() => undefined);
+                }
+                catch {
+                    // Interruption is best effort; the bounded report still closes resources.
+                }
+            }
+        }
+        const candidate = await closeAction("candidate", this.candidate?.dispose, deadlineAt, this.now);
+        const providers = [];
+        const failures = [];
+        for (let index = this.providers.length - 1; index >= 0; index -= 1) {
+            const provider = this.providers[index];
+            if (provider === undefined)
+                continue;
+            const id = provider.id ?? `provider-${index}`;
+            const result = await closeAction(id, resourceAction(provider), deadlineAt, this.now);
+            providers.push({ id, status: result.status });
+            if (result.message !== undefined)
+                failures.push({ resource: id, message: result.message });
+        }
+        const remaining = this.work.size;
+        timedOut ||=
+            remaining > 0 ||
+                candidate.status === "timed-out" ||
+                providers.some((item) => item.status === "timed-out");
+        if (candidate.message !== undefined)
+            failures.push({ resource: "candidate", message: candidate.message });
+        const outcome = timedOut
+            ? "timed-out"
+            : failures.length > 0
+                ? "failed"
+                : interrupted > 0
+                    ? "interrupted"
+                    : "drained";
+        const report = Object.freeze({
+            token: this.token,
+            deadlineMs: this.deadlineMs,
+            elapsedMs: Math.max(0, this.now() - startedAt),
+            initialInFlight,
+            completed: initialInFlight - remaining,
+            interrupted,
+            remaining,
+            timedOut,
+            outcome,
+            candidate: candidate.status,
+            providers: Object.freeze(providers.reverse()),
+            failures: Object.freeze(failures),
+            stateTransition: "not-configured",
+        });
+        try {
+            this.onReport?.(report);
+        }
+        catch {
+            // Reporting cannot change generation cleanup.
+        }
+        return report;
+    }
+    release(id) {
+        if (!this.work.delete(id) || this.work.size !== 0)
+            return;
+        const waiters = [...this.idleWaiters];
+        this.idleWaiters.clear();
+        for (const resolve of waiters)
+            resolve();
+    }
+    waitForIdle(deadlineAt) {
+        if (this.work.size === 0)
+            return Promise.resolve(true);
+        const remaining = Math.max(0, deadlineAt - this.now());
+        return new Promise((resolve) => {
+            let timer;
+            const finish = (drained) => {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                this.idleWaiters.delete(onIdle);
+                resolve(drained);
+            };
+            const onIdle = () => finish(true);
+            this.idleWaiters.add(onIdle);
+            timer = setTimeout(() => finish(false), remaining);
+        });
+    }
+}
+export function createSupervisorDrain(options) {
+    return new SupervisorGenerationDrain(options);
+}
+function sameToken(left, right) {
+    return (Boolean(left && right) &&
+        left?.sourceToken === right?.sourceToken &&
+        left?.generationToken === right?.generationToken);
+}
+//# sourceMappingURL=drain.js.map

package/dist/drain.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./state-machine.js";
+export * from "./watcher.js";
+export * from "./candidate.js";
+export * from "./verification.js";
+export * from "./proxy.js";
+export * from "./drain.js";
+export * from "./drain-state.js";
+export * from "./observability.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+export * from "./state-machine.js";
+export * from "./watcher.js";
+export * from "./candidate.js";
+export * from "./verification.js";
+export * from "./proxy.js";
+export * from "./drain.js";
+export * from "./drain-state.js";
+export * from "./observability.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC"}

package/dist/observability-records.d.ts

@@ -0,0 +1,9 @@
+import { type DiagnosticRecord, type GenerationRecord } from "@relkit/observability";
+import type { SupervisorCandidateToken, SupervisorTelemetry } from "./state-machine-types.js";
+export interface SupervisorTelemetryRecord {
+    readonly record: GenerationRecord | DiagnosticRecord;
+    readonly streamType: "generation.changed" | "diagnostic.changed";
+}
+export declare function recordsForTelemetry(event: SupervisorTelemetry, graphHash: (token: SupervisorCandidateToken) => string, now: () => number): readonly SupervisorTelemetryRecord[];
+export declare function generationIdFor(token: SupervisorCandidateToken): string;
+//# sourceMappingURL=observability-records.d.ts.map

package/dist/observability-records.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability-records.d.ts","sourceRoot":"","sources":["../src/observability-records.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,gBAAgB,EAErB,KAAK,gBAAgB,EACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EACV,wBAAwB,EAExB,mBAAmB,EACpB,MAAM,0BAA0B,CAAC;AAElC,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,CAAC;IACrD,QAAQ,CAAC,UAAU,EAAE,oBAAoB,GAAG,oBAAoB,CAAC;CAClE;AAED,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,mBAAmB,EAC1B,SAAS,EAAE,CAAC,KAAK,EAAE,wBAAwB,KAAK,MAAM,EACtD,GAAG,EAAE,MAAM,MAAM,GAChB,SAAS,yBAAyB,EAAE,CAkDtC;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,wBAAwB,GAAG,MAAM,CAEvE"}

package/dist/observability-records.js

@@ -0,0 +1,71 @@
+import { OBSERVABILITY_MODEL_VERSION, } from "@relkit/observability";
+export function recordsForTelemetry(event, graphHash, now) {
+    if (event.type !== "outcome")
+        return [];
+    const occurredAt = new Date(now()).toISOString();
+    const target = event.phase === "drain" ? event.previousGeneration : undefined;
+    const token = target ?? tokenFor(event);
+    const hash = graphHash(token);
+    const generationId = generationIdFor(token);
+    const lifecycle = lifecycleFor(event);
+    const generation = {
+        version: OBSERVABILITY_MODEL_VERSION,
+        signal: "generation",
+        generationId,
+        graphHash: hash,
+        event: lifecycle,
+        occurredAt,
+        sourceVersion: token.sourceToken,
+        ...(event.error?.code === undefined ? {} : { errorCode: event.error.code }),
+    };
+    const diagnostic = {
+        version: OBSERVABILITY_MODEL_VERSION,
+        signal: "diagnostic",
+        code: event.error?.code ?? `RELKIT_SUPERVISOR_${event.outcome.toUpperCase().replaceAll("-", "_")}`,
+        severity: event.outcome === "candidate-stale" ? "warning" : lifecycle === "failed" ? "error" : "info",
+        message: event.error?.message ?? `Supervisor ${event.phase} ${event.outcome}.`,
+        occurredAt,
+        generationId,
+        graphHash: hash,
+    };
+    const result = [
+        { record: generation, streamType: "generation.changed" },
+        { record: diagnostic, streamType: "diagnostic.changed" },
+    ];
+    if (event.outcome === "switch-succeeded" && event.previousGeneration !== undefined) {
+        const previous = event.previousGeneration;
+        result.unshift({
+            streamType: "generation.changed",
+            record: {
+                version: OBSERVABILITY_MODEL_VERSION,
+                signal: "generation",
+                generationId: generationIdFor(previous),
+                graphHash: graphHash(previous),
+                event: "draining",
+                occurredAt,
+                sourceVersion: previous.sourceToken,
+            },
+        });
+    }
+    return Object.freeze(result);
+}
+export function generationIdFor(token) {
+    return `generation-${token.generationToken}`;
+}
+function tokenFor(event) {
+    return { sourceToken: event.sourceToken, generationToken: event.generationToken };
+}
+function lifecycleFor(event) {
+    if (event.phase === "compile")
+        return event.outcome === "compile-succeeded" ? "created" : "failed";
+    if (event.phase === "start")
+        return event.outcome === "start-succeeded" ? "started" : "failed";
+    if (event.phase === "verification")
+        return event.outcome === "verification-succeeded" ? "ready" : "failed";
+    if (event.phase === "switch")
+        return event.outcome === "switch-succeeded" ? "activated" : "failed";
+    if (event.outcome === "drain-succeeded")
+        return "stopped";
+    return "failed";
+}
+//# sourceMappingURL=observability-records.js.map

package/dist/observability-records.js.map

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

package/dist/observability-types.d.ts

@@ -0,0 +1,18 @@
+import type { MaybePromise } from "@relkit/contracts";
+import type { ObservabilityCollector, ObservabilityRecord, ObservabilityStream, RedactionPolicy } from "@relkit/observability";
+import type { SupervisorCandidateToken, SupervisorTelemetry, SupervisorTelemetryListener } from "./state-machine-types.js";
+export type SupervisorGraphHash = string | ((token: SupervisorCandidateToken, event: SupervisorTelemetry) => string | undefined);
+export interface SupervisorObservabilityOptions {
+    readonly graphHash: SupervisorGraphHash;
+    readonly collector?: Pick<ObservabilityCollector, "collect">;
+    readonly stream?: Pick<ObservabilityStream, "publishRecord">;
+    readonly append?: (record: ObservabilityRecord) => MaybePromise<unknown>;
+    readonly redaction?: RedactionPolicy;
+    readonly now?: () => number;
+}
+export interface SupervisorObservability {
+    readonly onTelemetry: SupervisorTelemetryListener;
+    readonly emit: (event: SupervisorTelemetry) => void;
+    readonly flush: () => Promise<void>;
+}
+//# sourceMappingURL=observability-types.d.ts.map

package/dist/observability-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability-types.d.ts","sourceRoot":"","sources":["../src/observability-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EACV,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,EAChB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EACV,wBAAwB,EACxB,mBAAmB,EACnB,2BAA2B,EAC5B,MAAM,0BAA0B,CAAC;AAElC,MAAM,MAAM,mBAAmB,GAC7B,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,wBAAwB,EAAE,KAAK,EAAE,mBAAmB,KAAK,MAAM,GAAG,SAAS,CAAC,CAAC;AAEjG,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,SAAS,EAAE,mBAAmB,CAAC;IACxC,QAAQ,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,SAAS,CAAC,CAAC;IAC7D,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,mBAAmB,EAAE,eAAe,CAAC,CAAC;IAC7D,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,mBAAmB,KAAK,YAAY,CAAC,OAAO,CAAC,CAAC;IACzE,QAAQ,CAAC,SAAS,CAAC,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,WAAW,EAAE,2BAA2B,CAAC;IAClD,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,CAAC;IACpD,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC"}

package/dist/observability-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=observability-types.js.map

package/dist/observability-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability-types.js","sourceRoot":"","sources":["../src/observability-types.ts"],"names":[],"mappings":""}

package/dist/observability.d.ts

@@ -0,0 +1,5 @@
+import type { SupervisorObservability, SupervisorObservabilityOptions } from "./observability-types.js";
+export type { SupervisorGraphHash, SupervisorObservability, SupervisorObservabilityOptions, } from "./observability-types.js";
+/** Bridges supervisor lifecycle outcomes into the existing redacted observability sinks. */
+export declare function createSupervisorObservability(options: SupervisorObservabilityOptions): SupervisorObservability;
+//# sourceMappingURL=observability.d.ts.map

package/dist/observability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.d.ts","sourceRoot":"","sources":["../src/observability.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAEV,uBAAuB,EACvB,8BAA8B,EAC/B,MAAM,0BAA0B,CAAC;AAElC,YAAY,EACV,mBAAmB,EACnB,uBAAuB,EACvB,8BAA8B,GAC/B,MAAM,0BAA0B,CAAC;AAElC,4FAA4F;AAC5F,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,8BAA8B,GACtC,uBAAuB,CAuCzB"}

package/dist/observability.js

@@ -0,0 +1,46 @@
+import { admitObservabilityRecord } from "@relkit/observability";
+import { recordsForTelemetry } from "./observability-records.js";
+/** Bridges supervisor lifecycle outcomes into the existing redacted observability sinks. */
+export function createSupervisorObservability(options) {
+    const now = options.now ?? Date.now;
+    let tail = Promise.resolve();
+    const resolveHash = createHashResolver(options.graphHash);
+    const emit = (event) => {
+        const records = recordsForTelemetry(event, (token) => resolveHash(token, event), now);
+        for (const item of records)
+            publish(item.record, item.streamType);
+    };
+    const publish = (record, streamType) => {
+        const safe = admitObservabilityRecord(record, options.redaction);
+        if (safe === undefined)
+            return;
+        try {
+            options.collector?.collect(safe);
+            options.stream?.publishRecord(streamType, safe);
+        }
+        catch {
+            // A closed or bounded sink cannot change supervisor lifecycle behavior.
+        }
+        if (options.append !== undefined) {
+            tail = tail
+                .then(() => options.append(safe))
+                .then(() => undefined, () => undefined);
+        }
+    };
+    return Object.freeze({
+        onTelemetry: emit,
+        emit,
+        flush: async () => {
+            await tail;
+        },
+    });
+}
+function createHashResolver(value) {
+    return (token, event) => {
+        const hash = typeof value === "string" ? value : value(token, event);
+        if (hash === undefined || hash.trim() === "")
+            throw new TypeError(`Supervisor observability requires an explicit graph hash for generation-${token.generationToken}.`);
+        return hash;
+    };
+}
+//# sourceMappingURL=observability.js.map

package/dist/observability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.js","sourceRoot":"","sources":["../src/observability.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAA4B,MAAM,uBAAuB,CAAC;AAC3F,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAcjE,4FAA4F;AAC5F,MAAM,UAAU,6BAA6B,CAC3C,OAAuC;IAEvC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;IACpC,IAAI,IAAI,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAC7B,MAAM,WAAW,GAAG,kBAAkB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAE1D,MAAM,IAAI,GAAG,CAAC,KAA0B,EAAQ,EAAE;QAChD,MAAM,OAAO,GAAG,mBAAmB,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,WAAW,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC;QACtF,KAAK,MAAM,IAAI,IAAI,OAAO;YAAE,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IACpE,CAAC,CAAC;IAEF,MAAM,OAAO,GAAG,CACd,MAA2B,EAC3B,UAAuD,EACjD,EAAE;QACR,MAAM,IAAI,GAAG,wBAAwB,CAAC,MAAM,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;QACjE,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO;QAC/B,IAAI,CAAC;YACH,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;YACjC,OAAO,CAAC,MAAM,EAAE,aAAa,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QAClD,CAAC;QAAC,MAAM,CAAC;YACP,wEAAwE;QAC1E,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YACjC,IAAI,GAAG,IAAI;iBACR,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,MAAO,CAAC,IAAI,CAAC,CAAC;iBACjC,IAAI,CACH,GAAG,EAAE,CAAC,SAAS,EACf,GAAG,EAAE,CAAC,SAAS,CAChB,CAAC;QACN,CAAC;IACH,CAAC,CAAC;IAEF,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,WAAW,EAAE,IAAI;QACjB,IAAI;QACJ,KAAK,EAAE,KAAK,IAAI,EAAE;YAChB,MAAM,IAAI,CAAC;QACb,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED,SAAS,kBAAkB,CACzB,KAA0B;IAE1B,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;QACtB,MAAM,IAAI,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QACrE,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE;YAC1C,MAAM,IAAI,SAAS,CACjB,2EAA2E,KAAK,CAAC,eAAe,GAAG,CACpG,CAAC;QACJ,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;AACJ,CAAC"}

package/dist/proxy-forward.d.ts

@@ -0,0 +1,5 @@
+import type { SupervisorDrainLease } from "./drain-types.js";
+import type { ActiveSupervisorProxyTarget } from "./proxy.js";
+export declare function forwardProxyRequest(request: Request, target: ActiveSupervisorProxyTarget, fetcher?: typeof fetch, lease?: SupervisorDrainLease): Promise<Response>;
+export declare function drainResponse(): Response;
+//# sourceMappingURL=proxy-forward.d.ts.map

package/dist/proxy-forward.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy-forward.d.ts","sourceRoot":"","sources":["../src/proxy-forward.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,YAAY,CAAC;AAe9D,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,2BAA2B,EACnC,OAAO,GAAE,OAAO,KAAa,EAC7B,KAAK,CAAC,EAAE,oBAAoB,GAC3B,OAAO,CAAC,QAAQ,CAAC,CAanB;AAED,wBAAgB,aAAa,IAAI,QAAQ,CAKxC"}

package/dist/proxy-forward.js

@@ -0,0 +1,43 @@
+const HOP_BY_HOP_HEADERS = [
+    "connection",
+    "content-length",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+    "host",
+];
+export function forwardProxyRequest(request, target, fetcher = fetch, lease) {
+    const url = new URL(request.url);
+    url.protocol = "http:";
+    url.hostname = target.hostname;
+    url.port = String(target.port);
+    const init = {
+        method: request.method,
+        headers: forwardedHeaders(request.headers),
+        redirect: "manual",
+        signal: lease === undefined ? request.signal : AbortSignal.any([request.signal, lease.signal]),
+    };
+    if (request.method !== "GET" && request.method !== "HEAD")
+        init.body = request.body;
+    return fetcher(url, init);
+}
+export function drainResponse() {
+    return new Response(JSON.stringify({ error: "RelKit generation is draining." }), {
+        status: 503,
+        headers: { "cache-control": "no-store", "content-type": "application/json" },
+    });
+}
+function forwardedHeaders(source) {
+    const headers = new Headers(source);
+    const connection = headers.get("connection");
+    for (const name of connection?.split(",") ?? [])
+        headers.delete(name.trim());
+    for (const name of HOP_BY_HOP_HEADERS)
+        headers.delete(name);
+    return headers;
+}
+//# sourceMappingURL=proxy-forward.js.map

package/dist/proxy-forward.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy-forward.js","sourceRoot":"","sources":["../src/proxy-forward.ts"],"names":[],"mappings":"AAGA,MAAM,kBAAkB,GAAG;IACzB,YAAY;IACZ,gBAAgB;IAChB,YAAY;IACZ,oBAAoB;IACpB,qBAAqB;IACrB,IAAI;IACJ,SAAS;IACT,mBAAmB;IACnB,SAAS;IACT,MAAM;CACE,CAAC;AAEX,MAAM,UAAU,mBAAmB,CACjC,OAAgB,EAChB,MAAmC,EACnC,UAAwB,KAAK,EAC7B,KAA4B;IAE5B,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACjC,GAAG,CAAC,QAAQ,GAAG,OAAO,CAAC;IACvB,GAAG,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;IAC/B,GAAG,CAAC,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,IAAI,GAAgB;QACxB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,OAAO,EAAE,gBAAgB,CAAC,OAAO,CAAC,OAAO,CAAC;QAC1C,QAAQ,EAAE,QAAQ;QAClB,MAAM,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;KAC/F,CAAC;IACF,IAAI,OAAO,CAAC,MAAM,KAAK,KAAK,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM;QAAE,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IACpF,OAAO,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,gCAAgC,EAAE,CAAC,EAAE;QAC/E,MAAM,EAAE,GAAG;QACX,OAAO,EAAE,EAAE,eAAe,EAAE,UAAU,EAAE,cAAc,EAAE,kBAAkB,EAAE;KAC7E,CAAC,CAAC;AACL,CAAC;AAED,SAAS,gBAAgB,CAAC,MAAe;IACvC,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACpC,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAC7C,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE;QAAE,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAC7E,KAAK,MAAM,IAAI,IAAI,kBAAkB;QAAE,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC5D,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/proxy.d.ts

@@ -0,0 +1,45 @@
+import type { StartedCandidate } from "./candidate-types.js";
+import type { SupervisorDrainLease } from "./drain-types.js";
+import type { SupervisorCandidateToken } from "./state-machine-types.js";
+export { forwardProxyRequest } from "./proxy-forward.js";
+export declare const DEFAULT_SUPERVISOR_HOSTNAME = "127.0.0.1";
+export declare const DEFAULT_SUPERVISOR_PORT = 3000;
+export type SupervisorProxyTarget = Pick<StartedCandidate, "token" | "port"> & {
+    readonly hostname?: string;
+};
+export interface ActiveSupervisorProxyTarget {
+    readonly token: SupervisorCandidateToken;
+    readonly hostname: string;
+    readonly port: number;
+}
+export interface SupervisorProxyOptions {
+    readonly hostname?: string;
+    readonly port?: number;
+    readonly targetHostname?: string;
+    readonly fetch?: typeof fetch;
+    readonly track?: (token: SupervisorCandidateToken) => SupervisorDrainLease | undefined;
+}
+/** Stable development listener that synchronously selects one active target per request. */
+export declare class SupervisorProxy {
+    private readonly hostname;
+    private readonly configuredPort;
+    private readonly targetHostname;
+    private readonly fetcher;
+    private readonly track;
+    private server;
+    private stopping;
+    private target;
+    constructor(options?: SupervisorProxyOptions);
+    get port(): number;
+    get url(): URL | undefined;
+    get activeTarget(): ActiveSupervisorProxyTarget | undefined;
+    listen(): Promise<this>;
+    /** Replaces the target only when the expected active token still matches. */
+    compareAndSwitch(expected: SupervisorCandidateToken | undefined, next: SupervisorProxyTarget): boolean;
+    switchTarget(next: SupervisorProxyTarget, expected?: SupervisorCandidateToken | undefined): boolean;
+    /** Reads the active reference before awaiting, so switched traffic cannot select a retired target. */
+    handle(request: Request): Promise<Response>;
+    stop(): Promise<void>;
+}
+export declare function createSupervisorProxy(options?: SupervisorProxyOptions): SupervisorProxy;
+//# sourceMappingURL=proxy.d.ts.map

package/dist/proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAG7D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAEzE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAEzD,eAAO,MAAM,2BAA2B,cAAc,CAAC;AACvD,eAAO,MAAM,uBAAuB,OAAQ,CAAC;AAE7C,MAAM,MAAM,qBAAqB,GAAG,IAAI,CAAC,gBAAgB,EAAE,OAAO,GAAG,MAAM,CAAC,GAAG;IAC7E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,KAAK,EAAE,wBAAwB,CAAC;IACzC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,wBAAwB,KAAK,oBAAoB,GAAG,SAAS,CAAC;CACxF;AAED,4FAA4F;AAC5F,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkC;IACxD,OAAO,CAAC,MAAM,CAAoC;IAClD,OAAO,CAAC,QAAQ,CAA4B;IAC5C,OAAO,CAAC,MAAM,CAA0C;gBAE5C,OAAO,GAAE,sBAA2B;IAUhD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,GAAG,IAAI,GAAG,GAAG,SAAS,CAEzB;IAED,IAAI,YAAY,IAAI,2BAA2B,GAAG,SAAS,CAE1D;IAEK,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAW7B,6EAA6E;IAC7E,gBAAgB,CACd,QAAQ,EAAE,wBAAwB,GAAG,SAAS,EAC9C,IAAI,EAAE,qBAAqB,GAC1B,OAAO;IAeV,YAAY,CAAC,IAAI,EAAE,qBAAqB,EAAE,QAAQ,uCAAqB,GAAG,OAAO;IAIjF,sGAAsG;IACtG,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;IAqB3C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAUtB;AAED,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,sBAA2B,GAAG,eAAe,CAE3F"}