tmux-ide 2.7.0 → 2.9.0-beta.5

package/packages/daemon/dist/lib/app-window-mutation.js

@@ -0,0 +1,139 @@
+import { AppWindowMutationRequestSchemaZ, AppWindowMutationResultSchemaZ, } from "@tmux-ide/contracts";
+import { AppWindowKernelError } from "./app-window-kernel.js";
+import { AppWindowRepositoryError, AppWindowService } from "./app-window-repository.js";
+import { openProjectRuntimeRepository, } from "./project-runtime-repository.js";
+const MAX_OPERATIONS = 256;
+const ERROR_MESSAGES = {
+    daemon_instance_mismatch: "The daemon generation changed before the app window was updated.",
+    workspace_not_found: "The requested workspace is not registered.",
+    workspace_unavailable: "The requested workspace is unavailable for app-window mutation.",
+    revision_conflict: "The app-window document changed before this command was applied.",
+    operation_conflict: "The operation id was already used for a different app-window command.",
+    operation_capacity: "The daemon has reached its bounded app-window operation capacity.",
+    document_unavailable: "The durable app-window document is unavailable.",
+    mutation_failed: "The durable app-window command could not be applied.",
+};
+export class AppWindowMutationError extends Error {
+    code;
+    context;
+    constructor(code, context = {}, cause) {
+        super(ERROR_MESSAGES[code], cause === undefined ? undefined : { cause });
+        this.code = code;
+        this.context = context;
+        this.name = "AppWindowMutationError";
+    }
+}
+function boundedOperationLimit(value) {
+    if (value === undefined)
+        return MAX_OPERATIONS;
+    if (!Number.isInteger(value) || value < 1 || value > MAX_OPERATIONS) {
+        throw new TypeError(`app-window operation limit must be an integer from 1 to ${MAX_OPERATIONS}`);
+    }
+    return value;
+}
+function translateMutationError(error) {
+    if (error instanceof AppWindowMutationError)
+        return error;
+    if (error instanceof AppWindowRepositoryError) {
+        if (error.code === "REVISION_CONFLICT") {
+            return new AppWindowMutationError("revision_conflict", {}, error);
+        }
+        if (error.code === "WRITE_PROTECTED" || error.code === "READ_FAILED") {
+            return new AppWindowMutationError("document_unavailable", {}, error);
+        }
+        return new AppWindowMutationError("mutation_failed", {}, error);
+    }
+    if (error instanceof AppWindowKernelError) {
+        return new AppWindowMutationError("mutation_failed", { path: error.path }, error);
+    }
+    return new AppWindowMutationError("workspace_unavailable", {}, error);
+}
+/** Daemon-generation-owned semantic authority over the persisted AppWindow document. */
+export class AppWindowMutationAuthority {
+    #daemonInstanceId;
+    #registry;
+    #openRuntime;
+    #maxOperations;
+    #operations = new Map();
+    #disposed = false;
+    constructor(options) {
+        this.#daemonInstanceId = options.daemonInstanceId;
+        this.#registry = options.registry;
+        this.#openRuntime = options.openRuntime ?? openProjectRuntimeRepository;
+        this.#maxOperations = boundedOperationLimit(options.maxOperations);
+    }
+    async mutate(rawRequest) {
+        if (this.#disposed)
+            throw new AppWindowMutationError("workspace_unavailable");
+        const request = AppWindowMutationRequestSchemaZ.parse(rawRequest);
+        if (request.expectedDaemonInstanceId !== this.#daemonInstanceId) {
+            throw new AppWindowMutationError("daemon_instance_mismatch");
+        }
+        const fingerprint = JSON.stringify(request);
+        const existing = this.#operations.get(request.operationId);
+        if (existing) {
+            if (existing.fingerprint !== fingerprint) {
+                throw new AppWindowMutationError("operation_conflict");
+            }
+            const result = await existing.result;
+            return AppWindowMutationResultSchemaZ.parse({ ...result, outcome: "replayed" });
+        }
+        if (this.#operations.size >= this.#maxOperations) {
+            const settled = [...this.#operations].find(([, record]) => record.settled);
+            if (!settled)
+                throw new AppWindowMutationError("operation_capacity");
+            this.#operations.delete(settled[0]);
+        }
+        const result = this.#execute(request);
+        const record = { fingerprint, result, settled: false };
+        this.#operations.set(request.operationId, record);
+        try {
+            return await result;
+        }
+        catch (error) {
+            this.#operations.delete(request.operationId);
+            throw error;
+        }
+        finally {
+            record.settled = true;
+        }
+    }
+    dispose() {
+        this.#disposed = true;
+        this.#operations.clear();
+    }
+    async #execute(request) {
+        try {
+            const workspace = this.#registry.get(request.intent.workspaceName);
+            if (!workspace)
+                throw new AppWindowMutationError("workspace_not_found");
+            const runtime = await this.#openRuntime(workspace.projectDir);
+            if (this.#disposed)
+                throw new AppWindowMutationError("workspace_unavailable");
+            const service = new AppWindowService(runtime);
+            const loaded = service.load();
+            if (loaded.writeProtected)
+                throw new AppWindowMutationError("document_unavailable");
+            if (loaded.document.revision !== request.intent.expectedDocumentRevision) {
+                throw new AppWindowMutationError("revision_conflict", {
+                    expectedRevision: String(request.intent.expectedDocumentRevision),
+                    actualRevision: String(loaded.document.revision),
+                });
+            }
+            // execute performs its satisfied check while holding the repository's
+            // writer lock and pins the storage revision, so unchanged is linearizable.
+            const next = service.execute(request.intent.command, { expectedRevision: loaded.revision });
+            const unchanged = next.document.revision === loaded.document.revision;
+            return AppWindowMutationResultSchemaZ.parse({
+                operationId: request.operationId,
+                daemonInstanceId: this.#daemonInstanceId,
+                outcome: unchanged ? "unchanged" : "applied",
+                workspaceName: request.intent.workspaceName,
+                documentRevision: next.document.revision,
+            });
+        }
+        catch (error) {
+            throw translateMutationError(error);
+        }
+    }
+}

package/packages/daemon/dist/lib/app-window-repository.d.ts

@@ -0,0 +1,81 @@
+import { type AppWindowDocumentV1 } from "@tmux-ide/contracts";
+import { type ProjectRuntimeRepository } from "./project-runtime-repository.ts";
+import { type AppWindowCommand } from "./app-window-kernel.ts";
+import { type AppWindowStateDiagnostic } from "./app-window-state.ts";
+export declare const APP_WINDOW_DOCUMENT_PATH = "ui/app-windows.json";
+export type AppWindowRepositoryDiagnosticCode = AppWindowStateDiagnostic["code"] | "MISSING" | "READ_FAILED" | "WRITE_FAILED" | "WRITE_PROTECTED" | "MIGRATION_FAILED" | "REVISION_CONFLICT" | "RECOVERED";
+export interface AppWindowRepositoryDiagnostic {
+    code: AppWindowRepositoryDiagnosticCode;
+    path: string;
+    message: string;
+}
+export interface LoadedAppWindowDocument {
+    document: AppWindowDocumentV1;
+    revision: number | null;
+    writeProtected: boolean;
+    diagnostics: AppWindowRepositoryDiagnostic[];
+    /** Exact parsed payload retained for inspection; never used as a write source. */
+    preservedPayload?: unknown;
+    /** Token required by explicit recovery. It identifies the exact on-disk bytes. */
+    recoveryToken: string | null;
+}
+export interface LoadAppWindowDocumentOptions {
+    loadedAt: string;
+    migrateLegacy?: boolean;
+    migratedAt?: string;
+    terminalSourceIds?: readonly string[];
+    focusedTerminalSourceId?: string | null;
+    /** Explicitly permits a fresh document after a failed legacy migration. */
+    migrationFailureOptOut?: {
+        reason: string;
+    };
+}
+export type AppWindowRepositoryErrorCode = "READ_FAILED" | "WRITE_FAILED" | "WRITE_PROTECTED" | "REVISION_CONFLICT" | "INVALID_DOCUMENT" | "RECOVERY_NOT_REQUIRED" | "RECOVERY_CONFLICT";
+export declare class AppWindowRepositoryError extends Error {
+    readonly code: AppWindowRepositoryErrorCode;
+    readonly diagnostics: AppWindowRepositoryDiagnostic[];
+    readonly cause: unknown;
+    constructor(code: AppWindowRepositoryErrorCode, message: string, diagnostics?: AppWindowRepositoryDiagnostic[], cause?: unknown);
+}
+export interface ResetAppWindowDocumentRequest {
+    expectedRecoveryToken: string;
+    reason: string;
+    resetAt: string;
+    document?: AppWindowDocumentV1;
+}
+export interface ResetAppWindowDocumentResult extends LoadedAppWindowDocument {
+    backupPath: string;
+    metadataPath: string;
+    reason: string;
+}
+export interface AppWindowServiceOptions {
+    now?: () => string;
+    migration?: AppWindowServiceMigrationOptions;
+    writerLock?: AppWindowWriterLockOptions;
+}
+export interface AppWindowServiceMigrationOptions {
+    terminalSourceIds?: readonly string[];
+    focusedTerminalSourceId?: string | null;
+    migrationFailureOptOut?: {
+        reason: string;
+    };
+}
+export interface AppWindowWriterLockOptions {
+    timeoutMs?: number;
+    pollMs?: number;
+}
+export interface ExecuteAppWindowCommandOptions {
+    /** When supplied, stale callers fail rather than rebasing the command. */
+    expectedRevision?: number | null;
+    maxRetries?: number;
+}
+export declare class AppWindowService {
+    #private;
+    constructor(runtime: ProjectRuntimeRepository, options?: AppWindowServiceOptions);
+    load(): LoadedAppWindowDocument;
+    execute(command: AppWindowCommand, options?: ExecuteAppWindowCommandOptions): LoadedAppWindowDocument;
+    reset(request: ResetAppWindowDocumentRequest): ResetAppWindowDocumentResult;
+}
+export declare function loadAppWindowDocument(repository: ProjectRuntimeRepository, options: LoadAppWindowDocumentOptions): LoadedAppWindowDocument;
+export declare function writeAppWindowDocument(repository: ProjectRuntimeRepository, expectedRevision: number | null, document: AppWindowDocumentV1): LoadedAppWindowDocument;
+export declare function resetAppWindowDocument(repository: ProjectRuntimeRepository, request: ResetAppWindowDocumentRequest): ResetAppWindowDocumentResult;

package/packages/daemon/dist/lib/app-window-repository.js

@@ -0,0 +1,368 @@
+import { AppWindowDocumentV1SchemaZ } from "@tmux-ide/contracts";
+import { RevisionConflictError, } from "./project-runtime-repository.js";
+import { AppWindowKernelError, applyAppWindowCommand, isAppWindowCommandSatisfied, } from "./app-window-kernel.js";
+import { emptyAppWindowDocument, migrateWorkspaceUiStateV2ToAppWindowDocument, parseAppWindowDocument, serializeAppWindowDocument, } from "./app-window-state.js";
+export const APP_WINDOW_DOCUMENT_PATH = "ui/app-windows.json";
+const LEGACY_WORKSPACE_UI_PATH = "ui/workspace.json";
+export class AppWindowRepositoryError extends Error {
+    code;
+    diagnostics;
+    cause;
+    constructor(code, message, diagnostics = [], cause) {
+        super(message);
+        this.name = "AppWindowRepositoryError";
+        this.code = code;
+        this.diagnostics = diagnostics;
+        this.cause = cause;
+    }
+}
+export class AppWindowService {
+    #runtime;
+    #now;
+    #migration;
+    #writerLock;
+    constructor(runtime, options = {}) {
+        this.#runtime = runtime;
+        this.#now = options.now ?? (() => new Date().toISOString());
+        this.#migration = options.migration
+            ? {
+                terminalSourceIds: options.migration.terminalSourceIds,
+                focusedTerminalSourceId: options.migration.focusedTerminalSourceId,
+                migrationFailureOptOut: options.migration.migrationFailureOptOut,
+            }
+            : undefined;
+        this.#writerLock = options.writerLock;
+    }
+    load() {
+        const timestamp = this.#now();
+        return loadAppWindowDocument(this.#runtime, {
+            loadedAt: timestamp,
+            migratedAt: timestamp,
+            ...this.#migration,
+        });
+    }
+    execute(command, options = {}) {
+        const expectedRevision = validateExpectedRevision(options.expectedRevision);
+        return withAppWindowWriterLock(this.#runtime, this.#writerLock, (writer) => {
+            const retries = boundedRetries(options.maxRetries);
+            for (let attempt = 0; attempt <= retries; attempt += 1) {
+                const timestamp = this.#now();
+                const loaded = loadAppWindowDocumentInternal(this.#runtime, {
+                    loadedAt: timestamp,
+                    migratedAt: timestamp,
+                    ...this.#migration,
+                }, writer);
+                assertWritable(loaded);
+                if (expectedRevision !== undefined && expectedRevision !== loaded.revision) {
+                    throw revisionError(expectedRevision, loaded.revision);
+                }
+                if (isAppWindowCommandSatisfied(loaded.document, command))
+                    return loaded;
+                const clock = this.#now();
+                const commandTimestamp = Date.parse(clock) < Date.parse(loaded.document.updatedAt)
+                    ? loaded.document.updatedAt
+                    : clock;
+                const next = applyAppWindowCommand(loaded.document, command, commandTimestamp);
+                try {
+                    return writeAppWindowDocumentLocked(this.#runtime, writer, loaded.revision, next);
+                }
+                catch (error) {
+                    if (error instanceof AppWindowRepositoryError &&
+                        error.code === "REVISION_CONFLICT" &&
+                        expectedRevision === undefined &&
+                        attempt < retries) {
+                        continue;
+                    }
+                    throw error;
+                }
+            }
+            throw new Error("unreachable app-window retry exhaustion");
+        });
+    }
+    reset(request) {
+        return withAppWindowWriterLock(this.#runtime, this.#writerLock, (writer) => resetAppWindowDocumentLocked(this.#runtime, writer, request));
+    }
+}
+export function loadAppWindowDocument(repository, options) {
+    return loadAppWindowDocumentInternal(repository, options);
+}
+function loadAppWindowDocumentInternal(repository, options, writer) {
+    let runtimeDocument;
+    try {
+        runtimeDocument = repository.readDocument(APP_WINDOW_DOCUMENT_PATH);
+    }
+    catch (error) {
+        return protectedReadFailure(repository, options.loadedAt, error);
+    }
+    if (!runtimeDocument.found) {
+        if (options.migrateLegacy !== false) {
+            const migration = writer
+                ? attemptFirstMigrationLocked(repository, writer, options)
+                : attemptFirstMigration(repository, options);
+            if (migration)
+                return migration;
+        }
+        return {
+            document: emptyAppWindowDocument(options.loadedAt),
+            revision: null,
+            writeProtected: false,
+            diagnostics: [diagnostic("MISSING", APP_WINDOW_DOCUMENT_PATH, "app window state is absent")],
+            recoveryToken: null,
+        };
+    }
+    const parsed = parseAppWindowDocument(runtimeDocument.payload, options.loadedAt);
+    const diagnostics = parsed.diagnostics.map((entry) => ({ ...entry }));
+    const writeProtected = parsed.writeProtected || diagnostics.length > 0;
+    return {
+        document: parsed.document,
+        revision: runtimeDocument.revision,
+        writeProtected,
+        diagnostics,
+        ...(writeProtected ? { preservedPayload: structuredClone(runtimeDocument.payload) } : {}),
+        recoveryToken: safeRecoveryToken(repository),
+    };
+}
+export function writeAppWindowDocument(repository, expectedRevision, document) {
+    return withAppWindowWriterLock(repository, undefined, (writer) => writeAppWindowDocumentLocked(repository, writer, expectedRevision, document));
+}
+function writeAppWindowDocumentLocked(repository, writer, expectedRevision, document) {
+    const validation = AppWindowDocumentV1SchemaZ.safeParse(document);
+    if (!validation.success) {
+        throw new AppWindowRepositoryError("INVALID_DOCUMENT", validation.error.issues.map((issue) => issue.message).join("; "));
+    }
+    const loaded = loadAppWindowDocument(repository, {
+        loadedAt: validation.data.updatedAt,
+        migrateLegacy: false,
+    });
+    assertWritable(loaded);
+    if (loaded.revision !== expectedRevision)
+        throw revisionError(expectedRevision, loaded.revision);
+    assertNextDocumentRevision(loaded, validation.data);
+    try {
+        const payload = JSON.parse(serializeAppWindowDocument(validation.data));
+        const written = writer.writeDocument(APP_WINDOW_DOCUMENT_PATH, payload, {
+            expectedRevision,
+        });
+        return {
+            document: validation.data,
+            revision: written.revision,
+            writeProtected: false,
+            diagnostics: [],
+            recoveryToken: safeRecoveryToken(repository),
+        };
+    }
+    catch (error) {
+        if (error instanceof RevisionConflictError) {
+            throw revisionError(error.expectedRevision, error.actualRevision, error);
+        }
+        throw new AppWindowRepositoryError("WRITE_FAILED", `app window state could not be written: ${error.message}`, [diagnostic("WRITE_FAILED", APP_WINDOW_DOCUMENT_PATH, error.message)], error);
+    }
+}
+export function resetAppWindowDocument(repository, request) {
+    return withAppWindowWriterLock(repository, undefined, (writer) => resetAppWindowDocumentLocked(repository, writer, request));
+}
+function resetAppWindowDocumentLocked(repository, writer, request) {
+    const loaded = loadAppWindowDocument(repository, {
+        loadedAt: request.resetAt,
+        migrateLegacy: false,
+    });
+    if (!loaded.writeProtected) {
+        throw new AppWindowRepositoryError("RECOVERY_NOT_REQUIRED", "app window state is valid; normal revision CAS must be used");
+    }
+    if (!loaded.recoveryToken || loaded.recoveryToken !== request.expectedRecoveryToken) {
+        throw new AppWindowRepositoryError("RECOVERY_CONFLICT", "app window recovery token no longer matches the preserved document");
+    }
+    let resetDocument = request.document;
+    if (resetDocument === undefined) {
+        try {
+            resetDocument = emptyAppWindowDocument(request.resetAt);
+        }
+        catch (error) {
+            throw new AppWindowRepositoryError("INVALID_DOCUMENT", `resetAt must be a valid app window timestamp: ${error.message}`, [], error);
+        }
+    }
+    const validation = AppWindowDocumentV1SchemaZ.safeParse(resetDocument);
+    if (!validation.success) {
+        throw new AppWindowRepositoryError("INVALID_DOCUMENT", validation.error.issues.map((issue) => issue.message).join("; "));
+    }
+    const document = validation.data;
+    try {
+        const payload = JSON.parse(serializeAppWindowDocument(document));
+        const recovered = writer.recoverDocument(APP_WINDOW_DOCUMENT_PATH, payload, {
+            expectedRawSha256: request.expectedRecoveryToken,
+            reason: request.reason,
+            details: {
+                diagnostics: loaded.diagnostics.map((entry) => ({ ...entry })),
+            },
+        });
+        return {
+            document,
+            revision: recovered.revision,
+            writeProtected: false,
+            diagnostics: [
+                diagnostic("RECOVERED", APP_WINDOW_DOCUMENT_PATH, `app window state was explicitly reset; prior bytes preserved at ${recovered.backupPath}`),
+            ],
+            recoveryToken: safeRecoveryToken(repository),
+            backupPath: recovered.backupPath,
+            metadataPath: recovered.metadataPath,
+            reason: recovered.reason,
+        };
+    }
+    catch (error) {
+        if (error instanceof RevisionConflictError) {
+            throw new AppWindowRepositoryError("RECOVERY_CONFLICT", "app window document changed before explicit recovery", [], error);
+        }
+        throw new AppWindowRepositoryError("WRITE_FAILED", `app window recovery failed: ${error.message}`, [], error);
+    }
+}
+function assertNextDocumentRevision(loaded, next) {
+    if (loaded.revision === null) {
+        if (next.revision === 0 || next.revision === 1)
+            return;
+        throw new AppWindowRepositoryError("INVALID_DOCUMENT", "a new app window document must start at domain revision 0 or 1");
+    }
+    if (next.revision !== loaded.document.revision + 1) {
+        throw new AppWindowRepositoryError("INVALID_DOCUMENT", `app window domain revision must advance exactly once from ${loaded.document.revision}`);
+    }
+    if (Date.parse(next.updatedAt) < Date.parse(loaded.document.updatedAt)) {
+        throw new AppWindowRepositoryError("INVALID_DOCUMENT", "app window updatedAt must not move backwards");
+    }
+}
+function withAppWindowWriterLock(repository, options, action) {
+    try {
+        return repository.withWriterLock(options, action);
+    }
+    catch (error) {
+        if (error instanceof AppWindowRepositoryError || error instanceof AppWindowKernelError) {
+            throw error;
+        }
+        throw new AppWindowRepositoryError("WRITE_FAILED", `app window writer lock failed: ${error.message}`, [diagnostic("WRITE_FAILED", APP_WINDOW_DOCUMENT_PATH, error.message)], error);
+    }
+}
+function attemptFirstMigration(repository, options) {
+    try {
+        return withAppWindowWriterLock(repository, undefined, (writer) => attemptFirstMigrationLocked(repository, writer, options));
+    }
+    catch (error) {
+        return migrationFailure(repository, options, error, "legacy migration lock could not be acquired");
+    }
+}
+function attemptFirstMigrationLocked(repository, writer, options) {
+    let current;
+    try {
+        current = repository.readDocument(APP_WINDOW_DOCUMENT_PATH);
+    }
+    catch (error) {
+        return protectedReadFailure(repository, options.loadedAt, error);
+    }
+    if (current.found) {
+        return loadAppWindowDocumentInternal(repository, { ...options, migrateLegacy: false }, writer);
+    }
+    let legacy;
+    try {
+        legacy = repository.readDocument(LEGACY_WORKSPACE_UI_PATH);
+    }
+    catch (error) {
+        return migrationFailure(repository, options, error, "legacy workspace UI state could not be read");
+    }
+    if (!legacy.found)
+        return null;
+    try {
+        const migrated = migrateWorkspaceUiStateV2ToAppWindowDocument(legacy.payload, {
+            migratedAt: options.migratedAt ?? options.loadedAt,
+            terminalSourceIds: options.terminalSourceIds,
+            focusedTerminalSourceId: options.focusedTerminalSourceId,
+        });
+        const payload = JSON.parse(serializeAppWindowDocument(migrated.document));
+        const written = writer.writeDocument(APP_WINDOW_DOCUMENT_PATH, payload, {
+            expectedRevision: null,
+        });
+        return {
+            document: migrated.document,
+            revision: written.revision,
+            writeProtected: false,
+            diagnostics: migrated.diagnostics,
+            recoveryToken: safeRecoveryToken(repository),
+        };
+    }
+    catch (error) {
+        if (error instanceof RevisionConflictError) {
+            return loadAppWindowDocumentInternal(repository, { ...options, migrateLegacy: false }, writer);
+        }
+        return migrationFailure(repository, options, error, "legacy workspace UI state was not migrated");
+    }
+}
+function migrationFailure(repository, options, error, context) {
+    const optOut = validateMigrationFailureOptOut(options.migrationFailureOptOut);
+    const suffix = optOut
+        ? `; explicit migration opt-out accepted: ${optOut}`
+        : "; writes remain protected until an explicit migration opt-out reason is supplied";
+    return {
+        document: emptyAppWindowDocument(options.loadedAt),
+        revision: null,
+        writeProtected: optOut === null,
+        diagnostics: [
+            diagnostic("MIGRATION_FAILED", LEGACY_WORKSPACE_UI_PATH, `${context}: ${error.message}${suffix}`),
+        ],
+        recoveryToken: safeRecoveryToken(repository),
+    };
+}
+function validateMigrationFailureOptOut(value) {
+    if (value === undefined)
+        return null;
+    const reason = value.reason.trim();
+    if (reason.length === 0 || reason.length > 512 || reason.includes("\0"))
+        return null;
+    return reason;
+}
+function protectedReadFailure(repository, loadedAt, error) {
+    return {
+        document: emptyAppWindowDocument(loadedAt),
+        revision: null,
+        writeProtected: true,
+        diagnostics: [
+            diagnostic("READ_FAILED", APP_WINDOW_DOCUMENT_PATH, `app window state could not be read safely: ${error.message}`),
+        ],
+        recoveryToken: safeRecoveryToken(repository),
+    };
+}
+function assertWritable(loaded) {
+    if (!loaded.writeProtected)
+        return;
+    throw new AppWindowRepositoryError("WRITE_PROTECTED", "app window state is not safe to overwrite without explicit recovery", [
+        ...loaded.diagnostics,
+        diagnostic("WRITE_PROTECTED", APP_WINDOW_DOCUMENT_PATH, "preserved current app window bytes without writing"),
+    ]);
+}
+function safeRecoveryToken(repository) {
+    try {
+        return repository.documentRecoveryToken(APP_WINDOW_DOCUMENT_PATH);
+    }
+    catch {
+        return null;
+    }
+}
+function revisionError(expected, actual, cause) {
+    return new AppWindowRepositoryError("REVISION_CONFLICT", `app window revision conflict: expected ${String(expected)}, actual ${String(actual)}`, [
+        diagnostic("REVISION_CONFLICT", APP_WINDOW_DOCUMENT_PATH, `expected ${String(expected)}, actual ${String(actual)}`),
+    ], cause);
+}
+function boundedRetries(value) {
+    if (value === undefined)
+        return 2;
+    if (!Number.isInteger(value) || value < 0 || value > 8) {
+        throw new AppWindowRepositoryError("INVALID_DOCUMENT", "maxRetries must be an integer between 0 and 8");
+    }
+    return value;
+}
+function validateExpectedRevision(value) {
+    if (value === undefined || value === null)
+        return value;
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new AppWindowRepositoryError("INVALID_DOCUMENT", "expectedRevision must be null or a nonnegative safe integer");
+    }
+    return value;
+}
+function diagnostic(code, path, message) {
+    return { code, path, message };
+}

package/packages/daemon/dist/lib/app-window-state.d.ts

@@ -0,0 +1,57 @@
+import { type AppWindowDocumentV1 } from "@tmux-ide/contracts";
+export { stableAppWindowInstanceId } from "@tmux-ide/core";
+/**
+ * Standalone durable kernel seam; it intentionally does not replace the
+ * current WorkspaceUiStateV2 controller in this slice.
+ *
+ * Integration follow-ups:
+ * - give this document its own project-runtime repository path and revision CAS;
+ * - project root-owned window actions into this kernel before renderer updates;
+ * - correlate terminalSourceId -> live `%pane_id` in an in-memory adapter only;
+ * - retire view/dock layout fields from WorkspaceUiStateV2 after one-way migration.
+ */
+export type AppWindowStateDiagnosticCode = "MALFORMED" | "UNSUPPORTED_VERSION" | "INVALID_FIELD" | "MIGRATED" | "TERMINAL_SOURCE_REQUIRED" | "COMPOSITE_LAYOUT_DEFERRED" | "FIELD_DEFAULTED";
+export interface AppWindowStateDiagnostic {
+    code: AppWindowStateDiagnosticCode;
+    path: string;
+    message: string;
+}
+export interface ParsedAppWindowDocument {
+    document: AppWindowDocumentV1;
+    diagnostics: AppWindowStateDiagnostic[];
+    writeProtected: boolean;
+}
+export interface MigratedAppWindowDocument {
+    document: AppWindowDocumentV1;
+    diagnostics: AppWindowStateDiagnostic[];
+}
+export interface MigrateWorkspaceUiStateOptions {
+    migratedAt: string;
+    /** Durable semantic terminal ids, never live tmux `%pane_id` values. */
+    terminalSourceIds?: readonly string[];
+    /** Stable focus input used to select one terminal when several are present. */
+    focusedTerminalSourceId?: string | null;
+}
+export declare function emptyAppWindowDocument(updatedAt: string): AppWindowDocumentV1;
+/**
+ * Strictly validates durable state. Invalid current-version documents expose
+ * an empty recovery projection under write protection; newer versions are
+ * likewise protected so an older binary cannot overwrite unknown data.
+ */
+export declare function parseAppWindowDocument(value: unknown, fallbackTimestamp: string): ParsedAppWindowDocument;
+/**
+ * One-way seam from the current WorkspaceUiStateV2 projection. Native dock
+ * surfaces receive stable app-window instances. Terminals are migrated only
+ * when their semantic source ids are supplied separately; live `%pane_id`
+ * correlation is deliberately neither accepted nor persisted.
+ */
+export declare function migrateWorkspaceUiStateV2ToAppWindowDocument(value: unknown, options: MigrateWorkspaceUiStateOptions): MigratedAppWindowDocument;
+export declare function saveAppWindowNamedLayout(document: AppWindowDocumentV1, input: {
+    id: string;
+    name: string;
+    description?: string | null;
+    updatedAt: string;
+}): AppWindowDocumentV1;
+export declare function restoreAppWindowNamedLayout(document: AppWindowDocumentV1, layoutId: string, updatedAt: string): AppWindowDocumentV1;
+export declare function focusAppWindow(document: AppWindowDocumentV1, windowId: string | null, updatedAt: string): AppWindowDocumentV1;
+export declare function serializeAppWindowDocument(document: AppWindowDocumentV1): string;