@astrale-os/kernel-core 0.9.0-beta.9 → 0.9.0

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

@@ -1,229 +1,279 @@
-import type { ClassRef, Key } from '@astrale-os/kernel-dsl/v1';
-import { z } from 'zod';
-import type { AuthorityOperation } from '../../../authority/operation.js';
 import type { OperationId } from '../../../installation/operation-id.js';
-export declare const installInput: z.ZodObject<{
-    operation: z.ZodString;
-    domains: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
-        source: z.ZodObject<{
-            kind: z.ZodLiteral<"local">;
-            artifact: z.ZodObject<{
-                digest: z.ZodString;
-                mediaType: z.ZodString;
-                size: z.ZodNumber;
-            }, z.core.$strict>;
-        }, z.core.$strict>;
-        currentRevision: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    }, z.core.$strict>, z.ZodObject<{
-        source: z.ZodObject<{
-            kind: z.ZodLiteral<"remote">;
-            url: z.ZodString;
-            token: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>;
-        targetRevision: z.ZodOptional<z.ZodString>;
-        targetEtag: z.ZodOptional<z.ZodString>;
-        currentRevision: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    }, z.core.$strict>]>>;
-}, z.core.$strict>;
-export declare const installOutput: z.ZodObject<{
-    operation: z.ZodString;
-    transitions: z.ZodArray<z.ZodObject<{
-        intent: z.ZodObject<{
-            transition: z.ZodString;
-            operation: z.ZodString;
-            installation: z.ZodString;
-            origin: z.ZodString;
-            source: z.ZodNullable<z.ZodObject<{
-                origin: z.ZodString;
-                schemaRevision: z.ZodString;
-                schemaBundle: z.ZodString;
-                service: z.ZodDiscriminatedUnion<[z.ZodObject<{
-                    kind: z.ZodLiteral<"local">;
-                    artifact: z.ZodString;
-                }, z.core.$strict>, z.ZodObject<{
-                    kind: z.ZodLiteral<"remote">;
-                    etag: z.ZodString;
-                }, z.core.$strict>], "kind">;
-                capabilities: z.ZodObject<{
-                    functions: z.ZodOptional<z.ZodArray<z.ZodString>>;
-                    classes: z.ZodOptional<z.ZodArray<z.ZodObject<{
-                        class: z.ZodObject<{
-                            origin: z.ZodString;
-                            kind: z.ZodLiteral<"class">;
-                            name: z.ZodString;
-                        }, z.core.$strict>;
-                        operations: z.ZodArray<z.ZodEnum<{
-                            create: "create";
-                            delete: "delete";
-                            read: "read";
-                            traverse: "traverse";
-                            update: "update";
-                        }>>;
-                    }, z.core.$strict>>>;
-                    admin: z.ZodOptional<z.ZodObject<{
-                        grant: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-                            create: "create";
-                            delete: "delete";
-                            grant: "grant";
-                            read: "read";
-                            revoke: "revoke";
-                            traverse: "traverse";
-                            update: "update";
-                            use: "use";
-                        }>>>;
-                        revoke: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-                            create: "create";
-                            delete: "delete";
-                            grant: "grant";
-                            read: "read";
-                            revoke: "revoke";
-                            traverse: "traverse";
-                            update: "update";
-                            use: "use";
-                        }>>>;
-                    }, z.core.$strict>>;
-                }, z.core.$strict>;
-                dependencies: z.ZodArray<z.ZodObject<{
-                    origin: z.ZodString;
-                    installation: z.ZodString;
-                    target: z.ZodString;
-                    readinessReceipt: z.ZodString;
-                    meaningComparison: z.ZodString;
-                }, z.core.$strict>>;
-            }, z.core.$strict>>;
-            target: z.ZodNullable<z.ZodObject<{
-                origin: z.ZodString;
-                schemaRevision: z.ZodString;
-                schemaBundle: z.ZodString;
-                service: z.ZodDiscriminatedUnion<[z.ZodObject<{
-                    kind: z.ZodLiteral<"local">;
-                    artifact: z.ZodString;
-                }, z.core.$strict>, z.ZodObject<{
-                    kind: z.ZodLiteral<"remote">;
-                    etag: z.ZodString;
-                }, z.core.$strict>], "kind">;
-                capabilities: z.ZodObject<{
-                    functions: z.ZodOptional<z.ZodArray<z.ZodString>>;
-                    classes: z.ZodOptional<z.ZodArray<z.ZodObject<{
-                        class: z.ZodObject<{
-                            origin: z.ZodString;
-                            kind: z.ZodLiteral<"class">;
-                            name: z.ZodString;
-                        }, z.core.$strict>;
-                        operations: z.ZodArray<z.ZodEnum<{
-                            create: "create";
-                            delete: "delete";
-                            read: "read";
-                            traverse: "traverse";
-                            update: "update";
-                        }>>;
-                    }, z.core.$strict>>>;
-                    admin: z.ZodOptional<z.ZodObject<{
-                        grant: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-                            create: "create";
-                            delete: "delete";
-                            grant: "grant";
-                            read: "read";
-                            revoke: "revoke";
-                            traverse: "traverse";
-                            update: "update";
-                            use: "use";
-                        }>>>;
-                        revoke: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-                            create: "create";
-                            delete: "delete";
-                            grant: "grant";
-                            read: "read";
-                            revoke: "revoke";
-                            traverse: "traverse";
-                            update: "update";
-                            use: "use";
-                        }>>>;
-                    }, z.core.$strict>>;
-                }, z.core.$strict>;
-                dependencies: z.ZodArray<z.ZodObject<{
-                    origin: z.ZodString;
-                    installation: z.ZodString;
-                    target: z.ZodString;
-                    readinessReceipt: z.ZodString;
-                    meaningComparison: z.ZodString;
-                }, z.core.$strict>>;
-            }, z.core.$strict>>;
-        }, z.core.$strict>;
-        phase: z.ZodEnum<{
+/**
+ * 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;
+        mediaType: import("zod").ZodString;
+        size: import("zod").ZodNumber;
+    }, import("zod/v4/core").$strict>;
+    currentRevision: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
+}, import("zod/v4/core").$strict>, import("zod").ZodObject<{
+    release: import("zod").ZodObject<{
+        url: import("zod").ZodString;
+        token: import("zod").ZodOptional<import("zod").ZodString>;
+        digest: import("zod").ZodOptional<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").ZodOptional<import("zod").ZodEnum<{
+            drain: "drain";
+            revoke: "revoke";
+        }>>;
+    }, import("zod/v4/core").$strict>>;
+    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<{
+        artifact: import("zod").ZodObject<{
+            digest: import("zod").ZodString;
+            mediaType: import("zod").ZodString;
+            size: import("zod").ZodNumber;
+        }, import("zod/v4/core").$strict>;
+        currentRevision: import("zod").ZodOptional<import("zod").ZodNullable<import("zod").ZodString>>;
+    }, import("zod/v4/core").$strict>, import("zod").ZodObject<{
+        release: import("zod").ZodObject<{
+            url: import("zod").ZodString;
+            token: import("zod").ZodOptional<import("zod").ZodString>;
+            digest: import("zod").ZodOptional<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").ZodOptional<import("zod").ZodEnum<{
+                drain: "drain";
+                revoke: "revoke";
+            }>>;
+        }, import("zod/v4/core").$strict>>;
+        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;
+    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: z.ZodLiteral<"committed">;
-        readiness: z.ZodOptional<z.ZodObject<{
-            installation: z.ZodString;
-            target: z.ZodString;
-            transition: z.ZodString;
-            dependencies: z.ZodArray<z.ZodObject<{
-                origin: z.ZodString;
-                installation: z.ZodString;
-                target: z.ZodString;
-                readinessReceipt: z.ZodString;
-                meaningComparison: z.ZodString;
-            }, z.core.$strict>>;
-        }, z.core.$strict>>;
-    }, z.core.$strict>>;
-}, z.core.$strict>;
+        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>;
+/**
+ * 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;
 export interface ArtifactRef {
     readonly digest: InstallationDigest;
     readonly mediaType: string;
     readonly size: number;
 }
-export interface DependencyReadinessCoordinate {
+export interface DependencyReadinessEvidence {
     readonly origin: string;
-    readonly installation: string;
-    readonly target: InstallationDigest;
-    readonly readinessReceipt: InstallationDigest;
-    readonly meaningComparison: InstallationDigest;
+    readonly generation: InstallationDigest;
+    readonly readiness: InstallationDigest;
+    readonly meaning: InstallationDigest;
 }
-export type ServiceTarget = {
-    readonly kind: 'local';
-    readonly artifact: InstallationDigest;
-} | {
-    readonly kind: 'remote';
-    readonly etag: InstallationDigest;
-};
-export type ClassOperation = 'create' | 'read' | 'traverse' | 'update' | 'delete';
-export interface ClassCapabilityRequirement {
-    readonly class: ClassRef;
-    readonly operations: NonEmpty<ClassOperation>;
+export interface DomainGeneration {
+    readonly origin: string;
+    readonly revision: string;
+    readonly generation: InstallationDigest;
 }
-export interface CapabilityRequirements {
-    readonly functions?: NonEmpty<Key.Callable>;
-    readonly classes?: NonEmpty<ClassCapabilityRequirement>;
-    readonly admin?: {
-        readonly grant?: NonEmpty<AuthorityOperation>;
-        readonly revoke?: NonEmpty<AuthorityOperation>;
+/**
+ * The operator's consent to replace the issuer an installation runs under (D7): a compare-and-swap
+ * of the exact installed issuer `from` for the exact issuer `to` the source serves.
+ */
+export interface IssuerConsent {
+    readonly issuer: {
+        readonly from: string;
+        readonly to: string;
     };
-}
-export interface InstallationTarget {
-    readonly origin: string;
-    readonly schemaRevision: string;
-    readonly schemaBundle: InstallationDigest;
-    readonly service: ServiceTarget;
-    readonly capabilities: CapabilityRequirements;
-    readonly dependencies: readonly DependencyReadinessCoordinate[];
+    /**
+     * What the replaced issuer keeps: `drain` (default) accepts it for a bounded time after the
+     * activation, then only for the steps of its durable runs; `revoke` cuts it at the activation.
+     */
+    readonly previous?: 'drain' | 'revoke';
 }
 export interface TransitionIntent {
     readonly transition: string;
     readonly operation: OperationId;
-    readonly installation: string;
     readonly origin: string;
-    readonly source: InstallationTarget | null;
-    readonly target: InstallationTarget | null;
+    readonly previous: DomainGeneration | null;
+    readonly generation: DomainGeneration | null;
+    /** Present only on a replacement that changed its issuer under consent. */
+    readonly consent?: {
+        readonly issuer: {
+            readonly from: string;
+            readonly to: string;
+        };
+        readonly previous: 'drain' | 'revoke';
+    };
 }
 export interface ReadinessReceipt {
-    readonly installation: string;
-    readonly target: InstallationDigest;
+    readonly generation: InstallationDigest;
     readonly transition: string;
-    readonly dependencies: readonly DependencyReadinessCoordinate[];
+    readonly dependencies: readonly DependencyReadinessEvidence[];
 }
 export interface TransitionReceipt {
     readonly intent: TransitionIntent;
@@ -231,28 +281,70 @@ export interface TransitionReceipt {
     readonly state: 'committed';
     readonly readiness?: ReadinessReceipt;
 }
-export type DesiredInstallation = {
-    readonly source: {
-        readonly kind: 'local';
-        readonly artifact: ArtifactRef;
-    };
-    readonly currentRevision?: string | null;
-} | {
-    readonly source: {
-        readonly kind: 'remote';
+/** Installs the exact DomainRelease served by the URL. */
+export interface ReleaseRequest {
+    readonly release: {
         readonly url: string;
         readonly token?: string;
+        /** Requires an exact release digest. Omit to accept the served release. */
+        readonly digest?: ReleaseDigest;
     };
-    readonly targetRevision?: string;
-    readonly targetEtag?: InstallationDigest;
+    /**
+     * Required when the source serves another issuer than the installed one, refused otherwise:
+     * `from` must be the installed issuer and `to` the served one, neither the Kernel issuer.
+     */
+    readonly consent?: IssuerConsent;
+    readonly revision?: string;
     readonly currentRevision?: string | null;
-};
+}
+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<DesiredInstallation>;
+    readonly domains: NonEmpty<DomainRequest>;
+    readonly mode?: InstallMode;
+    readonly validation?: InstallValidation;
 }
-export interface InstallOutput {
+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 {};