@astrale-os/kernel-core 1.0.0-beta.3 → 1.0.0-beta.5

package/dist/schema/kernel/syscalls/contracts/execution.d.ts

@@ -1,3 +1,4 @@
+import { type InstallClass, type InstallMode, type ValidationOptions } from './install.js';
 /** Terminal outcome of one durable call; a handler failure is an outcome, not a call error. */
 export declare const executionOutcome: import("zod").ZodUnion<readonly [import("zod").ZodObject<{
     kind: import("zod").ZodLiteral<"completed">;
@@ -13,7 +14,102 @@ export declare const executionOutcome: import("zod").ZodUnion<readonly [import("
 }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
     kind: import("zod").ZodLiteral<"cancelled">;
 }, import("zod/v4/core").$strict>]>;
-export declare const executionStatus: import("zod").ZodObject<{
+/**
+ * The steps a system execution reports as its `phase`: an install classifies, validates and
+ * activates; a repair session drains, awaits a command, attempts and activates; each ends
+ * `completed`, `rejected` or `cancelled`.
+ */
+export declare const SYSTEM_EXECUTION_PHASES: readonly ["classifying", "validating", "activating", "draining", "awaiting", "attempting", "completed", "rejected", "cancelled"];
+/** Continuity interruptions a validation survives before it ends. */
+export declare const MAXIMUM_VALIDATION_INTERRUPTIONS = 3;
+/**
+ * What a system execution shows beside its engine state, as the Runtime writes it and the Client
+ * reads it. `phase` is its own step; every other member is present only where it applies: the
+ * install's class, mode and validation options, the validation progress the store keeps, and for a
+ * repair session the admission it holds the Instance in, the `n` of the `command:<n>` signal it
+ * awaits and, while that wait is bounded, when it expires, the attempt running now, which the
+ * `abort:<number>` signal stops, and the last attempt that ended without activating, with its
+ * report. `uncertified` is the break-glass mark the Instance carries, shown on a live execution
+ * and on the session the mark names.
+ */
+export declare const systemExecutionDetail: import("zod").ZodObject<{
+    phase: import("zod").ZodEnum<{
+        activating: "activating";
+        attempting: "attempting";
+        awaiting: "awaiting";
+        cancelled: "cancelled";
+        classifying: "classifying";
+        completed: "completed";
+        draining: "draining";
+        rejected: "rejected";
+        validating: "validating";
+    }>;
+    class: import("zod").ZodOptional<import("zod").ZodEnum<{
+        immediate: "immediate";
+        noop: "noop";
+        revalidate: "revalidate";
+    }>>;
+    mode: import("zod").ZodOptional<import("zod").ZodEnum<{
+        maintenance: "maintenance";
+        online: "online";
+    }>>;
+    validation: import("zod").ZodOptional<import("zod").ZodObject<{
+        scope: import("zod").ZodEnum<{
+            full: "full";
+            incremental: "incremental";
+        }>;
+        counts: import("zod").ZodEnum<{
+            exact: "exact";
+            sample: "sample";
+        }>;
+    }, import("zod/v4/core").$strict>>;
+    progress: import("zod").ZodOptional<import("zod").ZodObject<{
+        pages: import("zod").ZodNumber;
+        interruptions: import("zod").ZodNumber;
+    }, import("zod/v4/core").$strict>>;
+    instance: import("zod").ZodOptional<import("zod").ZodEnum<{
+        attempt: "attempt";
+        draining: "draining";
+        open: "open";
+        repair: "repair";
+    }>>;
+    command: import("zod").ZodOptional<import("zod").ZodNumber>;
+    expires: import("zod").ZodOptional<import("zod").ZodNumber>;
+    attempt: import("zod").ZodOptional<import("zod").ZodObject<{
+        number: import("zod").ZodNumber;
+        destination: import("zod").ZodEnum<{
+            previous: "previous";
+            target: "target";
+        }>;
+    }, import("zod/v4/core").$strict>>;
+    report: import("zod").ZodOptional<import("zod").ZodObject<{
+        attempt: import("zod").ZodNumber;
+        destination: import("zod").ZodEnum<{
+            previous: "previous";
+            target: "target";
+        }>;
+        result: import("zod").ZodEnum<{
+            aborted: "aborted";
+            interrupted: "interrupted";
+            "migration-required": "migration-required";
+        }>;
+        reason: import("zod").ZodOptional<import("zod").ZodString>;
+        summary: import("zod").ZodOptional<import("zod").ZodUnknown>;
+    }, import("zod/v4/core").$strict>>;
+    uncertified: import("zod").ZodOptional<import("zod").ZodObject<{
+        since: import("zod").ZodNumber;
+        session: import("zod").ZodOptional<import("zod").ZodString>;
+        operator: import("zod").ZodOptional<import("zod").ZodString>;
+        reason: import("zod").ZodOptional<import("zod").ZodString>;
+    }, import("zod/v4/core").$strict>>;
+}, import("zod/v4/core").$strict>;
+/**
+ * The status of one Execution: the engine state of one whose node exists, `detail` present on a
+ * system execution only; or, for Root alone, the state `deleted` of a system execution whose node
+ * was deleted, with the outcome its lifecycle record keeps for ever, so that it is never read as a
+ * live run.
+ */
+export declare const executionStatus: import("zod").ZodUnion<readonly [import("zod").ZodObject<{
     id: import("zod").ZodString;
     function: import("zod").ZodString;
     version: import("zod").ZodString;
@@ -28,6 +124,77 @@ export declare const executionStatus: import("zod").ZodObject<{
         waiting: "waiting";
     }>;
     createdAt: import("zod").ZodString;
+    detail: import("zod").ZodOptional<import("zod").ZodObject<{
+        phase: import("zod").ZodEnum<{
+            activating: "activating";
+            attempting: "attempting";
+            awaiting: "awaiting";
+            cancelled: "cancelled";
+            classifying: "classifying";
+            completed: "completed";
+            draining: "draining";
+            rejected: "rejected";
+            validating: "validating";
+        }>;
+        class: import("zod").ZodOptional<import("zod").ZodEnum<{
+            immediate: "immediate";
+            noop: "noop";
+            revalidate: "revalidate";
+        }>>;
+        mode: import("zod").ZodOptional<import("zod").ZodEnum<{
+            maintenance: "maintenance";
+            online: "online";
+        }>>;
+        validation: import("zod").ZodOptional<import("zod").ZodObject<{
+            scope: import("zod").ZodEnum<{
+                full: "full";
+                incremental: "incremental";
+            }>;
+            counts: import("zod").ZodEnum<{
+                exact: "exact";
+                sample: "sample";
+            }>;
+        }, import("zod/v4/core").$strict>>;
+        progress: import("zod").ZodOptional<import("zod").ZodObject<{
+            pages: import("zod").ZodNumber;
+            interruptions: import("zod").ZodNumber;
+        }, import("zod/v4/core").$strict>>;
+        instance: import("zod").ZodOptional<import("zod").ZodEnum<{
+            attempt: "attempt";
+            draining: "draining";
+            open: "open";
+            repair: "repair";
+        }>>;
+        command: import("zod").ZodOptional<import("zod").ZodNumber>;
+        expires: import("zod").ZodOptional<import("zod").ZodNumber>;
+        attempt: import("zod").ZodOptional<import("zod").ZodObject<{
+            number: import("zod").ZodNumber;
+            destination: import("zod").ZodEnum<{
+                previous: "previous";
+                target: "target";
+            }>;
+        }, import("zod/v4/core").$strict>>;
+        report: import("zod").ZodOptional<import("zod").ZodObject<{
+            attempt: import("zod").ZodNumber;
+            destination: import("zod").ZodEnum<{
+                previous: "previous";
+                target: "target";
+            }>;
+            result: import("zod").ZodEnum<{
+                aborted: "aborted";
+                interrupted: "interrupted";
+                "migration-required": "migration-required";
+            }>;
+            reason: import("zod").ZodOptional<import("zod").ZodString>;
+            summary: import("zod").ZodOptional<import("zod").ZodUnknown>;
+        }, import("zod/v4/core").$strict>>;
+        uncertified: import("zod").ZodOptional<import("zod").ZodObject<{
+            since: import("zod").ZodNumber;
+            session: import("zod").ZodOptional<import("zod").ZodString>;
+            operator: import("zod").ZodOptional<import("zod").ZodString>;
+            reason: import("zod").ZodOptional<import("zod").ZodString>;
+        }, import("zod/v4/core").$strict>>;
+    }, import("zod/v4/core").$strict>>;
     outcome: import("zod").ZodOptional<import("zod").ZodUnion<readonly [import("zod").ZodObject<{
         kind: import("zod").ZodLiteral<"completed">;
         value: import("zod").ZodUnknown;
@@ -42,6 +209,27 @@ export declare const executionStatus: import("zod").ZodObject<{
     }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
         kind: import("zod").ZodLiteral<"cancelled">;
     }, import("zod/v4/core").$strict>]>>;
+}, import("zod/v4/core").$strict>, import("zod").ZodObject<{
+    id: import("zod").ZodString;
+    state: import("zod").ZodLiteral<"deleted">;
+    outcome: import("zod").ZodUnion<readonly [import("zod").ZodObject<{
+        kind: import("zod").ZodLiteral<"completed">;
+        value: import("zod").ZodUnknown;
+    }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
+        kind: import("zod").ZodLiteral<"failed">;
+        error: import("zod").ZodObject<{
+            code: import("zod").ZodString;
+            message: import("zod").ZodString;
+            family: import("zod").ZodOptional<import("zod").ZodString>;
+            details: import("zod").ZodOptional<import("zod").ZodUnknown>;
+        }, import("zod/v4/core").$strict>;
+    }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
+        kind: import("zod").ZodLiteral<"cancelled">;
+    }, import("zod/v4/core").$strict>]>;
+}, import("zod/v4/core").$strict>]>;
+/** What a durable call answers at once: the Execution it created or recovered. */
+export declare const executionRef: import("zod").ZodObject<{
+    id: import("zod").ZodString;
 }, import("zod/v4/core").$strict>;
 export declare const executionStatusInput: import("zod").ZodObject<{}, import("zod/v4/core").$strict>;
 export declare const executionResultInput: import("zod").ZodObject<{
@@ -58,3 +246,55 @@ export declare const executionSignalOutput: import("zod").ZodObject<{}, import("
 export declare const executionResumeInput: import("zod").ZodObject<{}, import("zod/v4/core").$strict>;
 export declare const executionDeleteInput: import("zod").ZodObject<{}, import("zod/v4/core").$strict>;
 export declare const executionDeleteOutput: import("zod").ZodObject<{}, import("zod/v4/core").$strict>;
+export type SystemExecutionPhase = (typeof SYSTEM_EXECUTION_PHASES)[number];
+/** One attempt of a repair session that ended without activating its destination. */
+export interface AttemptReport {
+    readonly attempt: number;
+    /** `target` for an `apply`, `previous` for a cooperative cancel or an idle expiry. */
+    readonly destination: 'target' | 'previous';
+    readonly result: 'migration-required' | 'interrupted' | 'aborted';
+    /** The public failure code that interrupted it. */
+    readonly reason?: string;
+    /** The public migration report of a refuted attempt, versioned by its owner. */
+    readonly summary?: unknown;
+}
+/** The detail of a system execution's status; see `systemExecutionDetail`. */
+export interface SystemExecutionDetail {
+    readonly phase: SystemExecutionPhase;
+    readonly class?: InstallClass;
+    readonly mode?: InstallMode;
+    readonly validation?: ValidationOptions;
+    /** Pages validated so far, and continuity interruptions of at most three. */
+    readonly progress?: {
+        readonly pages: number;
+        readonly interruptions: number;
+    };
+    /** The admission a repair session holds the Instance in. */
+    readonly instance?: 'open' | 'draining' | 'repair' | 'attempt';
+    /** The `n` of the `command:<n>` signal a waiting session awaits. */
+    readonly command?: number;
+    /**
+     * When a waiting session's idle bound passes (epoch milliseconds): without a command by then, it
+     * tries to return to its source. Absent once an idle return was refuted: it then waits for Root.
+     */
+    readonly expires?: number;
+    /** The attempt running now; the `abort:<number>` signal stops it. */
+    readonly attempt?: {
+        readonly number: number;
+        readonly destination: 'target' | 'previous';
+    };
+    /** The last attempt that ended without activating. */
+    readonly report?: AttemptReport;
+    /** The break-glass mark the Instance carries: no certificate covers its stored facts. */
+    readonly uncertified?: UncertifiedMark;
+}
+/**
+ * The mark a break-glass exit leaves on the Instance until a `full` validation commits: when it
+ * was set (epoch milliseconds), the session it closed, and the operator and reason the Host named.
+ */
+export interface UncertifiedMark {
+    readonly since: number;
+    readonly session?: string;
+    readonly operator?: string;
+    readonly reason?: string;
+}

package/dist/schema/kernel/syscalls/contracts/execution.js

@@ -1,5 +1,6 @@
 import { fullMatch } from '@astrale-os/kernel-dsl/v1/value/full-match';
 import { boolean, enum as enumeration, literal, number, strictObject, string, union, unknown as unknownSchema, } from 'zod';
+import { INSTALL_CLASSES, INSTALL_MODES, validationOptions, } from './install.js';
 const nodeId = string().min(1).max(255).check(fullMatch('[A-Za-z0-9._-]+'));
 const empty = strictObject({});
 /** Engine-observed state; never persisted on the Execution. */
@@ -25,14 +26,83 @@ export const executionOutcome = union([
     strictObject({ kind: literal('failed'), error: failure }),
     strictObject({ kind: literal('cancelled') }),
 ]);
-export const executionStatus = strictObject({
-    id: nodeId,
-    function: nodeId,
-    version: string().check(fullMatch('sha256:[0-9a-f]{64}')),
-    state,
-    createdAt: string().min(1),
-    outcome: executionOutcome.optional(),
+/**
+ * The steps a system execution reports as its `phase`: an install classifies, validates and
+ * activates; a repair session drains, awaits a command, attempts and activates; each ends
+ * `completed`, `rejected` or `cancelled`.
+ */
+export const SYSTEM_EXECUTION_PHASES = Object.freeze([
+    'classifying',
+    'validating',
+    'activating',
+    'draining',
+    'awaiting',
+    'attempting',
+    'completed',
+    'rejected',
+    'cancelled',
+]);
+/** Continuity interruptions a validation survives before it ends. */
+export const MAXIMUM_VALIDATION_INTERRUPTIONS = 3;
+const destination = enumeration(['target', 'previous']);
+const ordinal = number().int().min(1);
+/**
+ * What a system execution shows beside its engine state, as the Runtime writes it and the Client
+ * reads it. `phase` is its own step; every other member is present only where it applies: the
+ * install's class, mode and validation options, the validation progress the store keeps, and for a
+ * repair session the admission it holds the Instance in, the `n` of the `command:<n>` signal it
+ * awaits and, while that wait is bounded, when it expires, the attempt running now, which the
+ * `abort:<number>` signal stops, and the last attempt that ended without activating, with its
+ * report. `uncertified` is the break-glass mark the Instance carries, shown on a live execution
+ * and on the session the mark names.
+ */
+export const systemExecutionDetail = strictObject({
+    phase: enumeration(SYSTEM_EXECUTION_PHASES),
+    class: enumeration(INSTALL_CLASSES).optional(),
+    mode: enumeration(INSTALL_MODES).optional(),
+    validation: validationOptions.optional(),
+    progress: strictObject({
+        pages: number().int().min(0),
+        interruptions: number().int().min(0).max(MAXIMUM_VALIDATION_INTERRUPTIONS),
+    }).optional(),
+    instance: enumeration(['open', 'draining', 'repair', 'attempt']).optional(),
+    command: ordinal.optional(),
+    expires: number().int().min(0).optional(),
+    attempt: strictObject({ number: ordinal, destination }).optional(),
+    report: strictObject({
+        attempt: ordinal,
+        destination,
+        result: enumeration(['migration-required', 'interrupted', 'aborted']),
+        reason: string().check(fullMatch('[A-Z][A-Z0-9_]{0,63}')).optional(),
+        summary: unknownSchema().optional(),
+    }).optional(),
+    uncertified: strictObject({
+        since: number().int().min(0),
+        session: nodeId.optional(),
+        operator: string().min(1).max(64).optional(),
+        reason: string().min(1).max(256).optional(),
+    }).optional(),
 });
+/**
+ * The status of one Execution: the engine state of one whose node exists, `detail` present on a
+ * system execution only; or, for Root alone, the state `deleted` of a system execution whose node
+ * was deleted, with the outcome its lifecycle record keeps for ever, so that it is never read as a
+ * live run.
+ */
+export const executionStatus = union([
+    strictObject({
+        id: nodeId,
+        function: nodeId,
+        version: string().check(fullMatch('sha256:[0-9a-f]{64}')),
+        state,
+        createdAt: string().min(1),
+        detail: systemExecutionDetail.optional(),
+        outcome: executionOutcome.optional(),
+    }),
+    strictObject({ id: nodeId, state: literal('deleted'), outcome: executionOutcome }),
+]);
+/** What a durable call answers at once: the Execution it created or recovered. */
+export const executionRef = strictObject({ id: nodeId });
 export const executionStatusInput = empty;
 export const executionResultInput = strictObject({ waitMs: number().int().min(0).optional() });
 export const executionCancelInput = strictObject({ force: boolean().optional() });

package/dist/schema/kernel/syscalls/contracts/index.d.ts

@@ -2,8 +2,8 @@ export { admitInput, admitOutput } from './admit.js';
 export { blobSlot, DOWNLOAD_PARTS_MEDIA_TYPE, downloadInput, MAXIMUM_BLOB_BYTES, MAXIMUM_DOWNLOAD_SLOTS, uploadInput, uploadOutput, } from './blob.js';
 export { MAXIMUM_CHECKS, canInput, canOutput } from './can.js';
 export { delegateInput, delegateOutput } from './delegate.js';
-export { executionCancelInput, executionDeleteInput, executionDeleteOutput, executionOutcome, executionResultInput, executionResumeInput, executionSignalInput, executionSignalOutput, executionStatus, executionStatusInput, } from './execution.js';
-export { installInput, installReceipt, type DomainRequest, type InstallInput, type InstallReceipt, } from './install.js';
+export { executionCancelInput, executionDeleteInput, executionDeleteOutput, executionOutcome, executionRef, executionResultInput, executionResumeInput, executionSignalInput, executionSignalOutput, executionStatus, executionStatusInput, MAXIMUM_VALIDATION_INTERRUPTIONS, SYSTEM_EXECUTION_PHASES, systemExecutionDetail, type AttemptReport, type SystemExecutionDetail, type SystemExecutionPhase, type UncertifiedMark, } from './execution.js';
+export { abortSignal, commandSignal, INSTALL_CLASSES, INSTALL_MODES, installInput, installOutput, installReceipt, installSessionAbort, installSessionCommand, validationOptions, type DomainRequest, type InstallClass, type InstallInput, type InstallMode, type InstallOutput, type InstallReceipt, type InstallSessionAbort, type InstallSessionCommand, type InstallValidation, type ValidationOptions, } from './install.js';
 export { introspectInput } from './introspect.js';
 export { journalInput, journalOutput } from './journal.js';
 export { impersonateInput, impersonateOutput } from './impersonate.js';

package/dist/schema/kernel/syscalls/contracts/index.js

@@ -2,8 +2,8 @@ export { admitInput, admitOutput } from './admit.js';
 export { blobSlot, DOWNLOAD_PARTS_MEDIA_TYPE, downloadInput, MAXIMUM_BLOB_BYTES, MAXIMUM_DOWNLOAD_SLOTS, uploadInput, uploadOutput, } from './blob.js';
 export { MAXIMUM_CHECKS, canInput, canOutput } from './can.js';
 export { delegateInput, delegateOutput } from './delegate.js';
-export { executionCancelInput, executionDeleteInput, executionDeleteOutput, executionOutcome, executionResultInput, executionResumeInput, executionSignalInput, executionSignalOutput, executionStatus, executionStatusInput, } from './execution.js';
-export { installInput, installReceipt, } from './install.js';
+export { executionCancelInput, executionDeleteInput, executionDeleteOutput, executionOutcome, executionRef, executionResultInput, executionResumeInput, executionSignalInput, executionSignalOutput, executionStatus, executionStatusInput, MAXIMUM_VALIDATION_INTERRUPTIONS, SYSTEM_EXECUTION_PHASES, systemExecutionDetail, } from './execution.js';
+export { abortSignal, commandSignal, INSTALL_CLASSES, INSTALL_MODES, installInput, installOutput, installReceipt, installSessionAbort, installSessionCommand, validationOptions, } from './install.js';
 export { introspectInput } from './introspect.js';
 export { journalInput, journalOutput } from './journal.js';
 export { impersonateInput, impersonateOutput } from './impersonate.js';

package/dist/schema/kernel/syscalls/contracts/install.d.ts

@@ -1,4 +1,27 @@
 import type { OperationId } from '../../../installation/operation-id.js';
+/**
+ * What an install does to the stored data: nothing changes (`noop`), it applies at once without
+ * reading the data (`immediate`), or it revalidates the data before it applies (`revalidate`).
+ */
+export declare const INSTALL_CLASSES: readonly ["noop", "immediate", "revalidate"];
+/**
+ * How an install runs. `online` (the default) keeps the Instance open: it validates online and
+ * only its activation briefly pauses writes. `maintenance`, for Root only, opens a maintenance
+ * session: the Instance is closed to every other caller while Root repairs the data in it, then
+ * applies the target.
+ */
+export declare const INSTALL_MODES: readonly ["online", "maintenance"];
+/** The validation options an install runs with, defaults filled in. */
+export declare const validationOptions: import("zod").ZodObject<{
+    scope: import("zod").ZodEnum<{
+        full: "full";
+        incremental: "incremental";
+    }>;
+    counts: import("zod").ZodEnum<{
+        exact: "exact";
+        sample: "sample";
+    }>;
+}, import("zod/v4/core").$strict>;
 export declare const domainRequest: import("zod").ZodUnion<readonly [import("zod").ZodObject<{
     artifact: import("zod").ZodObject<{
         digest: import("zod").ZodString;
@@ -25,6 +48,7 @@ export declare const domainRequest: import("zod").ZodUnion<readonly [import("zod
     revision: import("zod").ZodOptional<import("zod").ZodString>;
     currentRevision: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
 }, import("zod/v4/core").$strict>]>;
+/** One install, all of it its intent: its operation, its Domains, its mode and validation options. */
 export declare const installInput: import("zod").ZodObject<{
     operation: import("zod").ZodString;
     domains: import("zod").ZodArray<import("zod").ZodUnion<readonly [import("zod").ZodObject<{
@@ -53,6 +77,20 @@ export declare const installInput: import("zod").ZodObject<{
         revision: import("zod").ZodOptional<import("zod").ZodString>;
         currentRevision: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
     }, import("zod/v4/core").$strict>]>>;
+    mode: import("zod").ZodOptional<import("zod").ZodEnum<{
+        maintenance: "maintenance";
+        online: "online";
+    }>>;
+    validation: import("zod").ZodOptional<import("zod").ZodObject<{
+        scope: import("zod").ZodOptional<import("zod").ZodEnum<{
+            full: "full";
+            incremental: "incremental";
+        }>>;
+        counts: import("zod").ZodOptional<import("zod").ZodEnum<{
+            exact: "exact";
+            sample: "sample";
+        }>>;
+    }, import("zod/v4/core").$strict>>;
 }, import("zod/v4/core").$strict>;
 export declare const installReceipt: import("zod").ZodObject<{
     operation: import("zod").ZodString;
@@ -99,6 +137,90 @@ export declare const installReceipt: import("zod").ZodObject<{
         }, import("zod/v4/core").$strict>>;
     }, import("zod/v4/core").$strict>>;
 }, import("zod/v4/core").$strict>;
+/**
+ * What a completed install ends with, the value its Execution's `result` yields: the committed
+ * receipt, or the exact generation of each root it proved unchanged.
+ */
+export declare const installOutput: import("zod").ZodUnion<readonly [import("zod").ZodObject<{
+    changed: import("zod").ZodLiteral<true>;
+    receipt: import("zod").ZodObject<{
+        operation: import("zod").ZodString;
+        transitions: import("zod").ZodArray<import("zod").ZodObject<{
+            intent: import("zod").ZodObject<{
+                transition: import("zod").ZodString;
+                operation: import("zod").ZodString;
+                origin: import("zod").ZodString;
+                previous: import("zod").ZodNullable<import("zod").ZodObject<{
+                    origin: import("zod").ZodString;
+                    revision: import("zod").ZodString;
+                    generation: import("zod").ZodString;
+                }, import("zod/v4/core").$strict>>;
+                generation: import("zod").ZodNullable<import("zod").ZodObject<{
+                    origin: import("zod").ZodString;
+                    revision: import("zod").ZodString;
+                    generation: import("zod").ZodString;
+                }, import("zod/v4/core").$strict>>;
+                consent: import("zod").ZodOptional<import("zod").ZodObject<{
+                    issuer: import("zod").ZodObject<{
+                        from: import("zod").ZodString;
+                        to: import("zod").ZodString;
+                    }, import("zod/v4/core").$strict>;
+                    previous: import("zod").ZodEnum<{
+                        drain: "drain";
+                        revoke: "revoke";
+                    }>;
+                }, import("zod/v4/core").$strict>>;
+            }, import("zod/v4/core").$strict>;
+            phase: import("zod").ZodEnum<{
+                converge: "converge";
+                cutover: "cutover";
+            }>;
+            state: import("zod").ZodLiteral<"committed">;
+            readiness: import("zod").ZodOptional<import("zod").ZodObject<{
+                generation: import("zod").ZodString;
+                transition: import("zod").ZodString;
+                dependencies: import("zod").ZodArray<import("zod").ZodObject<{
+                    origin: import("zod").ZodString;
+                    generation: import("zod").ZodString;
+                    readiness: import("zod").ZodString;
+                    meaning: import("zod").ZodString;
+                }, import("zod/v4/core").$strict>>;
+            }, import("zod/v4/core").$strict>>;
+        }, import("zod/v4/core").$strict>>;
+    }, import("zod/v4/core").$strict>;
+}, import("zod/v4/core").$strict>, import("zod").ZodObject<{
+    changed: import("zod").ZodLiteral<false>;
+    domains: import("zod").ZodArray<import("zod").ZodObject<{
+        origin: import("zod").ZodString;
+        revision: import("zod").ZodString;
+        generation: import("zod").ZodString;
+    }, import("zod/v4/core").$strict>>;
+}, import("zod/v4/core").$strict>]>;
+/**
+ * The value of the `command:<n>` signal of a waiting repair session: attempt the target, with
+ * validation options that only widen the default.
+ */
+export declare const installSessionCommand: import("zod").ZodObject<{
+    kind: import("zod").ZodLiteral<"apply">;
+    validation: import("zod").ZodOptional<import("zod").ZodObject<{
+        scope: import("zod").ZodOptional<import("zod").ZodEnum<{
+            full: "full";
+            incremental: "incremental";
+        }>>;
+        counts: import("zod").ZodOptional<import("zod").ZodEnum<{
+            exact: "exact";
+            sample: "sample";
+        }>>;
+    }, import("zod/v4/core").$strict>>;
+}, import("zod/v4/core").$strict>;
+/** The value of the `abort:<n>` signal of a repair session: stop attempt `n`, then wait again. */
+export declare const installSessionAbort: import("zod").ZodObject<{
+    kind: import("zod").ZodLiteral<"abort">;
+}, import("zod/v4/core").$strict>;
+/** The name of the signal that sends the `n`th command to a repair session. */
+export declare function commandSignal(n: number): `command:${number}`;
+/** The name of the signal that aborts attempt `n` of a repair session. */
+export declare function abortSignal(n: number): `abort:${number}`;
 type NonEmpty<Value> = readonly [Value, ...Value[]];
 export type InstallationDigest = `sha256:${string}`;
 export type ReleaseDigest = InstallationDigest;
@@ -179,12 +301,50 @@ export type DomainRequest = {
     readonly artifact: ArtifactRef;
     readonly currentRevision?: string | null;
 } | ReleaseRequest;
+/** `online` (default) never closes the Instance; `maintenance` opens a maintenance session. */
+export type InstallMode = (typeof INSTALL_MODES)[number];
+/** What an install does to the stored data; see `INSTALL_CLASSES`. */
+export type InstallClass = (typeof INSTALL_CLASSES)[number];
+/**
+ * What an install asks its data validation to read beyond the default. `scope: 'full'` trusts
+ * nothing of the stored data and reads every rule of the destination over every retained extent;
+ * `counts: 'exact'` walks every refuted rule to its end, so its count is exact. Each option only
+ * widens the default (`incremental`, `sample`).
+ */
+export interface InstallValidation {
+    readonly scope?: 'incremental' | 'full';
+    readonly counts?: 'sample' | 'exact';
+}
+/** The validation options an install runs with, defaults filled in. */
+export interface ValidationOptions {
+    readonly scope: 'incremental' | 'full';
+    readonly counts: 'sample' | 'exact';
+}
 export interface InstallInput {
     readonly operation: OperationId;
     readonly domains: NonEmpty<DomainRequest>;
+    readonly mode?: InstallMode;
+    readonly validation?: InstallValidation;
 }
 export interface InstallReceipt {
     readonly operation: OperationId;
     readonly transitions: NonEmpty<TransitionReceipt>;
 }
+/** What a completed install ends with; see `installOutput`. */
+export type InstallOutput = {
+    readonly changed: true;
+    readonly receipt: InstallReceipt;
+} | {
+    readonly changed: false;
+    readonly domains: NonEmpty<DomainGeneration>;
+};
+/** The `command:<n>` signal value of a repair session. */
+export interface InstallSessionCommand {
+    readonly kind: 'apply';
+    readonly validation?: InstallValidation;
+}
+/** The `abort:<n>` signal value of a repair session. */
+export interface InstallSessionAbort {
+    readonly kind: 'abort';
+}
 export {};

package/dist/schema/kernel/syscalls/contracts/install.js

@@ -1,5 +1,21 @@
-import { array, strictObject, union } from 'zod';
-import { artifactRef, installationDigest, installationText, issuerConsent, operationIdSchema, transitionReceipt, } from './installation.js';
+import { array, enum as enumeration, literal, strictObject, union } from 'zod';
+import { artifactRef, domainGeneration, installationDigest, installationText, issuerConsent, operationIdSchema, transitionReceipt, } from './installation.js';
+/**
+ * What an install does to the stored data: nothing changes (`noop`), it applies at once without
+ * reading the data (`immediate`), or it revalidates the data before it applies (`revalidate`).
+ */
+export const INSTALL_CLASSES = Object.freeze(['noop', 'immediate', 'revalidate']);
+/**
+ * How an install runs. `online` (the default) keeps the Instance open: it validates online and
+ * only its activation briefly pauses writes. `maintenance`, for Root only, opens a maintenance
+ * session: the Instance is closed to every other caller while Root repairs the data in it, then
+ * applies the target.
+ */
+export const INSTALL_MODES = Object.freeze(['online', 'maintenance']);
+const scope = enumeration(['incremental', 'full']);
+const counts = enumeration(['sample', 'exact']);
+/** The validation options an install runs with, defaults filled in. */
+export const validationOptions = strictObject({ scope, counts });
 export const domainRequest = union([
     strictObject({
         artifact: artifactRef,
@@ -16,11 +32,41 @@ export const domainRequest = union([
         currentRevision: installationText.nullable().optional(),
     }),
 ]);
+const installValidation = strictObject({ scope: scope.optional(), counts: counts.optional() });
+/** One install, all of it its intent: its operation, its Domains, its mode and validation options. */
 export const installInput = strictObject({
     operation: operationIdSchema,
     domains: array(domainRequest).min(1),
+    mode: enumeration(INSTALL_MODES).optional(),
+    validation: installValidation.optional(),
 });
 export const installReceipt = strictObject({
     operation: operationIdSchema,
     transitions: array(transitionReceipt).min(1),
 });
+/**
+ * What a completed install ends with, the value its Execution's `result` yields: the committed
+ * receipt, or the exact generation of each root it proved unchanged.
+ */
+export const installOutput = union([
+    strictObject({ changed: literal(true), receipt: installReceipt }),
+    strictObject({ changed: literal(false), domains: array(domainGeneration).min(1) }),
+]);
+/**
+ * The value of the `command:<n>` signal of a waiting repair session: attempt the target, with
+ * validation options that only widen the default.
+ */
+export const installSessionCommand = strictObject({
+    kind: literal('apply'),
+    validation: installValidation.optional(),
+});
+/** The value of the `abort:<n>` signal of a repair session: stop attempt `n`, then wait again. */
+export const installSessionAbort = strictObject({ kind: literal('abort') });
+/** The name of the signal that sends the `n`th command to a repair session. */
+export function commandSignal(n) {
+    return `command:${n}`;
+}
+/** The name of the signal that aborts attempt `n` of a repair session. */
+export function abortSignal(n) {
+    return `abort:${n}`;
+}