@timurproko/a1 0.1.1-dev.6 → 0.1.1-dev.7

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

@@ -0,0 +1,31 @@
+import type { LaunchInstanceStopIntent, LaunchProfileId, SupervisorCommand } 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 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 {};

package/dist/src/foundation/launch-guardian/main.js

@@ -0,0 +1,165 @@
+import { randomUUID } from "node:crypto";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+import { resolve } from "node:path";
+import { assertLaunchProfileId } from "../lifecycle/index.js";
+import { closeVerifiedContainment, LinuxNativeProcessInspector, NativeGuardianContainment, resolveProcessGuardianPath, verifyProcessGuardianArtifact, WindowsNativeProcessInspector, } from "../process-containment/index.js";
+import { SupervisorClient } from "../protocol/index.js";
+import { resolveProductPaths } from "../supervision/index.js";
+export async function runLaunchGuardian(options) {
+    assertLaunchProfileId(options.profileId);
+    const environment = { ...(options.environment ?? process.env) };
+    const paths = resolveProductPaths(environment);
+    const instanceId = randomUUID();
+    const helperPath = options.helperPath ?? resolveProcessGuardianPath(options.releaseRoot, environment);
+    const inspector = options.inspector ?? platformInspector(helperPath);
+    await (options.ensureHelper ?? verifyProcessGuardianArtifact)(helperPath);
+    const guardianIdentity = await inspector.observe(process.pid);
+    if (!guardianIdentity)
+        throw diagnosticError("launch guardian cannot verify its own native process identity", "PROCESS_IDENTITY_UNAVAILABLE");
+    const client = options.control ?? new SupervisorClient(environment[PRODUCT_IDENTITY.environment.releaseId]);
+    await client.connect(paths.endpoint);
+    const containment = options.containment ?? new NativeGuardianContainment(instanceId, helperPath, resolve(paths.runtimeDir, "launch-instances", `${instanceId}.ready.json`));
+    const stop = stopRequests(client, instanceId);
+    let rootIdentity = null;
+    try {
+        await requireAccepted(client, {
+            type: "create-launch-instance",
+            requestId: randomUUID(),
+            instanceId,
+            profileId: options.profileId,
+            shutdownPolicy: "terminate-tree-on-close",
+            guardianIdentity,
+        });
+        let handle;
+        try {
+            handle = await containment.spawn(process.execPath, [options.uiEntry], {
+                cwd: options.cwd ?? process.cwd(),
+                environment: environmentEntries(environment),
+                ...(environment.TERM ? { terminalType: environment.TERM } : {}),
+            });
+            rootIdentity = handle.identity;
+            await requireAccepted(client, {
+                type: "activate-launch-instance",
+                requestId: randomUUID(),
+                instanceId,
+                rootIdentity,
+                containmentIdentity: containment.identity,
+            });
+        }
+        catch (error) {
+            const outcome = failureOutcome(error, "guardian-error");
+            await completeBestEffort(client, instanceId, "completed", outcome);
+            throw error;
+        }
+        const outcome = await Promise.race([
+            handle.outcome,
+            stop.requested.then(async (reason) => {
+                if (reason !== "supervisor-disconnect") {
+                    await requireAccepted(client, {
+                        type: "begin-launch-instance-stop",
+                        requestId: randomUUID(),
+                        instanceId,
+                        reason,
+                    });
+                }
+                if (!rootIdentity)
+                    return failureOutcome(new Error("launch root identity is unavailable"), "cleanup-error");
+                const result = await closeVerifiedContainment(containment, inspector, rootIdentity, reason);
+                await containment.close();
+                if (reason === "supervisor-disconnect" && result.outcome.kind === "stopped") {
+                    return {
+                        kind: "interrupted",
+                        reason,
+                        message: "supervisor disconnected after local launch-instance containment closed",
+                    };
+                }
+                return result.outcome;
+            }),
+        ]);
+        await containment.close();
+        if (outcome.kind !== "interrupted" || outcome.reason !== "supervisor-disconnect") {
+            await completeBestEffort(client, instanceId, outcome.kind === "interrupted" || outcome.kind === "cleanup-error" ? "interrupted" : "completed", outcome);
+        }
+        return exitCode(outcome);
+    }
+    catch (error) {
+        await containment.close().catch(() => undefined);
+        throw error;
+    }
+    finally {
+        stop.dispose();
+        client.close();
+    }
+}
+function platformInspector(helperPath) {
+    if (process.platform === "win32")
+        return new WindowsNativeProcessInspector(helperPath);
+    if (process.platform === "linux")
+        return new LinuxNativeProcessInspector();
+    throw diagnosticError(`launch-instance process containment is unsupported on ${process.platform}`, "CONTAINMENT_UNSUPPORTED");
+}
+function stopRequests(client, instanceId) {
+    let resolveStop;
+    let settled = false;
+    const requested = new Promise(resolvePromise => { resolveStop = resolvePromise; });
+    const request = (reason) => {
+        if (settled)
+            return;
+        settled = true;
+        resolveStop(reason);
+    };
+    const onStopIntent = (intent) => {
+        if (intent.instanceId === instanceId)
+            request(intent.reason);
+    };
+    const onDisconnect = () => request("supervisor-disconnect");
+    const onSigterm = () => request("user-request");
+    const onSigint = () => undefined;
+    client.on("stopIntent", onStopIntent);
+    client.on("disconnect", onDisconnect);
+    process.once("SIGTERM", onSigterm);
+    process.on("SIGINT", onSigint);
+    return {
+        requested,
+        dispose() {
+            client.off("stopIntent", onStopIntent);
+            client.off("disconnect", onDisconnect);
+            process.off("SIGTERM", onSigterm);
+            process.off("SIGINT", onSigint);
+        },
+    };
+}
+async function requireAccepted(client, command) {
+    const result = await client.command(command);
+    if (!result.ok)
+        throw diagnosticError(result.error?.message ?? `supervisor rejected ${command.type}`, result.error?.code ?? "SUPERVISOR_REJECTED");
+}
+async function completeBestEffort(client, instanceId, terminalState, outcome) {
+    await requireAccepted(client, {
+        type: "complete-launch-instance",
+        requestId: randomUUID(),
+        instanceId,
+        terminalState,
+        outcome,
+    }).catch(() => undefined);
+}
+function environmentEntries(environment) {
+    return Object.fromEntries(Object.entries(environment).filter((entry) => entry[1] !== undefined));
+}
+function failureOutcome(error, kind) {
+    return {
+        kind,
+        message: error instanceof Error ? error.message : String(error),
+        code: error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : null,
+    };
+}
+function exitCode(outcome) {
+    if (outcome.kind === "exited")
+        return outcome.exitCode;
+    if (outcome.kind === "stopped")
+        return 0;
+    return 1;
+}
+function diagnosticError(message, code) {
+    return Object.assign(new Error(`A1: ${message}`), { code });
+}

package/dist/src/foundation/lifecycle/commands.d.ts

@@ -0,0 +1,40 @@
+import type { LaunchInstanceId, LaunchInstanceOutcome, LaunchInstanceShutdownPolicy, LaunchInstanceStopReason, ProcessContainmentIdentity } from "./launch-instance.js";
+import type { LaunchProfileId, NativeProcessIdentity, RequestId } from "./model.js";
+export type SupervisorCommand = {
+    readonly type: "create-launch-instance";
+    readonly requestId: RequestId;
+    readonly instanceId: LaunchInstanceId;
+    readonly profileId: LaunchProfileId;
+    readonly shutdownPolicy: LaunchInstanceShutdownPolicy;
+    readonly guardianIdentity: NativeProcessIdentity;
+} | {
+    readonly type: "activate-launch-instance";
+    readonly requestId: RequestId;
+    readonly instanceId: LaunchInstanceId;
+    readonly rootIdentity: NativeProcessIdentity;
+    readonly containmentIdentity: ProcessContainmentIdentity;
+} | {
+    readonly type: "begin-launch-instance-stop";
+    readonly requestId: RequestId;
+    readonly instanceId: LaunchInstanceId;
+    readonly reason: LaunchInstanceStopReason;
+} | {
+    readonly type: "complete-launch-instance";
+    readonly requestId: RequestId;
+    readonly instanceId: LaunchInstanceId;
+    readonly terminalState: "completed" | "interrupted";
+    readonly outcome: LaunchInstanceOutcome;
+} | {
+    readonly type: "reconcile-launch-instance";
+    readonly requestId: RequestId;
+    readonly instanceId: LaunchInstanceId;
+} | {
+    readonly type: "resynchronize";
+    readonly requestId: RequestId;
+};
+export interface LaunchInstanceStopIntent {
+    readonly type: "stop-launch-instance";
+    readonly requestId: RequestId;
+    readonly instanceId: LaunchInstanceId;
+    readonly reason: LaunchInstanceStopReason;
+}

package/dist/src/foundation/lifecycle/commands.js

@@ -0,0 +1 @@
+export {};

package/dist/src/foundation/lifecycle/index.d.ts

@@ -1,2 +1,4 @@
+export * from "./commands.js";
+export * from "./launch-instance.js";
 export * from "./model.js";
 export * from "./paths.js";

package/dist/src/foundation/lifecycle/index.js

@@ -1,2 +1,4 @@
+export * from "./commands.js";
+export * from "./launch-instance.js";
 export * from "./model.js";
 export * from "./paths.js";

package/dist/src/foundation/lifecycle/launch-instance.d.ts

@@ -0,0 +1,46 @@
+import type { LaunchProfileId, NativeProcessIdentity } from "./model.js";
+export type LaunchInstanceId = string;
+export type LaunchInstanceState = "requested" | "active" | "stopping" | "completed" | "interrupted";
+export type LaunchInstanceShutdownPolicy = "terminate-tree-on-close";
+export type LaunchInstanceStopReason = "owner-disconnect" | "supervisor-disconnect" | "user-request" | "update";
+export interface ProcessContainmentIdentity {
+    readonly provider: string;
+    readonly token: string;
+}
+export type LaunchInstanceOutcome = {
+    readonly kind: "exited";
+    readonly exitCode: number;
+} | {
+    readonly kind: "signaled";
+    readonly signal: string;
+} | {
+    readonly kind: "stopped";
+    readonly reason: LaunchInstanceStopReason;
+} | {
+    readonly kind: "spawn-error" | "guardian-error" | "cleanup-error";
+    readonly message: string;
+    readonly code: string | null;
+} | {
+    readonly kind: "interrupted";
+    readonly reason: "owner-disconnect" | "supervisor-disconnect" | "guardian-exit" | "legacy-migration";
+    readonly message: string;
+};
+export interface LaunchInstance {
+    readonly id: LaunchInstanceId;
+    readonly ownerClientId: string;
+    readonly profileId: LaunchProfileId;
+    readonly state: LaunchInstanceState;
+    readonly shutdownPolicy: LaunchInstanceShutdownPolicy;
+    readonly guardianIdentity: NativeProcessIdentity;
+    readonly rootIdentity: NativeProcessIdentity | null;
+    readonly containmentIdentity: ProcessContainmentIdentity | null;
+    readonly createdAt: string;
+    readonly activatedAt: string | null;
+    readonly stoppingAt: string | null;
+    readonly completedAt: string | null;
+    readonly outcome: LaunchInstanceOutcome | null;
+}
+export declare function assertLaunchInstance(instance: LaunchInstance): void;
+export declare function assertLaunchInstanceTransition(previous: LaunchInstance, next: LaunchInstance): void;
+export declare function assertProcessContainmentIdentity(identity: ProcessContainmentIdentity): void;
+export declare function assertLaunchInstanceOutcome(outcome: LaunchInstanceOutcome): void;

package/dist/src/foundation/lifecycle/launch-instance.js

@@ -0,0 +1,134 @@
+import { assertLaunchProfileId, assertNativeProcessIdentity } from "./model.js";
+const ALLOWED_TRANSITIONS = {
+    requested: ["active", "completed", "interrupted"],
+    active: ["stopping", "completed", "interrupted"],
+    stopping: ["completed", "interrupted"],
+    completed: [],
+    interrupted: [],
+};
+export function assertLaunchInstance(instance) {
+    assertIdentifier(instance.id, "launch instance identity");
+    assertIdentifier(instance.ownerClientId, "launch instance owner identity");
+    assertLaunchProfileId(instance.profileId);
+    if (!(instance.state in ALLOWED_TRANSITIONS))
+        throw new TypeError(`invalid launch instance state: ${String(instance.state)}`);
+    if (instance.shutdownPolicy !== "terminate-tree-on-close")
+        throw new TypeError("launch instance shutdown policy must terminate its process tree on close");
+    assertNativeProcessIdentity(instance.guardianIdentity);
+    if (instance.rootIdentity !== null)
+        assertNativeProcessIdentity(instance.rootIdentity);
+    if (instance.containmentIdentity !== null)
+        assertProcessContainmentIdentity(instance.containmentIdentity);
+    assertTimestamp(instance.createdAt, "launch instance creation time");
+    assertOptionalTimestamp(instance.activatedAt, "launch instance activation time");
+    assertOptionalTimestamp(instance.stoppingAt, "launch instance stopping time");
+    assertOptionalTimestamp(instance.completedAt, "launch instance completion time");
+    if (instance.outcome !== null)
+        assertLaunchInstanceOutcome(instance.outcome);
+    if (instance.state === "requested") {
+        if (instance.rootIdentity !== null || instance.containmentIdentity !== null || instance.activatedAt !== null) {
+            throw new TypeError("requested launch instance cannot have active runtime ownership");
+        }
+        if (instance.stoppingAt !== null || instance.completedAt !== null || instance.outcome !== null) {
+            throw new TypeError("requested launch instance cannot have stopping or terminal state");
+        }
+        return;
+    }
+    if (instance.state === "active" || instance.state === "stopping") {
+        if (instance.rootIdentity === null || instance.containmentIdentity === null || instance.activatedAt === null) {
+            throw new TypeError(`${instance.state} launch instance requires root and containment ownership`);
+        }
+        if (instance.completedAt !== null || instance.outcome !== null)
+            throw new TypeError(`${instance.state} launch instance cannot have a terminal outcome`);
+        if (instance.state === "active" && instance.stoppingAt !== null)
+            throw new TypeError("active launch instance cannot have a stopping time");
+        if (instance.state === "stopping" && instance.stoppingAt === null)
+            throw new TypeError("stopping launch instance requires a stopping time");
+        return;
+    }
+    if (instance.completedAt === null || instance.outcome === null)
+        throw new TypeError("terminal launch instance requires completion time and outcome");
+    if (instance.state === "completed" && instance.outcome.kind === "interrupted")
+        throw new TypeError("completed launch instance cannot carry an interrupted outcome");
+    if (instance.state === "interrupted" && instance.outcome.kind !== "interrupted" && instance.outcome.kind !== "cleanup-error") {
+        throw new TypeError("interrupted launch instance requires an interrupted or cleanup-error outcome");
+    }
+}
+export function assertLaunchInstanceTransition(previous, next) {
+    assertLaunchInstance(previous);
+    assertLaunchInstance(next);
+    if (previous.id !== next.id || previous.ownerClientId !== next.ownerClientId || previous.profileId !== next.profileId) {
+        throw new TypeError("launch instance identity and ownership are immutable");
+    }
+    if (previous.shutdownPolicy !== next.shutdownPolicy
+        || !sameProcessIdentity(previous.guardianIdentity, next.guardianIdentity)
+        || previous.createdAt !== next.createdAt) {
+        throw new TypeError("launch instance guardian, policy, and creation identity are immutable");
+    }
+    const allowedTransitions = ALLOWED_TRANSITIONS[previous.state];
+    if (!allowedTransitions.includes(next.state)) {
+        throw new TypeError(`invalid launch instance transition: ${previous.state} -> ${next.state}`);
+    }
+    if (previous.rootIdentity !== null && !sameProcessIdentity(previous.rootIdentity, next.rootIdentity)) {
+        throw new TypeError("launch instance root identity is immutable after activation");
+    }
+    if (previous.containmentIdentity !== null && !sameContainmentIdentity(previous.containmentIdentity, next.containmentIdentity)) {
+        throw new TypeError("launch instance containment identity is immutable after activation");
+    }
+}
+export function assertProcessContainmentIdentity(identity) {
+    assertIdentifier(identity.provider, "process containment provider");
+    assertIdentifier(identity.token, "process containment token");
+}
+export function assertLaunchInstanceOutcome(outcome) {
+    if (outcome.kind === "exited") {
+        if (!Number.isSafeInteger(outcome.exitCode))
+            throw new TypeError("launch instance exit code must be a safe integer");
+        return;
+    }
+    if (outcome.kind === "signaled") {
+        assertIdentifier(outcome.signal, "launch instance signal");
+        return;
+    }
+    if (outcome.kind === "stopped") {
+        if (!["owner-disconnect", "supervisor-disconnect", "user-request", "update"].includes(outcome.reason)) {
+            throw new TypeError("invalid launch instance stop reason");
+        }
+        return;
+    }
+    if (outcome.kind === "interrupted") {
+        if (!["owner-disconnect", "supervisor-disconnect", "guardian-exit", "legacy-migration"].includes(outcome.reason)) {
+            throw new TypeError("invalid launch instance interruption reason");
+        }
+        assertDiagnostic(outcome.message, "launch instance interruption message");
+        return;
+    }
+    if (outcome.kind !== "spawn-error" && outcome.kind !== "guardian-error" && outcome.kind !== "cleanup-error") {
+        throw new TypeError(`invalid launch instance outcome: ${String(outcome.kind)}`);
+    }
+    assertDiagnostic(outcome.message, "launch instance failure message");
+    if (outcome.code !== null)
+        assertIdentifier(outcome.code, "launch instance failure code");
+}
+function sameProcessIdentity(left, right) {
+    return right !== null && left.pid === right.pid && left.startIdentity === right.startIdentity;
+}
+function sameContainmentIdentity(left, right) {
+    return right !== null && left.provider === right.provider && left.token === right.token;
+}
+function assertIdentifier(value, name) {
+    if (!value || value.length > 512 || value.includes("\0"))
+        throw new TypeError(`${name} must be non-empty, bounded, and contain no null byte`);
+}
+function assertDiagnostic(value, name) {
+    if (!value || value.length > 4_096 || value.includes("\0"))
+        throw new TypeError(`${name} must be non-empty, bounded, and contain no null byte`);
+}
+function assertTimestamp(value, name) {
+    if (!value || !Number.isFinite(Date.parse(value)))
+        throw new TypeError(`${name} must be a valid timestamp`);
+}
+function assertOptionalTimestamp(value, name) {
+    if (value !== null)
+        assertTimestamp(value, name);
+}

package/dist/src/foundation/lifecycle/model.d.ts

@@ -2,7 +2,6 @@ export type LaunchProfileId = "a1" | "pi" | "sandbox";
 export type GenerationId = string;
 export type DriverProfileId = string;
 export type RequestId = string;
-export type ForegroundTerminalLeaseId = string;
 export interface TerminalDimensions {
     readonly columns: number;
     readonly rows: number;
@@ -42,55 +41,20 @@ export type TransparentTerminalLifecycleOutcome = {
     readonly message: string;
     readonly code: string | null;
 };
-export type ForegroundTerminalLeaseState = "requested" | "active" | "released";
-export interface ForegroundTerminalLease {
-    readonly id: ForegroundTerminalLeaseId;
-    readonly ownerId: string;
-    readonly profile: TransparentTerminalLaunchProfile;
-    readonly state: ForegroundTerminalLeaseState;
-    readonly generationId: GenerationId | null;
-    readonly processIdentity: NativeProcessIdentity | null;
-    readonly acquiredAt: string;
-    readonly heartbeatAt: string | null;
-    readonly releasedAt: string | null;
-    readonly outcome: TransparentTerminalLifecycleOutcome | null;
-}
 export interface SupervisorSnapshot {
     readonly revision: number;
+    readonly activeInstances: readonly {
+        readonly id: string;
+        readonly profileId: LaunchProfileId;
+        readonly state: "requested" | "active" | "stopping";
+    }[];
 }
-export type SupervisorCommand = {
-    readonly type: "acquire-foreground-terminal-lease";
-    readonly requestId: RequestId;
-    readonly leaseId: ForegroundTerminalLeaseId;
-    readonly ownerId: string;
-    readonly profile: TransparentTerminalLaunchProfile;
-} | {
-    readonly type: "activate-foreground-terminal-lease";
-    readonly requestId: RequestId;
-    readonly leaseId: ForegroundTerminalLeaseId;
-    readonly generationId: GenerationId;
-    readonly processIdentity: NativeProcessIdentity;
-} | {
-    readonly type: "heartbeat-foreground-terminal-lease";
-    readonly requestId: RequestId;
-    readonly leaseId: ForegroundTerminalLeaseId;
-    readonly processIdentity: NativeProcessIdentity;
-} | {
-    readonly type: "release-foreground-terminal-lease";
-    readonly requestId: RequestId;
-    readonly leaseId: ForegroundTerminalLeaseId;
-    readonly processIdentity: NativeProcessIdentity | null;
-    readonly outcome: TransparentTerminalLifecycleOutcome;
-} | {
-    readonly type: "resynchronize";
-    readonly requestId: RequestId;
-};
 export interface CommandResult {
     readonly requestId: RequestId;
     readonly ok: boolean;
     readonly revision: number;
     readonly error?: {
-        readonly code: "invalid-command" | "not-found" | "stale-generation" | "capability-error" | "driver-error";
+        readonly code: "invalid-command" | "not-found" | "stale-generation" | "capability-error" | "containment-unsupported" | "ownership-error" | "driver-error";
         readonly message: string;
     };
 }

package/dist/src/foundation/owned-ui-settings/declarations.d.ts

@@ -0,0 +1,13 @@
+export declare const OWNED_UI_SETTINGS_VERSION = 1;
+export type OwnedUiSettingValue = string | number | boolean;
+export type OwnedUiSettingApplication = "live" | "restart";
+export interface OwnedUiSettingDeclaration {
+    readonly id: string;
+    readonly description: string;
+    readonly application: OwnedUiSettingApplication;
+    readonly defaultValue: OwnedUiSettingValue;
+    readonly allowedValues: readonly OwnedUiSettingValue[];
+}
+export declare const OWNED_UI_SETTING_DECLARATIONS: readonly OwnedUiSettingDeclaration[];
+export declare function assertOwnedUiSettingDeclarations(declarations: readonly OwnedUiSettingDeclaration[]): void;
+export declare function findOwnedUiSettingDeclaration(declarations: readonly OwnedUiSettingDeclaration[], id: string): OwnedUiSettingDeclaration | null;

package/dist/src/foundation/owned-ui-settings/declarations.js

@@ -0,0 +1,39 @@
+export const OWNED_UI_SETTINGS_VERSION = 1;
+const MAX_ID_LENGTH = 64;
+const ID_PATTERN = /^[a-z][a-z0-9]*(?:[A-Z][a-z0-9]*)*$/;
+export const OWNED_UI_SETTING_DECLARATIONS = Object.freeze([
+    Object.freeze({
+        id: "transcriptDensity",
+        description: "Vertical density of transcript content. Reserved for the custom-viewport milestone; no visible effect yet.",
+        application: "live",
+        defaultValue: "comfortable",
+        allowedValues: Object.freeze(["comfortable", "compact"]),
+    }),
+]);
+export function assertOwnedUiSettingDeclarations(declarations) {
+    const seen = new Set();
+    for (const declaration of declarations) {
+        if (!ID_PATTERN.test(declaration.id) || declaration.id.length > MAX_ID_LENGTH) {
+            throw new Error(`owned UI setting id is not a bounded camelCase identifier: ${declaration.id}`);
+        }
+        if (seen.has(declaration.id))
+            throw new Error(`duplicate owned UI setting id: ${declaration.id}`);
+        seen.add(declaration.id);
+        if (declaration.description.trim().length === 0) {
+            throw new Error(`owned UI setting has no description: ${declaration.id}`);
+        }
+        if (declaration.allowedValues.length === 0) {
+            throw new Error(`owned UI setting declares no allowed values: ${declaration.id}`);
+        }
+        const types = new Set(declaration.allowedValues.map(value => typeof value));
+        if (types.size !== 1) {
+            throw new Error(`owned UI setting mixes allowed value types: ${declaration.id}`);
+        }
+        if (!declaration.allowedValues.includes(declaration.defaultValue)) {
+            throw new Error(`owned UI setting default is not an allowed value: ${declaration.id}`);
+        }
+    }
+}
+export function findOwnedUiSettingDeclaration(declarations, id) {
+    return declarations.find(declaration => declaration.id === id) ?? null;
+}

package/dist/src/foundation/owned-ui-settings/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./declarations.js";
+export * from "./migrations.js";
+export * from "./resolution.js";
+export * from "./sections.js";
+export * from "./session.js";
+export * from "./store.js";

package/dist/src/foundation/owned-ui-settings/index.js

@@ -0,0 +1,6 @@
+export * from "./declarations.js";
+export * from "./migrations.js";
+export * from "./resolution.js";
+export * from "./sections.js";
+export * from "./session.js";
+export * from "./store.js";

package/dist/src/foundation/owned-ui-settings/migrations.d.ts

@@ -0,0 +1,13 @@
+export interface OwnedUiSettingsMigration {
+    /** Version this migration produces. A migration from N-1 declares `to: N`. */
+    readonly to: number;
+    readonly description: string;
+    migrate(values: Readonly<Record<string, unknown>>): Record<string, unknown>;
+}
+/**
+ * Ordered, contiguous migrations ending at OWNED_UI_SETTINGS_VERSION. Version 1
+ * is the first stored shape, so nothing precedes it and the list is empty.
+ */
+export declare const OWNED_UI_SETTINGS_MIGRATIONS: readonly OwnedUiSettingsMigration[];
+export declare function assertOwnedUiSettingsMigrations(migrations: readonly OwnedUiSettingsMigration[], currentVersion?: number): void;
+export declare function migrationsFrom(migrations: readonly OwnedUiSettingsMigration[], storedVersion: number): readonly OwnedUiSettingsMigration[];

package/dist/src/foundation/owned-ui-settings/migrations.js

@@ -0,0 +1,28 @@
+import { OWNED_UI_SETTINGS_VERSION } from "./declarations.js";
+/**
+ * Ordered, contiguous migrations ending at OWNED_UI_SETTINGS_VERSION. Version 1
+ * is the first stored shape, so nothing precedes it and the list is empty.
+ */
+export const OWNED_UI_SETTINGS_MIGRATIONS = Object.freeze([]);
+export function assertOwnedUiSettingsMigrations(migrations, currentVersion = OWNED_UI_SETTINGS_VERSION) {
+    const firstProduced = currentVersion - migrations.length + 1;
+    if (migrations.length > 0 && firstProduced < 2) {
+        throw new Error("owned UI settings migrations cannot produce a version below 2");
+    }
+    migrations.forEach((migration, index) => {
+        const expected = firstProduced + index;
+        if (migration.to !== expected) {
+            throw new Error(`owned UI settings migration ${index} produces version ${migration.to}, expected ${expected}`);
+        }
+        if (migration.description.trim().length === 0) {
+            throw new Error(`owned UI settings migration to version ${migration.to} has no description`);
+        }
+    });
+    const last = migrations.at(-1);
+    if (last && last.to !== currentVersion) {
+        throw new Error(`owned UI settings migrations end at version ${last.to}, expected ${currentVersion}`);
+    }
+}
+export function migrationsFrom(migrations, storedVersion) {
+    return migrations.filter(migration => migration.to > storedVersion);
+}

package/dist/src/foundation/owned-ui-settings/resolution.d.ts

@@ -0,0 +1,45 @@
+import { type OwnedUiSettingDeclaration, type OwnedUiSettingValue } from "./declarations.js";
+import { type OwnedUiSettingsMigration } from "./migrations.js";
+export type OwnedUiSettingSource = "default" | "stored";
+export interface OwnedUiResolvedSetting {
+    readonly declaration: OwnedUiSettingDeclaration;
+    readonly value: OwnedUiSettingValue;
+    readonly source: OwnedUiSettingSource;
+}
+export type OwnedUiSettingsNoticeCode = "document-unreadable" | "version-newer-than-supported" | "migration-unavailable" | "value-rejected";
+export interface OwnedUiSettingsNotice {
+    readonly code: OwnedUiSettingsNoticeCode;
+    /** Setting id for a rejected value; null for document-level notices. */
+    readonly settingId: string | null;
+    readonly detail: string;
+}
+export interface OwnedUiSettingsResolution {
+    readonly version: number;
+    readonly settings: readonly OwnedUiResolvedSetting[];
+    /** Keys that match no declaration, preserved verbatim so a downgrade cannot destroy them. */
+    readonly preserved: Readonly<Record<string, unknown>>;
+    readonly notices: readonly OwnedUiSettingsNotice[];
+    /** True when the resolved form differs from what was stored and should be written on the next change. */
+    readonly migrated: boolean;
+}
+export interface OwnedUiSettingsDocument {
+    readonly version: number;
+    readonly values: Readonly<Record<string, unknown>>;
+}
+export declare function parseOwnedUiSettingsDocument(raw: string): OwnedUiSettingsDocument | null;
+export interface ResolveOwnedUiSettingsInput {
+    readonly declarations: readonly OwnedUiSettingDeclaration[];
+    readonly migrations: readonly OwnedUiSettingsMigration[];
+    /** Parsed document, or null when the file is absent, unreadable, or unparseable. */
+    readonly document: OwnedUiSettingsDocument | null;
+    /** Set when the document existed but could not be read or parsed. */
+    readonly unreadableDetail?: string;
+    readonly currentVersion?: number;
+}
+/**
+ * Pure resolution: declarations plus a parsed document produce a complete value
+ * set, the keys to preserve, and every notice worth reporting. Never throws.
+ */
+export declare function resolveOwnedUiSettings(input: ResolveOwnedUiSettingsInput): OwnedUiSettingsResolution;
+export declare function settingValue(resolution: OwnedUiSettingsResolution, id: string): OwnedUiSettingValue | null;
+export declare function documentFrom(resolution: OwnedUiSettingsResolution): OwnedUiSettingsDocument;