@timurproko/a1 0.1.8-dev.299 → 0.1.8-dev.332

package/dist/features/prompt-history/service.js

@@ -1,38 +1,54 @@
 import { assertPromptHistorySubmission, PROMPT_HISTORY_MAX_ENTRY_BYTES, PROMPT_HISTORY_MAX_PENDING, PROMPT_HISTORY_MAX_TEXT_BYTES } from "../../contracts/owned-ui/index.js";
 import { resolvePromptHistoryPath } from "./paths.js";
-/** Owns a finite asynchronous history queue; storage faults never throw into prompt dispatch. */
+const clock = { now: () => Date.now(), setTimeout: (fn, ms) => setTimeout(fn, ms), clearTimeout: timer => clearTimeout(timer) };
+const RETENTION_MS = 30_000;
+const LIVENESS_MS = 10_000;
+/** One generation owns storage work; only proven non-commits may be retried. No default output sink. */
 export class PromptHistoryService {
     options;
     #snapshots = new Set();
     #failures = new Set();
-    #reported = new Set();
+    #counts = {};
     #queue = [];
+    #clock;
+    #state = "starting";
     #worker;
+    #stopping;
     #active;
     #timer;
+    #expiry;
     #poll;
+    #closeTimer;
     #sequence = 0;
+    #generation = 0;
     #bytes = 0;
-    #writes = 0;
     #started = false;
     #ready = false;
-    #failed = false;
-    #closing = false;
-    #reading = false;
     #refreshPending = false;
     #lastRevision = -1;
+    #backoff = 100;
+    #recoveries = 0;
     #closePromise;
+    #resolveClose;
     constructor(options) {
         this.options = options;
+        this.#clock = options.clock ?? clock;
+    }
+    /** Explicit developer inspection: bounded classified counters, never exception or prompt payloads. */
+    diagnostics() {
+        return { state: this.#state, generation: this.#generation, attempts: this.#sequence, recoveries: this.#recoveries,
+            pending: this.#queue.length, bytes: this.#bytes, active: this.#active !== undefined,
+            timers: [this.#timer, this.#expiry, this.#poll, this.#closeTimer].filter(value => value !== undefined).length,
+            failures: { ...this.#counts } };
     }
     start() {
-        if (this.#started || this.#closing)
+        if (this.#started || this.#isClosed())
             return;
         this.#started = true;
-        setImmediate(() => { void this.#open().catch(() => this.#fail("unavailable")); });
+        void this.#open();
     }
     record(submission) {
-        if (this.#failed || this.#closing)
+        if (this.#isClosed() || this.#state === "blocked-storage")
             return Promise.resolve("skipped");
         try {
             assertPromptHistorySubmission(submission);
@@ -46,7 +62,7 @@ export class PromptHistoryService {
             this.#report("oversized");
             return Promise.resolve("skipped");
         }
-        if (this.#writes >= PROMPT_HISTORY_MAX_PENDING || this.#bytes + bytes > PROMPT_HISTORY_MAX_TEXT_BYTES) {
+        if (this.#queue.length >= PROMPT_HISTORY_MAX_PENDING || this.#bytes + bytes > PROMPT_HISTORY_MAX_TEXT_BYTES) {
             this.#report("capacity");
             return Promise.resolve("skipped");
         }
@@ -56,53 +72,18 @@ export class PromptHistoryService {
             ...(submission.sessionId !== undefined && Buffer.byteLength(submission.sessionId) <= 256 ? { sessionId: submission.sessionId } : {}),
         };
         this.start();
-        this.#writes++;
         this.#bytes += bytes;
         return new Promise(resolve => {
-            this.#queue.push({ request: { id: ++this.#sequence, kind: "record", submission: candidate }, done: (_value, ok) => {
-                    this.#writes--;
-                    this.#bytes -= bytes;
-                    resolve(ok ? "committed" : "skipped");
-                    if (ok)
-                        this.refresh();
-                } });
+            this.#queue.push({ submission: candidate, expires: this.#clock.now() + RETENTION_MS, bytes, done: resolve });
+            this.#armExpiry();
             this.#drain();
         });
     }
     refresh() {
-        if (this.#closing || this.#failed)
+        if (this.#isClosed() || this.#state === "blocked-storage")
             return;
         this.start();
-        if (this.#reading) {
-            this.#refreshPending = true;
-            return;
-        }
-        this.#reading = true;
-        const observers = [...this.#snapshots];
-        this.#queue.push({ request: { id: ++this.#sequence, kind: "read" }, done: (value, ok) => {
-                this.#reading = false;
-                if (ok) {
-                    if (!isSnapshot(value)) {
-                        this.#fail("corrupt");
-                        return;
-                    }
-                    if (value.revision !== this.#lastRevision && observers.some(listener => this.#snapshots.has(listener))) {
-                        this.#lastRevision = value.revision;
-                        for (const listener of observers) {
-                            if (!this.#snapshots.has(listener))
-                                continue;
-                            try {
-                                listener(value);
-                            }
-                            catch { /* Security: observer errors must not escape the worker event handler. */ }
-                        }
-                    }
-                }
-                if (this.#refreshPending) {
-                    this.#refreshPending = false;
-                    this.refresh();
-                }
-            } });
+        this.#refreshPending = true;
         this.#drain();
     }
     onSnapshot(listener) {
@@ -110,6 +91,7 @@ export class PromptHistoryService {
         this.#lastRevision = -1;
         return () => this.#snapshots.delete(listener);
     }
+    // Security: this classified observer is developer-only, never wired to shell notifications.
     onFailure(listener) {
         this.#failures.add(listener);
         return () => this.#failures.delete(listener);
@@ -117,116 +99,299 @@ export class PromptHistoryService {
     close() {
         if (this.#closePromise !== undefined)
             return this.#closePromise;
-        this.#closing = true;
-        if (this.#poll !== undefined)
-            clearInterval(this.#poll);
-        this.#closePromise = new Promise(resolve => {
-            if (!this.#started || this.#failed) {
-                resolve();
-                return;
-            }
-            const deadline = setTimeout(() => { this.#report("shutdown"); this.#fail("shutdown"); resolve(); }, 2000);
-            this.#queue.push({ request: { id: ++this.#sequence, kind: "close" }, done: (_value, ok) => {
-                    if (!ok)
-                        this.#report("shutdown");
-                    const stopped = this.#worker?.terminate() ?? Promise.resolve();
-                    void stopped.catch(() => { }).finally(() => { clearTimeout(deadline); resolve(); });
-                } });
+        this.#state = "closing";
+        this.#clock.clearTimeout(this.#poll);
+        this.#poll = undefined;
+        this.#clock.clearTimeout(this.#expiry);
+        this.#expiry = undefined;
+        this.#refreshPending = false;
+        this.#closePromise = new Promise(resolve => { this.#resolveClose = resolve; });
+        this.#closeTimer = this.#clock.setTimeout(() => {
+            this.#report("shutdown");
+            this.#finishClose();
+        }, 2000);
+        if (!this.#started || !this.#ready && this.#worker === undefined)
+            this.#finishClose();
+        else if (this.#active === undefined && this.#ready) {
+            this.#clock.clearTimeout(this.#timer);
+            this.#timer = undefined;
             this.#drain();
-        });
+        }
         return this.#closePromise;
     }
+    #isClosed() { return this.#state === "closing" || this.#state === "closed"; }
     async #open() {
-        if (this.#failed)
+        if (this.#isClosed() || this.#state === "blocked-storage" || this.#worker !== undefined || this.#stopping !== undefined)
             return;
-        const { Worker } = await import("node:worker_threads");
-        if (this.#failed)
+        const generation = ++this.#generation;
+        this.#state = "starting";
+        try {
+            const { Worker } = await import("node:worker_threads");
+            if (this.#isClosed() || generation !== this.#generation)
+                return;
+            const location = resolvePromptHistoryPath(this.options.dataDir, this.options.profileRoot);
+            const source = import.meta.url.endsWith(".ts");
+            const entry = new URL(source ? "./worker.ts" : "./worker.js", import.meta.url);
+            const options = { workerData: { ...location, limit: this.options.limit }, stdout: true, stderr: true };
+            const worker = this.options.createWorker?.() ?? (source
+                ? new Worker(`import('tsx/esm/api').then(({ tsImport }) => tsImport(${JSON.stringify(entry.href)}, ${JSON.stringify(import.meta.url)}))`, { ...options, eval: true })
+                : new Worker(entry, options));
+            this.#worker = worker;
+            worker.stdout?.resume();
+            worker.stderr?.resume();
+            this.#timer = this.#clock.setTimeout(() => this.#lost("unavailable"), LIVENESS_MS);
+            worker.on("message", (message) => {
+                if (generation !== this.#generation || this.#state === "closed")
+                    return;
+                this.#response(message);
+            });
+            worker.on("error", () => { if (generation === this.#generation)
+                this.#lost("unavailable"); });
+            worker.on("exit", () => { if (generation === this.#generation)
+                this.#lost("unavailable"); });
+        }
+        catch {
+            if (generation === this.#generation)
+                this.#lost("unavailable");
+        }
+    }
+    #response(value) {
+        if (value === null || typeof value !== "object") {
+            this.#lost("unavailable");
             return;
-        const location = resolvePromptHistoryPath(this.options.dataDir, this.options.profileRoot);
-        const source = import.meta.url.endsWith(".ts");
-        const entry = new URL(source ? "./worker.ts" : "./worker.js", import.meta.url);
-        const options = { workerData: { ...location, limit: this.options.limit }, stdout: true, stderr: true };
-        this.#worker = this.options.createWorker?.() ?? (source
-            ? new Worker(`import('tsx/esm/api').then(({ tsImport }) => tsImport(${JSON.stringify(entry.href)}, ${JSON.stringify(import.meta.url)}))`, { ...options, eval: true })
-            : new Worker(entry, options));
-        this.#worker.stdout.resume();
-        this.#worker.stderr.resume();
-        this.#timer = setTimeout(() => this.#fail("unavailable"), 5000);
-        this.#worker.on("message", (message) => {
-            if (this.#failed)
+        }
+        const message = value;
+        if (!Number.isSafeInteger(message.id) || typeof message.ok !== "boolean") {
+            this.#lost("unavailable");
+            return;
+        }
+        // Concurrency: late/duplicate attempt replies cannot clear another attempt's liveness timer.
+        if (message.id !== (this.#ready ? this.#active?.id : 0))
+            return;
+        this.#clock.clearTimeout(this.#timer);
+        this.#timer = undefined;
+        const attempt = this.#active;
+        this.#active = undefined;
+        if (!message.ok) {
+            const code = failureCode(message.code);
+            this.#report(code);
+            if (code === "schema" || code === "corrupt") {
+                this.#state = this.#isClosed() ? "closing" : "blocked-storage";
+                this.#settleAll();
+                void this.#stopWorker();
+                if (this.#isClosed())
+                    this.#finishClose();
                 return;
-            clearTimeout(this.#timer);
-            if (message === null || typeof message !== "object" || !Number.isSafeInteger(message.id) || typeof message.ok !== "boolean") {
-                this.#fail("unavailable");
+            }
+            if (attempt?.work !== undefined && message.certainty !== "uncommitted") {
+                this.#settle(attempt.work, "skipped");
+                this.#lost(code);
                 return;
             }
-            if (!message.ok) {
-                this.#fail(failureCode(message.code));
+            if (attempt?.work !== undefined && code === "oversized")
+                this.#settle(attempt.work, "skipped");
+            if (this.#isClosed()) {
+                this.#report("shutdown");
+                this.#finishClose();
                 return;
             }
-            if (message.id === 0) {
-                this.#ready = true;
-                if (!this.#closing) {
-                    this.refresh();
-                    this.#poll = setInterval(() => this.refresh(), 1000);
-                    this.#poll.unref();
-                }
+            if (!this.#ready)
+                void this.#stopWorker().then(() => this.#recover());
+            else
+                this.#recover();
+            return;
+        }
+        if (!this.#ready) {
+            this.#ready = true;
+            if (!this.#isClosed()) {
+                this.#state = "ready";
+                this.#refreshPending = true;
+                this.#schedulePoll();
             }
-            else {
-                const item = this.#active;
-                if (item?.request.id !== message.id) {
-                    this.#fail("unavailable");
-                    return;
+        }
+        else if (attempt?.work !== undefined) {
+            this.#settle(attempt.work, "committed");
+            this.#refreshPending = !this.#isClosed();
+        }
+        else if (attempt?.observers !== undefined) {
+            if (!isSnapshot(message.value)) {
+                this.#lost("corrupt");
+                return;
+            }
+            const snapshot = message.value;
+            if (snapshot.revision !== this.#lastRevision && attempt.observers.some(listener => this.#snapshots.has(listener))) {
+                this.#lastRevision = snapshot.revision;
+                for (const listener of attempt.observers) {
+                    if (!this.#snapshots.has(listener) || this.#isClosed())
+                        continue;
+                    try {
+                        listener(snapshot);
+                    }
+                    catch { /* Security: observer exceptions are not storage failures. */ }
                 }
-                this.#active = undefined;
-                item.done(message.value, true);
             }
-            this.#drain();
-        });
-        this.#worker.on("error", () => this.#fail("unavailable"));
-        this.#worker.on("exit", () => { if (!this.#closing || this.#active !== undefined || this.#queue.length > 0)
-            this.#fail("unavailable"); });
+        }
+        else if (this.#isClosed()) {
+            this.#finishClose();
+            return;
+        }
+        this.#backoff = 100;
+        if (!this.#isClosed())
+            this.#state = "ready";
+        this.#drain();
     }
     #drain() {
-        if (!this.#ready || this.#failed || this.#active !== undefined)
+        if (!this.#ready || this.#active !== undefined || this.#timer !== undefined || this.#state === "blocked-storage" || this.#state === "closed")
             return;
-        const next = this.#queue.shift();
-        if (next === undefined)
+        const work = this.#queue[0];
+        const id = ++this.#sequence;
+        let request;
+        if (work !== undefined) {
+            this.#active = { id, work };
+            request = { id, kind: "record", submission: work.submission };
+        }
+        else if (this.#isClosed()) {
+            this.#active = { id };
+            request = { id, kind: "close" };
+        }
+        else if (this.#refreshPending) {
+            this.#refreshPending = false;
+            this.#active = { id, observers: [...this.#snapshots] };
+            request = { id, kind: "read" };
+        }
+        else
             return;
-        this.#active = next;
-        this.#timer = setTimeout(() => this.#fail("busy"), 1500);
+        this.#timer = this.#clock.setTimeout(() => this.#lost("unavailable"), LIVENESS_MS);
         try {
-            this.#worker.postMessage(next.request);
+            this.#worker.postMessage(request);
         }
         catch {
-            this.#fail("unavailable");
+            this.#lost("unavailable");
         }
     }
-    #report(code) {
-        if (this.#reported.has(code))
+    #settle(work, result) {
+        const index = this.#queue.indexOf(work);
+        if (index < 0)
             return;
-        this.#reported.add(code);
-        for (const listener of this.#failures) {
-            try {
-                listener(code);
+        this.#queue.splice(index, 1);
+        this.#bytes -= work.bytes;
+        work.done(result);
+        this.#armExpiry();
+    }
+    #settleAll() { for (const work of [...this.#queue])
+        this.#settle(work, "skipped"); }
+    #armExpiry() {
+        this.#clock.clearTimeout(this.#expiry);
+        this.#expiry = undefined;
+        if (this.#isClosed() || this.#queue.length === 0)
+            return;
+        this.#expiry = this.#clock.setTimeout(() => {
+            this.#expiry = undefined;
+            for (const work of [...this.#queue]) {
+                if (work.expires > this.#clock.now())
+                    break;
+                if (this.#active?.work === work)
+                    this.#lost("unavailable");
+                this.#settle(work, "skipped");
             }
-            catch { /* Security: caller exceptions are not persistence diagnostics. */ }
-        }
+            this.#armExpiry();
+        }, Math.max(0, this.#queue[0].expires - this.#clock.now()));
+    }
+    #schedulePoll() {
+        this.#clock.clearTimeout(this.#poll);
+        this.#poll = this.#clock.setTimeout(() => {
+            this.#poll = undefined;
+            if (this.#isClosed() || this.#state === "blocked-storage")
+                return;
+            this.refresh();
+            this.#schedulePoll();
+        }, 1000);
+        this.#poll.unref?.();
+    }
+    #recover() {
+        if (this.#isClosed() || this.#state === "blocked-storage")
+            return;
+        this.#state = "recovering";
+        this.#recoveries = Math.min(Number.MAX_SAFE_INTEGER, this.#recoveries + 1);
+        this.#clock.clearTimeout(this.#timer);
+        const jitter = Math.max(0, Math.min(1, (this.options.random ?? Math.random)()));
+        const delay = Math.min(5000, this.#backoff * (1 + jitter * 0.2));
+        this.#backoff = Math.min(5000, this.#backoff * 2);
+        this.#timer = this.#clock.setTimeout(() => {
+            this.#timer = undefined;
+            if (this.#isClosed())
+                return;
+            if (this.#ready) {
+                this.#state = "ready";
+                this.#refreshPending = true;
+                this.#drain();
+            }
+            else
+                void this.#open();
+        }, delay);
     }
-    #fail(code) {
-        if (this.#failed)
+    #lost(code) {
+        if (this.#state === "closed")
             return;
-        this.#failed = true;
-        clearTimeout(this.#timer);
-        clearInterval(this.#poll);
         this.#report(code);
         const active = this.#active;
         this.#active = undefined;
-        active?.done(undefined, false);
-        for (const item of this.#queue.splice(0))
-            item.done(undefined, false);
-        this.#worker?.unref();
-        void this.#worker?.terminate().catch(() => { });
+        if (active?.work !== undefined)
+            this.#settle(active.work, "skipped");
+        if (code === "schema" || code === "corrupt") {
+            this.#state = this.#isClosed() ? "closing" : "blocked-storage";
+            this.#settleAll();
+        }
+        if (this.#isClosed()) {
+            this.#report("shutdown");
+            this.#finishClose();
+            return;
+        }
+        void this.#stopWorker().then(() => this.#recover());
+    }
+    #stopWorker() {
+        if (this.#stopping !== undefined)
+            return this.#stopping;
+        this.#clock.clearTimeout(this.#timer);
+        this.#timer = undefined;
+        this.#clock.clearTimeout(this.#poll);
+        this.#poll = undefined;
+        this.#ready = false;
+        ++this.#generation;
+        const worker = this.#worker;
+        this.#worker = undefined;
+        if (worker === undefined)
+            return Promise.resolve();
+        worker.unref();
+        // Invariant: a rejected terminate is not proof of death. Wait for exit before opening a replacement.
+        const exited = new Promise(resolve => worker.once("exit", () => resolve()));
+        this.#stopping = worker.terminate().then(() => { }, () => exited).then(() => { this.#stopping = undefined; });
+        return this.#stopping;
+    }
+    #finishClose() {
+        if (this.#queue.length > 0)
+            this.#report("shutdown");
+        this.#state = "closed";
+        this.#active = undefined;
+        this.#settleAll();
+        for (const timer of [this.#timer, this.#poll, this.#expiry, this.#closeTimer])
+            this.#clock.clearTimeout(timer);
+        this.#timer = this.#poll = this.#expiry = this.#closeTimer = undefined;
+        void this.#stopWorker();
+        this.#resolveClose?.();
+        this.#resolveClose = undefined;
+    }
+    #report(code) {
+        const count = this.#counts[code] ?? 0;
+        this.#counts[code] = Math.min(Number.MAX_SAFE_INTEGER, count + 1);
+        if (count > 0)
+            return;
+        for (const listener of this.#failures) {
+            try {
+                listener(code);
+            }
+            catch { /* Security: never forward arbitrary observer errors. */ }
+        }
     }
 }
 function failureCode(value) {

package/dist/features/prompt-history/store.d.ts

@@ -1,7 +1,8 @@
 import { type PromptHistoryFailure, type PromptHistorySnapshot, type PromptHistorySubmission } from "../../contracts/owned-ui/index.js";
 export declare class HistoryStorageError extends Error {
     readonly code: PromptHistoryFailure;
-    constructor(code: PromptHistoryFailure);
+    readonly certainty: "uncommitted" | "unknown";
+    constructor(code: PromptHistoryFailure, certainty?: "uncommitted" | "unknown");
 }
 export declare class PromptHistoryStore {
     #private;

package/dist/features/prompt-history/store.js

@@ -5,9 +5,11 @@ import { PRODUCT_IDENTITY } from "../../product-identity.js";
 import { assertPromptHistorySubmission, PROMPT_HISTORY_MAX_ENTRY_BYTES, PROMPT_HISTORY_MAX_TEXT_BYTES } from "../../contracts/owned-ui/index.js";
 export class HistoryStorageError extends Error {
     code;
-    constructor(code) {
+    certainty;
+    constructor(code, certainty = "uncommitted") {
         super(`Prompt history ${code}`);
         this.code = code;
+        this.certainty = certainty;
     }
 }
 const MAX_STORAGE_BYTES = 64 * 1024 * 1024;
@@ -107,14 +109,25 @@ export class PromptHistoryStore {
     }
     close() { this.#database.close(); }
     #transaction(work) {
-        this.#database.exec("BEGIN IMMEDIATE");
+        try {
+            this.#database.exec("BEGIN IMMEDIATE");
+        }
+        catch (error) {
+            throw new HistoryStorageError(classifyHistoryError(error), "uncommitted");
+        }
         try {
             work();
             this.#database.exec("COMMIT");
         }
         catch (error) {
-            this.#database.exec("ROLLBACK");
-            throw error;
+            // Invariant: only a successful rollback proves that replay cannot advance recency twice.
+            try {
+                this.#database.exec("ROLLBACK");
+            }
+            catch {
+                throw new HistoryStorageError(classifyHistoryError(error), "unknown");
+            }
+            throw new HistoryStorageError(classifyHistoryError(error), "uncommitted");
         }
     }
     #prune(limit) {

package/dist/features/prompt-history/worker.js

@@ -1,6 +1,6 @@
 import { parentPort, workerData } from "node:worker_threads";
 import { setTimeout as delay } from "node:timers/promises";
-import { PromptHistoryStore, classifyHistoryError } from "./store.js";
+import { HistoryStorageError, PromptHistoryStore, classifyHistoryError } from "./store.js";
 const port = parentPort;
 if (port !== null) {
     let store;
@@ -22,7 +22,8 @@ if (port !== null) {
                 port.postMessage({ id: request.id, ok: true, value });
             }
             catch (error) {
-                port.postMessage({ id: request.id, ok: false, code: classifyHistoryError(error) });
+                port.postMessage({ id: request.id, ok: false, code: classifyHistoryError(error),
+                    certainty: error instanceof HistoryStorageError ? error.certainty : "unknown" });
             }
         });
     });
@@ -34,7 +35,9 @@ async function retry(operation) {
             return operation();
         }
         catch (error) {
-            if (classifyHistoryError(error) !== "busy" || performance.now() >= deadline)
+            if (classifyHistoryError(error) !== "busy"
+                || error instanceof HistoryStorageError && error.certainty === "unknown"
+                || performance.now() >= deadline)
                 throw error;
             await delay(25);
         }

package/dist/foundation/launch-context/index.d.ts

@@ -0,0 +1,59 @@
+/** The contract this build emits; supersedes the pre-cutover key set it still accepts. */
+export declare const PRIVATE_LAUNCH_CONTRACT = "neutral-launch-v1";
+export declare const PRIVATE_ENVIRONMENT: Readonly<{
+    releaseRoot: "LAUNCH_CONTEXT_RELEASE_ROOT";
+    releaseId: "LAUNCH_CONTEXT_RELEASE_ID";
+    releaseDigest: "LAUNCH_CONTEXT_RELEASE_DIGEST";
+    releaseLayers: "LAUNCH_CONTEXT_RELEASE_LAYERS";
+    launchProfile: "LAUNCH_CONTEXT_PROFILE";
+    immutableWarmup: "LAUNCH_CONTEXT_WARMUP";
+}>;
+/**
+ * Keys published by releases that predate the neutral cutover. They are read when
+ * an older launcher hands this build a process, and written when this build
+ * starts a release that declares no contract of its own, so an upgrade never
+ * depends on both sides having been rebuilt at the same moment.
+ */
+export declare const SUPERSEDED_ENVIRONMENT: Readonly<{
+    releaseRoot: "A1_RELEASE_ROOT";
+    releaseId: "A1_RELEASE_ID";
+    releaseDigest: "A1_RELEASE_DIGEST";
+    releaseLayers: "A1_RELEASE_LAYERS";
+    launchProfile: "A1_LAUNCH_PROFILE";
+    immutableWarmup: "A1_IMMUTABLE_WARMUP";
+}>;
+/** A release either declares the current contract or predates contract declaration. */
+export type LaunchContractTarget = typeof PRIVATE_LAUNCH_CONTRACT | "superseded";
+export interface LaunchContext {
+    readonly releaseRoot?: string;
+    readonly releaseId?: string;
+    readonly releaseDigest?: string;
+    readonly releaseLayers?: string;
+    readonly launchProfile?: "a1" | "pi";
+    readonly immutableWarmup?: "1";
+}
+export type LaunchContextRequirement = "optional" | "profile" | "release" | "warmup";
+/** Read current keys, fall back to superseded keys per field, with bounded diagnostics. */
+export declare function readLaunchContext(environment: NodeJS.ProcessEnv, requirement?: LaunchContextRequirement, platform?: NodeJS.Platform): LaunchContext;
+/** The key set a process started for this release must receive. */
+export declare function launchEnvironmentKeys(contract: LaunchContractTarget): Readonly<Record<string, string>>;
+/** Classify metadata by the contract it declares rather than rejecting what it omits. */
+export declare function launchContractTarget(value: {
+    readonly launchContract?: unknown;
+}): LaunchContractTarget;
+/** Whether metadata was produced by a build that declares this contract. */
+export declare function isCurrentLaunchContract(value: {
+    readonly launchContract?: unknown;
+}): boolean;
+/**
+ * Rebuild owned context without inheriting a prior session's private selection. The
+ * contract selects which key set is written, so this build can start either its
+ * own releases or a retained pre-cutover release it must keep serving.
+ */
+export declare function withLaunchContext(environment: NodeJS.ProcessEnv, context: LaunchContext, platform?: NodeJS.Platform, contract?: LaunchContractTarget): NodeJS.ProcessEnv;
+/** Remove both key sets, leaving user and integration settings intact. */
+export declare function withoutLaunchContext(environment: NodeJS.ProcessEnv, platform?: NodeJS.Platform): NodeJS.ProcessEnv;
+/** Require this build's own contract where nothing older can be accepted, such as recovery capsules. */
+export declare function assertCurrentLaunchContract(value: {
+    readonly launchContract?: unknown;
+}): void;