@timurproko/a1 0.1.8-dev.ece8cef → 0.2.0

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

@@ -0,0 +1,16 @@
+import { type PromptHistoryFailure, type PromptHistorySnapshot, type PromptHistorySubmission } from "../../contracts/owned-ui/index.js";
+export declare class HistoryStorageError extends Error {
+    readonly code: PromptHistoryFailure;
+    readonly certainty: "uncommitted" | "unknown";
+    constructor(code: PromptHistoryFailure, certainty?: "uncommitted" | "unknown");
+}
+export declare class PromptHistoryStore {
+    #private;
+    readonly path: string;
+    readonly profileId: string;
+    constructor(path: string, profileId: string, limit: number, imagesDir?: string);
+    record(input: PromptHistorySubmission): void;
+    snapshot(): PromptHistorySnapshot;
+    close(): void;
+}
+export declare function classifyHistoryError(error: unknown): PromptHistoryFailure;

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

@@ -0,0 +1,219 @@
+import { DatabaseSync } from "node:sqlite";
+import { chmodSync, closeSync, lstatSync, mkdirSync, openSync, statSync } from "node:fs";
+import { dirname } from "node:path";
+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";
+import { collectImageChipIdentifiers, PromptImageSidecar } from "./image-sidecar.js";
+export class HistoryStorageError extends Error {
+    code;
+    certainty;
+    constructor(code, certainty = "uncommitted") { super(`Prompt history ${code}`); this.code = code; this.certainty = certainty; }
+}
+const MAX_STORAGE_BYTES = 64 * 1024 * 1024;
+export class PromptHistoryStore {
+    #database;
+    #sidecar;
+    path;
+    profileId;
+    constructor(path, profileId, limit, imagesDir) {
+        this.path = path;
+        this.profileId = profileId;
+        if (!Number.isInteger(limit) || limit < 10 || limit > 100 || limit % 10 !== 0)
+            throw new HistoryStorageError("schema");
+        this.#sidecar = imagesDir === undefined ? undefined : new PromptImageSidecar(imagesDir);
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        if (lstatSync(dirname(path)).isSymbolicLink())
+            throw new HistoryStorageError("unavailable");
+        if (process.platform !== "win32")
+            chmodSync(dirname(path), 0o700);
+        try {
+            closeSync(openSync(path, "wx", 0o600));
+        }
+        catch (error) {
+            if (!(error instanceof Error && "code" in error && error.code === "EEXIST"))
+                throw error;
+        }
+        if (lstatSync(path).isSymbolicLink() || !lstatSync(path).isFile())
+            throw new HistoryStorageError("unavailable");
+        if (process.platform !== "win32")
+            chmodSync(path, 0o600);
+        this.#checkSize();
+        this.#database = new DatabaseSync(path);
+        try {
+            this.#database.exec("PRAGMA busy_timeout = 25");
+            this.#transaction(() => {
+                const version = Number(this.#database.prepare("PRAGMA user_version").get()?.user_version);
+                if (version === 0) {
+                    const tables = this.#database.prepare("SELECT name FROM sqlite_master WHERE type='table'").all();
+                    if (tables.length !== 0)
+                        throw new HistoryStorageError("schema");
+                    this.#database.exec(`CREATE TABLE history_meta (id INTEGER PRIMARY KEY CHECK(id=1), schema TEXT NOT NULL, profile TEXT NOT NULL, revision INTEGER NOT NULL, limit_count INTEGER NOT NULL);
+            CREATE TABLE prompts (text TEXT PRIMARY KEY COLLATE BINARY, submission_id TEXT NOT NULL, sequence INTEGER NOT NULL UNIQUE, timestamp INTEGER NOT NULL, kind TEXT NOT NULL, cwd TEXT, session_id TEXT, bytes INTEGER NOT NULL CHECK(bytes>0 AND bytes<=1048576));
+            PRAGMA user_version=1;`);
+                    this.#database.prepare("INSERT INTO history_meta VALUES (1,?,?,0,?)").run(PRODUCT_IDENTITY.protocol.promptHistorySchema, profileId, limit);
+                }
+                else if (version !== 1)
+                    throw new HistoryStorageError("schema");
+                const meta = this.#database.prepare("SELECT schema,profile FROM history_meta WHERE id=1").get();
+                if (meta?.schema !== PRODUCT_IDENTITY.protocol.promptHistorySchema || meta?.profile !== profileId)
+                    throw new HistoryStorageError("schema");
+                this.#database.prepare("UPDATE history_meta SET limit_count=?,revision=revision+1 WHERE id=1").run(limit);
+                this.#prune(limit);
+            });
+            this.#database.exec("PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL; PRAGMA wal_autocheckpoint=128; PRAGMA journal_size_limit=8388608; PRAGMA max_page_count=8192;");
+        }
+        catch (error) {
+            this.#database.close();
+            throw error;
+        }
+        // Rationale: opportunistically reclaim any sidecar whose row was pruned in a prior process
+        // crash or by another concurrent opener. Bounded by the number of files on disk minus the
+        // surviving reference set; failures are swallowed to preserve honest history behavior.
+        this.#sweepOrphanedSidecars();
+    }
+    record(input) {
+        assertPromptHistorySubmission(input);
+        const bytes = Buffer.byteLength(input.text);
+        if (bytes > PROMPT_HISTORY_MAX_ENTRY_BYTES)
+            throw new HistoryStorageError("oversized");
+        this.#checkSize(true);
+        this.#transaction(() => {
+            const duplicate = this.#database.prepare("SELECT submission_id FROM prompts WHERE text=?").get(input.text);
+            if (duplicate?.submission_id === input.id)
+                return;
+            this.#database.exec("UPDATE history_meta SET revision=revision+1 WHERE id=1");
+            const meta = this.#database.prepare("SELECT revision,limit_count FROM history_meta WHERE id=1").get();
+            this.#database.prepare(`INSERT INTO prompts VALUES (?,?,?,?,?,?,?,?) ON CONFLICT(text) DO UPDATE SET submission_id=excluded.submission_id,sequence=excluded.sequence,timestamp=excluded.timestamp,kind=excluded.kind,cwd=excluded.cwd,session_id=excluded.session_id,bytes=excluded.bytes`)
+                .run(input.text, input.id, meta.revision, input.timestamp, input.kind, bounded(input.cwd, 8192), bounded(input.sessionId, 256), bytes);
+            this.#prune(Number(meta.limit_count));
+        });
+    }
+    snapshot() {
+        this.#database.exec("BEGIN");
+        try {
+            const meta = this.#database.prepare("SELECT revision,limit_count FROM history_meta WHERE id=1").get();
+            const entries = this.#database.prepare("SELECT text,submission_id FROM prompts ORDER BY sequence DESC LIMIT 100").all();
+            let bytes = 0;
+            const result = entries.map(row => {
+                if (typeof row.text !== "string" || typeof row.submission_id !== "string")
+                    throw new HistoryStorageError("corrupt");
+                bytes += Buffer.byteLength(row.text);
+                if (bytes > PROMPT_HISTORY_MAX_TEXT_BYTES)
+                    throw new HistoryStorageError("corrupt");
+                return { text: row.text, submissionId: row.submission_id };
+            });
+            this.#database.exec("COMMIT");
+            return { revision: Number(meta.revision), limit: Number(meta.limit_count), entries: result };
+        }
+        catch (error) {
+            this.#database.exec("ROLLBACK");
+            throw error;
+        }
+    }
+    close() { this.#database.close(); }
+    #transaction(work) {
+        try {
+            this.#database.exec("BEGIN IMMEDIATE");
+        }
+        catch (error) {
+            throw new HistoryStorageError(classifyHistoryError(error), "uncommitted");
+        }
+        try {
+            work();
+            this.#database.exec("COMMIT");
+        }
+        catch (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) {
+        const rows = this.#database.prepare("SELECT sequence,bytes FROM prompts ORDER BY sequence DESC").all();
+        let bytes = 0;
+        const dropped = [];
+        for (const [index, row] of rows.entries()) {
+            bytes += Number(row.bytes);
+            if (index >= limit || bytes > PROMPT_HISTORY_MAX_TEXT_BYTES)
+                dropped.push(row.sequence);
+        }
+        if (dropped.length === 0)
+            return;
+        // Invariant: sidecar reap uses text still referenced by SURVIVING rows so a row still
+        // referencing an id shared with a pruned row keeps the file. Collect surviving ids before
+        // deleting so a concurrent snapshot cannot see a live row whose sidecar is already gone.
+        const droppedTexts = dropped.map(sequence => this.#database.prepare("SELECT text FROM prompts WHERE sequence=?").get(sequence)?.text).filter((value) => typeof value === "string");
+        for (const sequence of dropped)
+            this.#database.prepare("DELETE FROM prompts WHERE sequence=?").run(sequence);
+        if (this.#sidecar === undefined)
+            return;
+        const survivingIds = this.#collectReferencedIdentifiers();
+        for (const text of droppedTexts) {
+            for (const id of collectImageChipIdentifiers(text)) {
+                if (!survivingIds.has(id))
+                    this.#sidecar.unlink(id);
+            }
+        }
+    }
+    #collectReferencedIdentifiers() {
+        const identifiers = new Set();
+        const rows = this.#database.prepare("SELECT text FROM prompts").all();
+        for (const row of rows) {
+            if (typeof row.text !== "string")
+                continue;
+            for (const id of collectImageChipIdentifiers(row.text))
+                identifiers.add(id);
+        }
+        return identifiers;
+    }
+    #sweepOrphanedSidecars() {
+        if (this.#sidecar === undefined)
+            return;
+        try {
+            this.#sidecar.sweep(this.#collectReferencedIdentifiers());
+        }
+        catch { /* Rationale: sidecar sweep never blocks history readiness. */ }
+    }
+    #checkSize(maintain = false) {
+        let size = 0;
+        for (const suffix of ["", "-wal", "-shm"]) {
+            try {
+                if (lstatSync(this.path + suffix).isSymbolicLink())
+                    throw new HistoryStorageError("unavailable");
+                size += statSync(this.path + suffix).size;
+            }
+            catch (error) {
+                if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+                    throw error;
+            }
+        }
+        if (size > MAX_STORAGE_BYTES && maintain) {
+            this.#database.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+            this.#checkSize();
+        }
+        else if (size > MAX_STORAGE_BYTES)
+            throw new HistoryStorageError("capacity");
+    }
+}
+function bounded(value, bytes) {
+    return value !== undefined && Buffer.byteLength(value) <= bytes ? value : null;
+}
+export function classifyHistoryError(error) {
+    if (error instanceof HistoryStorageError)
+        return error.code;
+    if (error instanceof Error && "errcode" in error) {
+        const code = Number(error.errcode) & 0xff;
+        if (code === 5 || code === 6)
+            return "busy";
+        if (code === 11 || code === 26)
+            return "corrupt";
+        if (code === 13)
+            return "capacity";
+    }
+    return "unavailable";
+}

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

@@ -0,0 +1,9 @@
+import type { PromptHistorySubmission } from "../../contracts/owned-ui/index.js";
+export type HistoryWorkerRequest = {
+    id: number;
+    kind: "read" | "close";
+} | {
+    id: number;
+    kind: "record";
+    submission: PromptHistorySubmission;
+};

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

@@ -0,0 +1,45 @@
+import { parentPort, workerData } from "node:worker_threads";
+import { setTimeout as delay } from "node:timers/promises";
+import { HistoryStorageError, PromptHistoryStore, classifyHistoryError } from "./store.js";
+const port = parentPort;
+if (port !== null) {
+    let store;
+    let chain = Promise.resolve();
+    const options = workerData;
+    const open = retry(() => { store = new PromptHistoryStore(options.path, options.profileId, options.limit, options.imagesDir); });
+    void open.then(() => port.postMessage({ id: 0, ok: true }), error => port.postMessage({ id: 0, ok: false, code: classifyHistoryError(error) }));
+    port.on("message", (request) => {
+        chain = chain.then(async () => {
+            try {
+                await open;
+                if (request.kind === "close") {
+                    store.close();
+                    port.postMessage({ id: request.id, ok: true });
+                    port.close();
+                    return;
+                }
+                const value = await retry(() => request.kind === "record" ? store.record(request.submission) : store.snapshot());
+                port.postMessage({ id: request.id, ok: true, value });
+            }
+            catch (error) {
+                port.postMessage({ id: request.id, ok: false, code: classifyHistoryError(error),
+                    certainty: error instanceof HistoryStorageError ? error.certainty : "unknown" });
+            }
+        });
+    });
+}
+async function retry(operation) {
+    const deadline = performance.now() + 1000;
+    for (;;) {
+        try {
+            return operation();
+        }
+        catch (error) {
+            if (classifyHistoryError(error) !== "busy"
+                || error instanceof HistoryStorageError && error.certainty === "unknown"
+                || performance.now() >= deadline)
+                throw error;
+            await delay(25);
+        }
+    }
+}

package/dist/features/prompt-suggestions/diagnostics.d.ts

@@ -0,0 +1,18 @@
+import { type SuggestionDiagnosticObserver, type SuggestionDiagnosticRecord } from "../../contracts/owned-ui/index.js";
+export interface SuggestionDiagnosticCaptureOptions {
+    readonly enabled?: boolean;
+    /** Explicit local destination, or an injected sink for deterministic I/O tests. */
+    readonly destination?: string;
+    readonly writeSnapshot?: (snapshot: string) => Promise<void>;
+}
+/** Bounded metadata snapshots; one in-flight write and one replaceable latest snapshot. */
+export declare class SuggestionDiagnosticCapture implements SuggestionDiagnosticObserver {
+    #private;
+    readonly options: SuggestionDiagnosticCaptureOptions;
+    constructor(options?: SuggestionDiagnosticCaptureOptions);
+    record(record: SuggestionDiagnosticRecord): void;
+    snapshot(): readonly SuggestionDiagnosticRecord[];
+    /** Explicit evidence boundary, never awaited by input or rendering. */
+    flush(): Promise<void>;
+    dispose(): void;
+}

package/dist/features/prompt-suggestions/diagnostics.js

@@ -0,0 +1,82 @@
+import { writeFile } from "node:fs/promises";
+import { SUGGESTION_DECISION_REASONS, SUGGESTION_DIAGNOSTIC_EVENTS, } from "../../contracts/owned-ui/index.js";
+/** Bounded metadata snapshots; one in-flight write and one replaceable latest snapshot. */
+export class SuggestionDiagnosticCapture {
+    #records = [];
+    #pending;
+    #writing;
+    #disposed = false;
+    #write;
+    options;
+    constructor(options = {}) {
+        this.options = options;
+        this.#write = options.writeSnapshot ?? (options.destination === undefined ? undefined
+            : snapshot => writeFile(options.destination, snapshot, { encoding: "utf8", mode: 0o600 }));
+    }
+    record(record) {
+        if (!this.options.enabled || this.#disposed)
+            return;
+        const safe = sanitize(record);
+        if (safe === null)
+            return;
+        this.#records.push(safe);
+        if (this.#records.length > 128)
+            this.#records.shift();
+        let snapshot = this.#serialize();
+        while (Buffer.byteLength(snapshot, "utf8") > 65_536) {
+            this.#records.shift();
+            snapshot = this.#serialize();
+        }
+        if (this.#write) {
+            this.#pending = snapshot;
+            this.#pump();
+        }
+    }
+    snapshot() { return this.#records.map(record => ({ ...record })); }
+    /** Explicit evidence boundary, never awaited by input or rendering. */
+    async flush() {
+        while (this.#writing)
+            await this.#writing;
+    }
+    dispose() {
+        this.#disposed = true;
+        this.#records = [];
+        this.#pending = undefined;
+    }
+    #serialize() { return JSON.stringify({ schema: "prompt-suggestion-diagnostics-v1", records: this.#records }); }
+    #pump() {
+        if (this.#writing || this.#pending === undefined || !this.#write || this.#disposed)
+            return;
+        const snapshot = this.#pending;
+        this.#pending = undefined;
+        this.#writing = Promise.resolve().then(() => this.#write(snapshot)).catch(() => {
+            // Security: do not retain or display raw filesystem/provider errors.
+        }).finally(() => {
+            this.#writing = undefined;
+            this.#pump();
+        });
+    }
+}
+function sanitize(record) {
+    if (!SUGGESTION_DIAGNOSTIC_EVENTS.includes(record.event))
+        return null;
+    const reasoning = ["ordinary", "off", "minimal", "low", "medium", "high", "xhigh", "max", "unavailable"].includes(record.reasoning)
+        ? record.reasoning : "unavailable";
+    const reason = record.reason !== undefined && SUGGESTION_DECISION_REASONS.includes(record.reason) ? record.reason : undefined;
+    // Security: explicit projection prevents arbitrary extra fields, including raw error payloads, from escaping.
+    return {
+        event: record.event, ...(reason === undefined ? {} : { reason }),
+        session: boundedNumber(record.session), run: boundedNumber(record.run), response: boundedNumber(record.response),
+        request: boundedNumber(record.request), provider: identifier(record.provider), model: identifier(record.model),
+        reasoning, elapsedMs: boundedNumber(record.elapsedMs),
+    };
+}
+function boundedNumber(value) {
+    return Number.isFinite(value) ? Math.min(Number.MAX_SAFE_INTEGER, Math.max(0, Math.floor(value))) : 0;
+}
+function identifier(value) {
+    // Security: identifiers are metadata, not display names or arbitrary JSON. Reject controls/path-shaped values.
+    if (typeof value !== "string" || /[\p{C}\\\s]/u.test(value) || value.includes(":") || value.startsWith("/"))
+        return "redacted";
+    return value.slice(0, 64);
+}

package/dist/features/prompt-suggestions/index.d.ts

@@ -0,0 +1,2 @@
+export { SuggestionDiagnosticCapture } from "./diagnostics.js";
+export type { SuggestionDiagnosticCaptureOptions } from "./diagnostics.js";

package/dist/features/prompt-suggestions/index.js

@@ -0,0 +1 @@
+export { SuggestionDiagnosticCapture } from "./diagnostics.js";

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;

package/dist/foundation/launch-context/index.js

@@ -0,0 +1,136 @@
+/** The contract this build emits; supersedes the pre-cutover key set it still accepts. */
+export const PRIVATE_LAUNCH_CONTRACT = "neutral-launch-v1";
+export const PRIVATE_ENVIRONMENT = Object.freeze({
+    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 const SUPERSEDED_ENVIRONMENT = Object.freeze({
+    releaseRoot: "A1_RELEASE_ROOT",
+    releaseId: "A1_RELEASE_ID",
+    releaseDigest: "A1_RELEASE_DIGEST",
+    releaseLayers: "A1_RELEASE_LAYERS",
+    launchProfile: "A1_LAUNCH_PROFILE",
+    immutableWarmup: "A1_IMMUTABLE_WARMUP",
+});
+const PRIVATE_ENTRIES = Object.entries(PRIVATE_ENVIRONMENT);
+const SUPERSEDED_ENTRIES = Object.entries(SUPERSEDED_ENVIRONMENT);
+const PRIVATE_KEYS = new Set([...Object.values(PRIVATE_ENVIRONMENT), ...Object.values(SUPERSEDED_ENVIRONMENT)]);
+const LOGICAL_KEYS = new Map(PRIVATE_ENTRIES.map(([logical, key]) => [key, logical]));
+const SUPERSEDED_LOGICAL_KEYS = new Map(SUPERSEDED_ENTRIES.map(([logical, key]) => [key, logical]));
+/** Read current keys, fall back to superseded keys per field, with bounded diagnostics. */
+export function readLaunchContext(environment, requirement = "optional", platform = process.platform) {
+    const values = {};
+    const superseded = {};
+    // Performance: enumerate names only for Windows casing; never fetch unrelated environment values.
+    if (platform === "win32") {
+        for (const name of Object.keys(environment)) {
+            const upper = name.toUpperCase();
+            const logical = LOGICAL_KEYS.get(upper);
+            if (logical !== undefined)
+                acceptValue(values, logical, environment[name]);
+            const supersededLogical = SUPERSEDED_LOGICAL_KEYS.get(upper);
+            if (supersededLogical !== undefined)
+                acceptValue(superseded, supersededLogical, environment[name]);
+        }
+    }
+    else {
+        for (const [logical, key] of PRIVATE_ENTRIES) {
+            if (Object.prototype.propertyIsEnumerable.call(environment, key))
+                acceptValue(values, logical, environment[key]);
+        }
+        for (const [logical, key] of SUPERSEDED_ENTRIES) {
+            if (Object.prototype.propertyIsEnumerable.call(environment, key))
+                acceptValue(superseded, logical, environment[key]);
+        }
+    }
+    // Compatibility: the current key wins wherever both are present, so a launcher that
+    // emits this contract is never overruled by an inherited pre-cutover value.
+    for (const [logical, value] of Object.entries(superseded))
+        if (values[logical] === undefined)
+            values[logical] = value;
+    if (values.launchProfile !== undefined && values.launchProfile !== "a1" && values.launchProfile !== "pi") {
+        throw invalidContext("launchProfile", "unsupported profile");
+    }
+    if (values.immutableWarmup !== undefined && values.immutableWarmup !== "1")
+        throw invalidContext("immutableWarmup", "invalid permission flag");
+    if (values.releaseDigest !== undefined && !/^[a-f0-9]{64}$/.test(values.releaseDigest))
+        throw invalidContext("releaseDigest", "invalid digest");
+    if (requirement === "profile")
+        requireFields(values, ["launchProfile"]);
+    if (requirement === "release" || requirement === "warmup") {
+        requireFields(values, ["releaseRoot", "releaseId", "releaseDigest"]);
+        // Compatibility: Windows drops an empty value from a child environment block, so a
+        // release with no dependency layer arrives without the key it was given. The
+        // layer list is metadata of the release being started, never authority, and an
+        // absent list means the same thing the empty string does.
+        if (values.releaseLayers === undefined)
+            values.releaseLayers = "";
+    }
+    if (requirement === "warmup")
+        requireFields(values, ["immutableWarmup"]);
+    return Object.freeze(values);
+}
+/** The key set a process started for this release must receive. */
+export function launchEnvironmentKeys(contract) {
+    return contract === PRIVATE_LAUNCH_CONTRACT ? PRIVATE_ENVIRONMENT : SUPERSEDED_ENVIRONMENT;
+}
+/** Classify metadata by the contract it declares rather than rejecting what it omits. */
+export function launchContractTarget(value) {
+    return value.launchContract === PRIVATE_LAUNCH_CONTRACT ? PRIVATE_LAUNCH_CONTRACT : "superseded";
+}
+/** Whether metadata was produced by a build that declares this contract. */
+export function isCurrentLaunchContract(value) {
+    return value.launchContract === PRIVATE_LAUNCH_CONTRACT;
+}
+/**
+ * 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 function withLaunchContext(environment, context, platform = process.platform, contract = PRIVATE_LAUNCH_CONTRACT) {
+    const result = withoutLaunchContext(environment, platform);
+    for (const [logical, key] of Object.entries(launchEnvironmentKeys(contract))) {
+        const value = context[logical];
+        if (value !== undefined)
+            result[key] = value;
+    }
+    readLaunchContext(result, "optional", platform);
+    return result;
+}
+/** Remove both key sets, leaving user and integration settings intact. */
+export function withoutLaunchContext(environment, platform = process.platform) {
+    return Object.fromEntries(Object.entries(environment).filter(([key]) => !PRIVATE_KEYS.has(platform === "win32" ? key.toUpperCase() : key)));
+}
+/** Require this build's own contract where nothing older can be accepted, such as recovery capsules. */
+export function assertCurrentLaunchContract(value) {
+    if (value.launchContract !== PRIVATE_LAUNCH_CONTRACT) {
+        throw new Error("Unsupported private launch contract. Stop existing processes and install the current package directly with npm; review disposable runtime/release state before any manual reset. User settings, sessions, and history must be preserved.");
+    }
+}
+function acceptValue(values, logical, value) {
+    if (value === undefined)
+        return;
+    if (values[logical] !== undefined && values[logical] !== value)
+        throw invalidContext(logical, "conflicting environment key casing");
+    if (typeof value !== "string" || value.includes("\0") || (value.length === 0 && logical !== "releaseLayers"))
+        throw invalidContext(logical, "invalid value");
+    values[logical] = value;
+}
+function requireFields(values, fields) {
+    for (const field of fields)
+        if (values[field] === undefined)
+            throw invalidContext(field, "required current-contract field is missing");
+}
+function invalidContext(logical, reason) {
+    return new Error(`Invalid private launch context (${logical}): ${reason}`);
+}

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

@@ -0,0 +1,2 @@
+export { runLaunchGuardian } from "./main.js";
+export type { LaunchGuardianOptions } from "./main.js";

package/dist/foundation/launch-guardian/index.js

@@ -0,0 +1 @@
+export { runLaunchGuardian } from "./main.js";

package/dist/foundation/launch-guardian/main.d.ts

@@ -0,0 +1,33 @@
+import type { LaunchInstanceStopIntent, LaunchProfileId, SupervisorCommand } from "../lifecycle/index.js";
+import { type SessionSelection } from "../lifecycle/index.js";
+import { type NativeProcessInspector, type ProcessContainment } from "../process-containment/index.js";
+interface GuardianControl {
+    connect(endpoint: string, timeoutMs?: number): Promise<unknown>;
+    command(command: SupervisorCommand): Promise<{
+        readonly ok: boolean;
+        readonly error?: {
+            readonly code: string;
+            readonly message: string;
+        };
+    }>;
+    on(event: "stopIntent", listener: (intent: LaunchInstanceStopIntent) => void): unknown;
+    on(event: "disconnect", listener: () => void): unknown;
+    off(event: "stopIntent", listener: (intent: LaunchInstanceStopIntent) => void): unknown;
+    off(event: "disconnect", listener: () => void): unknown;
+    close(): void;
+}
+export interface LaunchGuardianOptions {
+    readonly profileId: LaunchProfileId;
+    readonly releaseRoot: string;
+    readonly uiEntry: string;
+    readonly sessionSelection?: SessionSelection;
+    readonly environment?: NodeJS.ProcessEnv;
+    readonly cwd?: string;
+    readonly helperPath?: string;
+    readonly inspector?: NativeProcessInspector;
+    readonly control?: GuardianControl;
+    readonly containment?: ProcessContainment;
+    readonly ensureHelper?: (path: string) => Promise<void>;
+}
+export declare function runLaunchGuardian(options: LaunchGuardianOptions): Promise<number>;
+export {};