@timurproko/a1 0.1.0 → 0.1.1-dev.10

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

@@ -1,4 +1,4 @@
-export interface AddOnePaths {
+export interface ProductPaths {
     readonly configDir: string;
     readonly dataDir: string;
     readonly runtimeDir: string;
@@ -7,5 +7,4 @@ export interface AddOnePaths {
     readonly endpointMetadataPath: string;
     readonly supervisorLogPath: string;
 }
-export declare function resolveAddOnePaths(environment?: NodeJS.ProcessEnv): AddOnePaths;
-//# sourceMappingURL=paths.d.ts.map
+export declare function resolveProductPaths(environment?: NodeJS.ProcessEnv, hostPlatform?: NodeJS.Platform, fallbackHome?: string): ProductPaths;

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

@@ -1,26 +1,42 @@
 import { createHash } from "node:crypto";
 import { homedir, platform } from "node:os";
-import { join, resolve } from "node:path";
-export function resolveAddOnePaths(environment = process.env) {
-    const windows = platform() === "win32";
-    const home = environment.HOME ?? environment.USERPROFILE ?? homedir();
-    const configDir = resolve(environment.ADDONE_CONFIG_DIR
-        ?? (windows ? join(environment.APPDATA ?? home, "AddOne") : join(environment.XDG_CONFIG_HOME ?? join(home, ".config"), "addone")));
-    const dataDir = resolve(environment.ADDONE_DATA_DIR
-        ?? (windows ? join(environment.LOCALAPPDATA ?? home, "AddOne") : join(environment.XDG_DATA_HOME ?? join(home, ".local", "share"), "addone")));
-    const runtimeDir = resolve(environment.ADDONE_RUNTIME_DIR
-        ?? (windows ? join(dataDir, "runtime") : join(environment.XDG_RUNTIME_DIR ?? dataDir, "addone-runtime")));
+import { posix, win32 } from "node:path";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+export function resolveProductPaths(environment = process.env, hostPlatform = platform(), fallbackHome = homedir()) {
+    const windows = hostPlatform === "win32";
+    const path = windows ? win32 : posix;
+    const home = environment.HOME ?? environment.USERPROFILE ?? fallbackHome;
+    const configOverride = environment[PRODUCT_IDENTITY.environment.configDir];
+    const dataOverride = environment[PRODUCT_IDENTITY.environment.dataDir];
+    const runtimeOverride = environment[PRODUCT_IDENTITY.environment.runtimeDir];
+    const databaseOverride = environment[PRODUCT_IDENTITY.environment.databasePath];
+    const endpointOverride = environment[PRODUCT_IDENTITY.environment.endpoint];
+    const configDir = path.resolve(configOverride
+        ?? (windows
+            ? path.join(environment.APPDATA ?? home, PRODUCT_IDENTITY.state.windowsControlDirectory)
+            : path.join(environment.XDG_CONFIG_HOME ?? path.join(home, ".config"), PRODUCT_IDENTITY.state.unixControlDirectory)));
+    const dataDir = path.resolve(dataOverride
+        ?? (windows
+            ? path.join(environment.LOCALAPPDATA ?? home, PRODUCT_IDENTITY.state.windowsControlDirectory)
+            : path.join(environment.XDG_DATA_HOME ?? path.join(home, ".local", "share"), PRODUCT_IDENTITY.state.unixControlDirectory)));
+    const runtimeDir = path.resolve(runtimeOverride
+        ?? (windows
+            ? path.join(dataDir, "runtime")
+            : environment.XDG_RUNTIME_DIR
+                ? path.join(environment.XDG_RUNTIME_DIR, PRODUCT_IDENTITY.state.unixControlDirectory)
+                : path.join(dataDir, "runtime")));
     const namespace = createHash("sha256").update(runtimeDir.toLowerCase()).digest("hex").slice(0, 20);
-    const endpoint = environment.ADDONE_ENDPOINT
-        ?? (windows ? `\\\\.\\pipe\\addone-${namespace}` : join(runtimeDir, "supervisor.sock"));
+    const endpoint = endpointOverride
+        ?? (windows
+            ? `\\\\.\\pipe\\${PRODUCT_IDENTITY.endpoint.windowsPipeStem}-${namespace}`
+            : path.join(runtimeDir, PRODUCT_IDENTITY.endpoint.unixSocketFilename));
     return {
         configDir,
         dataDir,
         runtimeDir,
-        databasePath: resolve(environment.ADDONE_DATABASE_PATH ?? join(dataDir, "control.sqlite3")),
+        databasePath: path.resolve(databaseOverride ?? path.join(dataDir, PRODUCT_IDENTITY.endpoint.databaseFilename)),
         endpoint,
-        endpointMetadataPath: join(runtimeDir, "supervisor.json"),
-        supervisorLogPath: join(runtimeDir, "supervisor.log"),
+        endpointMetadataPath: path.join(runtimeDir, PRODUCT_IDENTITY.endpoint.metadataFilename),
+        supervisorLogPath: path.join(runtimeDir, PRODUCT_IDENTITY.endpoint.supervisorLogFilename),
     };
 }
-//# sourceMappingURL=paths.js.map

package/dist/src/foundation/native-host-protocol/codec.d.ts

@@ -9,4 +9,3 @@ export declare class NativeHostFrameCodec {
     push(chunk: Buffer | string): NativeHostProofMessage[];
     private decodeLine;
 }
-//# sourceMappingURL=codec.d.ts.map

package/dist/src/foundation/native-host-protocol/codec.js

@@ -54,4 +54,3 @@ function isProofMessage(value) {
         && typeof value.type === "string"
         && ["hello", "hello-result", "command", "command-result", "event", "error"].includes(value.type);
 }
-//# sourceMappingURL=codec.js.map

package/dist/src/foundation/native-host-protocol/evidence.d.ts

@@ -1,4 +1,4 @@
-export declare const NATIVE_SPIKE_EVIDENCE_SCHEMA: "addone-native-host-spike-evidence-v1";
+export declare const NATIVE_SPIKE_EVIDENCE_SCHEMA: string;
 export declare const NATIVE_SPIKE_WORKLOADS: readonly ["four-concurrent-sessions", "input-routing", "unicode-cursor-modes", "alternate-screen", "paste", "mouse", "ime", "live-resize", "dpi", "high-rate-output", "pane-abnormal-exit", "host-cleanup"];
 export type NativeSpikeWorkloadId = typeof NATIVE_SPIKE_WORKLOADS[number];
 export interface NativeSpikeMetricSummary {
@@ -34,7 +34,7 @@ export interface NativeSpikeEvidence {
         readonly sizeBytes: number;
     };
     readonly source: {
-        readonly addoneCommit: string;
+        readonly "a1Commit": string;
         readonly libghosttyVtCommit: string;
         readonly portablePtyVersion: string;
         readonly crosstermVersion: string;
@@ -65,4 +65,3 @@ export interface NativeSpikeEvidence {
     };
 }
 export declare function assertNativeSpikeEvidence(value: NativeSpikeEvidence): void;
-//# sourceMappingURL=evidence.d.ts.map

package/dist/src/foundation/native-host-protocol/evidence.js

@@ -1,4 +1,5 @@
-export const NATIVE_SPIKE_EVIDENCE_SCHEMA = "addone-native-host-spike-evidence-v1";
+import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
+export const NATIVE_SPIKE_EVIDENCE_SCHEMA = PRODUCT_IDENTITY.evidence.nativeSpikeSchema;
 export const NATIVE_SPIKE_WORKLOADS = [
     "four-concurrent-sessions",
     "input-routing",
@@ -34,8 +35,8 @@ export function assertNativeSpikeEvidence(value) {
         throw new TypeError("native spike artifact hash must be SHA-256");
     if (!Number.isSafeInteger(value.artifact.sizeBytes) || value.artifact.sizeBytes <= 0)
         throw new RangeError("native spike artifact size is invalid");
-    if (!/^[a-f0-9]{40}$/.test(value.source.addoneCommit))
-        throw new TypeError("native spike AddOne commit is invalid");
+    if (!/^[a-f0-9]{40}$/.test(value.source["a1Commit"]))
+        throw new TypeError(PRODUCT_TEXT.diagnostic("native spike commit is invalid"));
     if (value.source.libghosttyVtCommit !== EXPECTED_LIBGHOSTTY_VT ||
         value.source.portablePtyVersion !== EXPECTED_PORTABLE_PTY ||
         value.source.crosstermVersion !== EXPECTED_CROSSTERM) {
@@ -138,4 +139,3 @@ function assertJsonObject(value, name) {
     if (!encoded || encoded.length > 64_000)
         throw new RangeError(`${name} exceeds the bounded evidence detail limit`);
 }
-//# sourceMappingURL=evidence.js.map

package/dist/src/foundation/native-host-protocol/index.d.ts

@@ -2,4 +2,3 @@ export * from "./codec.js";
 export * from "./evidence.js";
 export * from "./messages.js";
 export * from "./proof-gate.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/src/foundation/native-host-protocol/index.js

@@ -2,4 +2,3 @@ export * from "./codec.js";
 export * from "./evidence.js";
 export * from "./messages.js";
 export * from "./proof-gate.js";
-//# sourceMappingURL=index.js.map

package/dist/src/foundation/native-host-protocol/messages.d.ts

@@ -1,5 +1,5 @@
 import { type CorrelationId, type NativeHostCommand, type NativeHostEvent, type NativeHostHello, type PaneId, type TerminalSessionLaunch } from "../workspace-contracts/index.js";
-export declare const NATIVE_HOST_PROTOCOL_NAME: "addone-native-host";
+export declare const NATIVE_HOST_PROTOCOL_NAME: string;
 export declare const MAX_NATIVE_HOST_MESSAGE_BYTES: number;
 export type NativeHostProofMessage = {
     readonly type: "hello";
@@ -54,4 +54,3 @@ export declare function nativeHostCommandResult(correlationId: CorrelationId, re
 export declare function nativeHostFailure(code: string, message: string, retryable?: boolean): NativeHostFailure;
 export declare function nativeHostTimedOut(deadlineAt: number, now: number): boolean;
 export declare function assertNativeHostProofMessage(message: NativeHostProofMessage): void;
-//# sourceMappingURL=messages.d.ts.map

package/dist/src/foundation/native-host-protocol/messages.js

@@ -1,5 +1,6 @@
 import { NATIVE_HOST_PROTOCOL_VERSION, assertNativeHostCommand, assertTerminalSessionLaunch, } from "../workspace-contracts/index.js";
-export const NATIVE_HOST_PROTOCOL_NAME = "addone-native-host";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+export const NATIVE_HOST_PROTOCOL_NAME = PRODUCT_IDENTITY.protocol.nativeHostSchema;
 export const MAX_NATIVE_HOST_MESSAGE_BYTES = 1024 * 1024;
 export function negotiateNativeHostHello(value) {
     if (value.protocolVersion !== NATIVE_HOST_PROTOCOL_VERSION) {
@@ -146,4 +147,3 @@ function negotiation(accepted, negotiatedCapabilities, diagnostic) {
 function isText(value, maximum) {
     return typeof value === "string" && value.length > 0 && value.length <= maximum && !value.includes("\0");
 }
-//# sourceMappingURL=messages.js.map

package/dist/src/foundation/native-host-protocol/proof-gate.d.ts

@@ -11,4 +11,3 @@ export interface NativeSpikeGateDecision {
     readonly reasons: readonly string[];
 }
 export declare function evaluateNativeSpikeGate(evidence: NativeSpikeEvidence): NativeSpikeGateDecision;
-//# sourceMappingURL=proof-gate.d.ts.map

package/dist/src/foundation/native-host-protocol/proof-gate.js

@@ -31,4 +31,3 @@ export function evaluateNativeSpikeGate(evidence) {
     }
     return Object.freeze({ decision: "go", integrationAllowed: true, reasons: Object.freeze(["technical and physical proof accepted"]) });
 }
-//# sourceMappingURL=proof-gate.js.map

package/dist/src/foundation/owned-ui-contracts/extension-ui.d.ts

@@ -300,4 +300,3 @@ export interface OwnedUiExtensionRendererPort {
     }, theme: OwnedUiExtensionThemePort, context: OwnedUiExtensionToolRenderContext): OwnedUiExtensionComponent;
 }
 export declare function assertOwnedUiExtensionUiPort(value: unknown): asserts value is OwnedUiExtensionUiPort;
-//# sourceMappingURL=extension-ui.d.ts.map

package/dist/src/foundation/owned-ui-contracts/extension-ui.js

@@ -66,4 +66,3 @@ export function assertOwnedUiExtensionUiPort(value) {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-//# sourceMappingURL=extension-ui.js.map

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

@@ -1,4 +1,3 @@
 export * from "./extension-ui.js";
 export * from "./model.js";
 export * from "./validation.js";
-//# sourceMappingURL=index.d.ts.map

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

@@ -1,4 +1,3 @@
 export * from "./extension-ui.js";
 export * from "./model.js";
 export * from "./validation.js";
-//# sourceMappingURL=index.js.map

package/dist/src/foundation/owned-ui-contracts/model.d.ts

@@ -239,4 +239,3 @@ export interface OwnedUiSnapshot {
     readonly sequence: number;
     readonly view: OwnedUiSessionViewModel;
 }
-//# sourceMappingURL=model.d.ts.map

package/dist/src/foundation/owned-ui-contracts/model.js

@@ -1,2 +1 @@
 export const OWNED_UI_CONTRACT_VERSION = 1;
-//# sourceMappingURL=model.js.map

package/dist/src/foundation/owned-ui-contracts/validation.d.ts

@@ -9,4 +9,3 @@ export declare function assertOwnedUiEditorState(editor: OwnedUiEditorState): vo
 export declare function assertOwnedUiStatusView(status: OwnedUiStatusView): void;
 export declare function assertOwnedUiTerminalSurface(surface: OwnedUiTerminalSurface): void;
 export declare function assertOwnedUiDiagnostics(diagnostic: OwnedUiDiagnostics): void;
-//# sourceMappingURL=validation.d.ts.map

package/dist/src/foundation/owned-ui-contracts/validation.js

@@ -393,4 +393,3 @@ function assertJsonBytes(value, name, maximumBytes) {
 function textBytes(value) {
     return new TextEncoder().encode(value).byteLength;
 }
-//# sourceMappingURL=validation.js.map

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;

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

@@ -0,0 +1,147 @@
+import { OWNED_UI_SETTINGS_VERSION, findOwnedUiSettingDeclaration, } from "./declarations.js";
+import { migrationsFrom } from "./migrations.js";
+export function parseOwnedUiSettingsDocument(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        return null;
+    const candidate = parsed;
+    const version = candidate["version"];
+    if (typeof version !== "number" || !Number.isInteger(version) || version < 1)
+        return null;
+    const values = candidate["values"];
+    if (typeof values !== "object" || values === null || Array.isArray(values))
+        return null;
+    return { version, values: values };
+}
+/**
+ * Pure resolution: declarations plus a parsed document produce a complete value
+ * set, the keys to preserve, and every notice worth reporting. Never throws.
+ */
+export function resolveOwnedUiSettings(input) {
+    const currentVersion = input.currentVersion ?? OWNED_UI_SETTINGS_VERSION;
+    const notices = [];
+    if (input.unreadableDetail !== undefined) {
+        notices.push({ code: "document-unreadable", settingId: null, detail: input.unreadableDetail });
+    }
+    if (input.document === null) {
+        return {
+            version: currentVersion,
+            settings: defaultsFor(input.declarations),
+            preserved: Object.freeze({}),
+            notices: Object.freeze(notices),
+            migrated: false,
+        };
+    }
+    if (input.document.version > currentVersion) {
+        notices.push({
+            code: "version-newer-than-supported",
+            settingId: null,
+            detail: `stored version ${input.document.version} is newer than supported version ${currentVersion}`,
+        });
+        return {
+            version: currentVersion,
+            settings: defaultsFor(input.declarations),
+            preserved: Object.freeze({ ...input.document.values }),
+            notices: Object.freeze(notices),
+            migrated: false,
+        };
+    }
+    const pending = migrationsFrom(input.migrations, input.document.version);
+    const expected = currentVersion - input.document.version;
+    if (pending.length !== expected) {
+        notices.push({
+            code: "migration-unavailable",
+            settingId: null,
+            detail: `no declared migration path from stored version ${input.document.version} to ${currentVersion}`,
+        });
+        return {
+            version: currentVersion,
+            settings: defaultsFor(input.declarations),
+            preserved: Object.freeze({ ...input.document.values }),
+            notices: Object.freeze(notices),
+            migrated: false,
+        };
+    }
+    let values = { ...input.document.values };
+    for (const migration of pending) {
+        try {
+            values = { ...migration.migrate(Object.freeze({ ...values })) };
+        }
+        catch (error) {
+            notices.push({
+                code: "migration-unavailable",
+                settingId: null,
+                detail: `migration to version ${migration.to} failed: ${describe(error)}`,
+            });
+            return {
+                version: currentVersion,
+                settings: defaultsFor(input.declarations),
+                preserved: Object.freeze({ ...input.document.values }),
+                notices: Object.freeze(notices),
+                migrated: false,
+            };
+        }
+    }
+    const settings = [];
+    for (const declaration of input.declarations) {
+        if (!Object.hasOwn(values, declaration.id)) {
+            settings.push({ declaration, value: declaration.defaultValue, source: "default" });
+            continue;
+        }
+        const stored = values[declaration.id];
+        if (isAllowed(declaration, stored)) {
+            settings.push({ declaration, value: stored, source: "stored" });
+            continue;
+        }
+        notices.push({
+            code: "value-rejected",
+            settingId: declaration.id,
+            detail: `stored value ${JSON.stringify(stored) ?? "undefined"} is not an allowed value`,
+        });
+        settings.push({ declaration, value: declaration.defaultValue, source: "default" });
+    }
+    const preserved = {};
+    for (const [key, value] of Object.entries(values)) {
+        if (findOwnedUiSettingDeclaration(input.declarations, key) === null)
+            preserved[key] = value;
+    }
+    return {
+        version: currentVersion,
+        settings: Object.freeze(settings),
+        preserved: Object.freeze(preserved),
+        notices: Object.freeze(notices),
+        migrated: pending.length > 0,
+    };
+}
+export function settingValue(resolution, id) {
+    return resolution.settings.find(setting => setting.declaration.id === id)?.value ?? null;
+}
+export function documentFrom(resolution) {
+    const values = { ...resolution.preserved };
+    for (const setting of resolution.settings) {
+        if (setting.source === "stored")
+            values[setting.declaration.id] = setting.value;
+    }
+    return { version: resolution.version, values };
+}
+function defaultsFor(declarations) {
+    return Object.freeze(declarations.map(declaration => ({
+        declaration,
+        value: declaration.defaultValue,
+        source: "default",
+    })));
+}
+function isAllowed(declaration, value) {
+    if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean")
+        return false;
+    return declaration.allowedValues.includes(value);
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}

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

@@ -0,0 +1,70 @@
+import type { OwnedUiSettingValue } from "./declarations.js";
+import type { OwnedUiSettingsResolution } from "./resolution.js";
+export type OwnedUiSettingsBackend = "a1" | "agent";
+export interface OwnedUiSettingsEntry {
+    readonly id: string;
+    /** Label to show, when its source provides one. Falls back to the id. */
+    readonly label: string | null;
+    readonly backend: OwnedUiSettingsBackend;
+    readonly description: string | null;
+    /** Present when the value is a scalar the surface can offer as a choice. */
+    readonly value: OwnedUiSettingValue | null;
+    /** Raw value as reported by its backend, for entries the surface can only display. */
+    readonly rawValue: unknown;
+    readonly editable: boolean;
+    readonly choices: readonly OwnedUiSettingValue[] | null;
+    /** True when the value is a structured object edited through its own surface. */
+    readonly structured: boolean;
+    /** Limits a numeric setting accepts, when the engine states them. */
+    readonly minimum: number | null;
+    readonly maximum: number | null;
+    /** Flags that surface offers, declared by the source rather than by the value. */
+    readonly flags: readonly {
+        readonly key: string;
+        readonly label: string;
+        readonly description: string;
+        readonly fallback: boolean;
+    }[];
+    readonly origin: "default" | "stored" | "engine";
+    readonly application: "live" | "restart" | "engine";
+}
+export interface OwnedUiSettingsSection {
+    readonly id: string;
+    readonly title: string;
+    readonly entries: readonly OwnedUiSettingsEntry[];
+    /** Set when the section could not be built; entries is then empty. */
+    readonly unavailableReason: string | null;
+    /** Set when the section is present but nothing in it can be changed here. */
+    readonly readOnlyReason: string | null;
+}
+export interface AgentSettingsSnapshot {
+    readonly descriptors: readonly {
+        readonly key: string;
+        readonly valueType: "boolean" | "number" | "string" | "enum" | "json";
+        readonly writable: boolean;
+        readonly choices?: readonly unknown[];
+        readonly label?: string;
+        readonly description?: string;
+        readonly minimum?: number;
+        readonly maximum?: number;
+        readonly flags?: readonly {
+            readonly key: string;
+            readonly label: string;
+            readonly description: string;
+            readonly fallback: boolean;
+        }[];
+    }[];
+    readonly values: Readonly<Record<string, unknown>>;
+    /** Whether the engine advertises settings write capability at all. */
+    readonly writeAdvertised: boolean;
+    /** Set when the engine could not report its settings. */
+    readonly failure: string | null;
+}
+export interface BuildOwnedUiSettingsSectionsInput {
+    readonly resolution: OwnedUiSettingsResolution;
+    /** Null when no engine is attached, which is not a failure. */
+    readonly agent: AgentSettingsSnapshot | null;
+}
+export declare const AGENT_SECTION_ID = "agent";
+export declare function buildOwnedUiSettingsSections(input: BuildOwnedUiSettingsSectionsInput): readonly OwnedUiSettingsSection[];
+export declare function findOwnedUiSettingsEntry(sections: readonly OwnedUiSettingsSection[], id: string, backend: OwnedUiSettingsBackend): OwnedUiSettingsEntry | null;