@b00dea/cockpit 0.0.0-stage → 0.1.1

package/dist/environment/state.d.ts

@@ -0,0 +1,410 @@
+import { z } from 'zod';
+import { type SurfaceTarget } from '../surfaces/contract.js';
+import { type BootstrapLockOwnerId } from './identity.js';
+import { ENVIRONMENT_CODES, type CheckoutId, type CockpitId, type HolderId, type EnvironmentObservation, type StackId } from './contract.js';
+export declare const observationDeclarations: readonly [{
+    readonly id: 'config-freshness';
+    readonly owner: "environment-state";
+    readonly postures: readonly ["environment"];
+    readonly stages: readonly [{
+        readonly stage: 'bootstrap';
+        readonly disposition: 'required';
+    }, {
+        readonly stage: 'steady';
+        readonly disposition: 'required';
+    }];
+    readonly code: "CONFIG_STALE";
+    readonly isIssued: typeof isStateObservation;
+    readonly issuedAt: typeof observationIssuedAt;
+}, {
+    readonly id: 'config-schema-validity';
+    readonly owner: "environment-state";
+    readonly postures: readonly ["environment"];
+    readonly stages: readonly [{
+        readonly stage: 'bootstrap';
+        readonly disposition: 'required';
+    }, {
+        readonly stage: 'steady';
+        readonly disposition: 'required';
+    }];
+    readonly code: "CONFIG_SCHEMA_INVALID";
+    readonly isIssued: typeof isStateObservation;
+    readonly issuedAt: typeof observationIssuedAt;
+}];
+export declare function isStateObservation(value: unknown): value is EnvironmentObservation;
+declare function observationIssuedAt(value: unknown): number | undefined;
+export declare function observeConfiguration(input: {
+    readonly path: string;
+    readonly stackId: StackId;
+    readonly observedAt: string;
+}): Promise<readonly EnvironmentObservation[]>;
+export declare const SERIALIZED_RECORD_BYTE_LIMIT = 1048576;
+declare const RECORD_KINDS: readonly ['coordination', 'lifecycle', 'lifecycle-history', 'data-outcome', 'cache'];
+declare const StateRecordSchema: z.ZodObject<{
+    format: z.ZodLiteral<"cockpit-state/v1">;
+    kind: z.ZodEnum<{
+        cache: "cache";
+        coordination: "coordination";
+        "data-outcome": "data-outcome";
+        lifecycle: "lifecycle";
+        "lifecycle-history": "lifecycle-history";
+    }>;
+    cockpitId: z.ZodString;
+    subjectId: z.ZodString;
+    revision: z.ZodNumber;
+    updatedAt: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+    value: z.ZodJSONSchema;
+}, z.core.$strict>;
+export type StateRecord = z.infer<typeof StateRecordSchema>;
+type StateRecordKind = typeof RECORD_KINDS[number];
+declare const BootstrapStateRecordSchema: z.ZodObject<{
+    format: z.ZodLiteral<"cockpit-state/v1">;
+    kind: z.ZodLiteral<"bootstrap">;
+    checkoutId: z.ZodString;
+    target: z.ZodEnum<{
+        claudecode: "claudecode";
+        codexcli: "codexcli";
+        cursor: "cursor";
+        grokcli: "grokcli";
+        opencode: "opencode";
+    }>;
+    revision: z.ZodNumber;
+    updatedAt: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+    value: z.ZodObject<{
+        stage: z.ZodEnum<{
+            "draft-observed": "draft-observed";
+            "draft-prepared": "draft-prepared";
+            "environment-verified": "environment-verified";
+            "surface-previewed": "surface-previewed";
+            "surface-published": "surface-published";
+        }>;
+        checkoutRoot: z.ZodString;
+        target: z.ZodEnum<{
+            claudecode: "claudecode";
+            codexcli: "codexcli";
+            cursor: "cursor";
+            grokcli: "grokcli";
+            opencode: "opencode";
+        }>;
+        sources: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            sha256: z.ZodString;
+        }, z.core.$strict>>;
+        commandSha256: z.ZodString;
+        previewSha256: z.ZodString;
+        published: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            sha256: z.ZodString;
+        }, z.core.$strict>>;
+        destination: z.ZodNullable<z.ZodString>;
+        artifactBytes: z.ZodNullable<z.ZodString>;
+        artifactSha256: z.ZodNullable<z.ZodString>;
+        greenfield: z.ZodOptional<z.ZodObject<{
+            mode: z.ZodOptional<z.ZodEnum<{
+                estate: "estate";
+                registry: "registry";
+            }>>;
+            stage: z.ZodEnum<{
+                "answers-recorded": "answers-recorded";
+                "question-pending": "question-pending";
+                resolved: "resolved";
+            }>;
+            classification: z.ZodOptional<z.ZodEnum<{
+                "incomplete-multi-repository": "incomplete-multi-repository";
+                "no-runnable-product": "no-runnable-product";
+                "one-sibling": "one-sibling";
+                "ready-multi-repository": "ready-multi-repository";
+            }>>;
+            sourceObservationSha256: z.ZodString;
+            notice: z.ZodOptional<z.ZodString>;
+            questions: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                field: z.ZodString;
+                source: z.ZodString;
+                why: z.ZodString;
+                expectedSha256: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+            answers: z.ZodArray<z.ZodObject<{
+                questionId: z.ZodString;
+                bytes: z.ZodString;
+                sha256: z.ZodString;
+                provenance: z.ZodEnum<{
+                    "agent-default": "agent-default";
+                    derived: "derived";
+                    "operator-confirmed": "operator-confirmed";
+                    unattributed: "unattributed";
+                }>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type BootstrapStateRecord = z.infer<typeof BootstrapStateRecordSchema>;
+type AnyStateRecord = StateRecord | BootstrapStateRecord;
+export interface StateAddress {
+    readonly path: string;
+    readonly stateRoot: string;
+    readonly cockpitRoot: string;
+    readonly kind: StateRecordKind;
+    readonly cockpitId: CockpitId;
+    readonly subjectId: string;
+    readonly qualifier?: string;
+}
+export interface StateNamespace {
+    readonly root: string;
+    readonly cockpitRoot: string;
+    readonly paths: {
+        readonly coordination: (stackId: StackId) => StateAddress;
+        readonly lifecycle: (stackId: StackId) => StateAddress;
+        readonly dataOutcome: (stackId: StackId) => StateAddress;
+        readonly stateLock: string;
+        readonly installLock: (cacheId: string) => string;
+        readonly cache: (checkoutId: CheckoutId, cacheIdentitySha256: string) => StateAddress;
+    };
+}
+export interface BootstrapStateAddress {
+    readonly path: string;
+    readonly stateRoot: string;
+    readonly checkoutRoot: string;
+    readonly kind: 'bootstrap';
+    readonly checkoutId: CheckoutId;
+    readonly target: SurfaceTarget;
+}
+export interface BootstrapStateNamespace {
+    readonly root: string;
+    readonly checkoutRoot: string;
+    readonly checkoutId: CheckoutId;
+    readonly target: SurfaceTarget;
+    readonly paths: {
+        readonly bootstrap: (target: SurfaceTarget) => BootstrapStateAddress;
+        readonly stateLock: string;
+    };
+}
+export type StateResult<T> = {
+    readonly kind: 'complete';
+    readonly value: T;
+} | {
+    readonly kind: 'missing';
+    readonly path: string;
+} | {
+    readonly kind: 'indeterminate';
+    readonly code: typeof ENVIRONMENT_CODES.STATE_DURABILITY_INDETERMINATE;
+    readonly message: string;
+    readonly target: string;
+    readonly recovery: string;
+    readonly value: T;
+} | {
+    readonly kind: 'refusal';
+    readonly code: typeof ENVIRONMENT_CODES.STATE_ROOT_UNAVAILABLE | typeof ENVIRONMENT_CODES.STATE_FORMAT_UNSUPPORTED | typeof ENVIRONMENT_CODES.STATE_RECORD_MALFORMED | typeof ENVIRONMENT_CODES.STATE_LOCKED;
+    readonly message: string;
+    readonly target: string;
+    readonly recovery?: string;
+};
+interface SelectStateRootInput {
+    readonly platform: 'darwin' | 'linux';
+    readonly home: string | undefined;
+    readonly xdgStateHome?: string;
+    readonly checkoutRoot?: string;
+    readonly checkoutRoots?: readonly string[];
+    readonly cockpitId: CockpitId;
+    readonly uid?: number;
+}
+export interface SelectBootstrapStateRootInput {
+    readonly platform: 'darwin' | 'linux';
+    readonly home: string | undefined;
+    readonly xdgStateHome?: string;
+    readonly checkoutRoot: string;
+    readonly target: SurfaceTarget;
+    readonly uid?: number;
+}
+type LockHolderState = 'live' | 'dead' | 'unknown';
+interface StateLockInspection {
+    readonly holderState: LockHolderState | 'invalid';
+    readonly description: string;
+    readonly recovery: string;
+}
+export interface StateTransactionOptions {
+    readonly ownerId: HolderId | BootstrapLockOwnerId;
+    readonly observeHolder?: (holder: {
+        readonly ownerId: HolderId | BootstrapLockOwnerId;
+        readonly pid: number;
+    }) => Promise<LockHolderState>;
+    readonly beforePublish?: (temporaryPath: string) => Promise<void>;
+    readonly beforeCommit?: () => StateTransactionAbort<unknown> | undefined;
+    readonly beforeRelease?: () => Promise<void>;
+    readonly beforeLockMetadata?: (operation: 'owner-unlink' | 'tombstone-rmdir' | 'owner-restore-link' | 'backup-unlink') => Promise<void>;
+    readonly contentionTimeoutMs?: number;
+}
+interface StateScopedLock {
+    readonly kind: 'state-scoped-lock';
+}
+export interface StateTransactionAbort<T> {
+    readonly aborted: true;
+    readonly value: T;
+}
+export declare function abortStateTransaction<T>(value: T): StateTransactionAbort<T>;
+type StatePublicationStatus = 'complete' | 'indeterminate';
+export declare function authenticateStatePublication(input: {
+    readonly publication: StateResult<AnyStateRecord>;
+    readonly address: StateAddress | BootstrapStateAddress;
+}): Readonly<{
+    readonly status: StatePublicationStatus;
+    readonly record: AnyStateRecord;
+}> | undefined;
+export declare function authenticateStateNamespace(value: unknown): StateNamespace | undefined;
+export declare function issueStateScopedLock(namespace: StateNamespace, input: Readonly<{
+    owner: string;
+    identity: string;
+}>): StateScopedLock | undefined;
+export declare function withStateRootPortLock<T>(value: StateNamespace, options: Pick<StateTransactionOptions, 'ownerId' | 'observeHolder' | 'contentionTimeoutMs' | 'beforeRelease' | 'beforeLockMetadata'>, operation: () => T | Promise<T>): Promise<StateResult<T>>;
+export type SkippedStateNamespace = Readonly<{
+    path: string;
+    reason: string;
+}>;
+export declare function withStateNamespaceInventory<T>(value: StateNamespace, operation: (namespaces: readonly StateNamespace[], skipped: readonly SkippedStateNamespace[]) => T | Promise<T>): Promise<StateResult<T>>;
+export declare function lifecycleHistoryAddress(value: StateNamespace, stackId: StackId): StateAddress | undefined;
+export declare function parseCoordinationStateEntry(name: string): Readonly<{
+    kind: 'record';
+    stackId: StackId;
+} | {
+    kind: 'temporary';
+} | {
+    kind: 'executor';
+    stackId: StackId;
+    attemptId: string;
+}> | undefined;
+export declare function snapshotStateNamespace(value: StateNamespace): StateNamespace | undefined;
+export declare function snapshotBootstrapStateNamespace(value: BootstrapStateNamespace): BootstrapStateNamespace | undefined;
+/**
+ * The per-user state root, without a cockpit or checkout: what `runtime measure` needs to record a
+ * fact about this machine before any stack exists. It is the same root `selectStateRoot` scopes
+ * each cockpit under, so every checkout of every cockpit on this machine reaches the same directory.
+ */
+export declare function selectMachineStateRoot(input: Readonly<{
+    platform: 'darwin' | 'linux';
+    home: string | undefined;
+    xdgStateHome?: string;
+    uid?: number;
+}>): Promise<StateResult<string>>;
+export declare function selectBootstrapStateRoot(input: SelectBootstrapStateRootInput): Promise<StateResult<BootstrapStateNamespace>>;
+export declare function selectStateRoot(input: SelectStateRootInput): Promise<StateResult<StateNamespace>>;
+export declare function readState(address: BootstrapStateAddress): Promise<StateResult<BootstrapStateRecord>>;
+export declare function readState(address: StateAddress): Promise<StateResult<StateRecord>>;
+export declare function readState(address: StateAddress | BootstrapStateAddress): Promise<StateResult<AnyStateRecord>>;
+interface BootstrapAnswerResetPreview {
+    readonly revision: number;
+    readonly field: string;
+    readonly invalidatedFields: readonly string[];
+    readonly previewSha256: string;
+}
+type BootstrapAnswerResetResult = Readonly<{
+    kind: 'pending';
+    preview: BootstrapAnswerResetPreview;
+}> | Readonly<{
+    kind: 'complete';
+    preview: BootstrapAnswerResetPreview;
+    record: BootstrapStateRecord;
+}> | Readonly<{
+    kind: 'refusal';
+    code: string;
+    message: string;
+    target: string;
+}>;
+export declare function resetBootstrapAnswer(namespace: BootstrapStateNamespace, address: BootstrapStateAddress, input: Readonly<{
+    ownerId: BootstrapLockOwnerId;
+    field: string;
+    updatedAt: string;
+    acceptedPreviewSha256?: string;
+}>): Promise<BootstrapAnswerResetResult>;
+type BootstrapObservationRefreshRefusal = Readonly<{
+    kind: 'refusal';
+    reason: 'invalid' | 'stale';
+    message: string;
+}>;
+type BootstrapObservationRefreshResult = StateResult<BootstrapStateRecord> | BootstrapObservationRefreshRefusal;
+export declare function refreshBootstrapObservation(namespace: BootstrapStateNamespace, address: BootstrapStateAddress, input: Readonly<{
+    ownerId: BootstrapLockOwnerId;
+    expectedRevision: number;
+    expectedSourceObservationSha256: string;
+    greenfield: NonNullable<BootstrapStateRecord['value']['greenfield']>;
+    updatedAt: string;
+}>): Promise<BootstrapObservationRefreshResult>;
+type BootstrapPublicationRefreshRefusal = Readonly<{
+    kind: 'refusal';
+    reason: 'invalid' | 'stale';
+    message: string;
+}>;
+type BootstrapPublicationRefreshResult = StateResult<BootstrapStateRecord> | BootstrapPublicationRefreshRefusal;
+export declare function refreshBootstrapPublication(namespace: BootstrapStateNamespace, address: BootstrapStateAddress, input: Readonly<{
+    ownerId: BootstrapLockOwnerId;
+    expectedRevision: number;
+    expectedSources: BootstrapStateRecord['value']['sources'];
+    expectedCommandSha256: string;
+    expectedPreviewSha256: string;
+    expectedPublished: BootstrapStateRecord['value']['published'];
+    sources: BootstrapStateRecord['value']['sources'];
+    previewSha256: string;
+    published: BootstrapStateRecord['value']['published'];
+    updatedAt: string;
+}>): Promise<BootstrapPublicationRefreshResult>;
+/**
+ * Replaces bootstrap state whose publication is gone from the checkout with a fresh preview record.
+ * The caller proves the absence; the expected revision keeps a concurrent init from being discarded.
+ */
+export declare function restartBootstrapState(namespace: BootstrapStateNamespace, address: BootstrapStateAddress, input: Readonly<{
+    ownerId: BootstrapLockOwnerId;
+    expectedRevision: number;
+    updatedAt: string;
+    value: Readonly<{
+        commandSha256: string;
+        previewSha256: string;
+        sources: readonly BootstrapStateRecord['value']['sources'][number][];
+    }>;
+}>): Promise<StateResult<BootstrapStateRecord> | Readonly<{
+    kind: 'stale';
+}>>;
+export declare function inspectStateLock(namespace: StateNamespace | BootstrapStateNamespace, observeHolder?: StateTransactionOptions['observeHolder']): Promise<StateLockInspection>;
+export declare function withStateScopedLock<T>(namespace: StateNamespace, scope: StateScopedLock, options: Pick<StateTransactionOptions, 'ownerId' | 'observeHolder' | 'contentionTimeoutMs' | 'beforeRelease' | 'beforeLockMetadata'>, operation: () => T | Promise<T>): Promise<StateResult<T>>;
+export declare function transactState(namespace: StateNamespace, address: StateAddress, options: StateTransactionOptions, update: (current: StateRecord | null) => StateRecord | Promise<StateRecord>): Promise<StateResult<StateRecord>>;
+export declare function transactState<T>(namespace: StateNamespace, address: StateAddress, options: StateTransactionOptions, update: (current: StateRecord | null) => StateRecord | StateTransactionAbort<T> | Promise<StateRecord | StateTransactionAbort<T>>): Promise<StateResult<StateRecord> | StateTransactionAbort<T>>;
+export declare function transactState(namespace: BootstrapStateNamespace, address: BootstrapStateAddress, options: StateTransactionOptions, update: (current: BootstrapStateRecord | null) => BootstrapStateRecord | Promise<BootstrapStateRecord>): Promise<StateResult<BootstrapStateRecord>>;
+export declare function transactState<T>(namespace: BootstrapStateNamespace, address: BootstrapStateAddress, options: StateTransactionOptions, update: (current: BootstrapStateRecord | null) => BootstrapStateRecord | StateTransactionAbort<T> | Promise<BootstrapStateRecord | StateTransactionAbort<T>>): Promise<StateResult<BootstrapStateRecord> | StateTransactionAbort<T>>;
+/** One of a stack's own record files, by the SHA-256 of its exact bytes. */
+export type StackStateFile = Readonly<{
+    kind: 'coordination' | 'lifecycle' | 'lifecycle-history' | 'data-outcome';
+    path: string;
+    sha256: string;
+}>;
+/** A stack's record files, and its coordination record decoded from the very bytes its file digest binds. */
+type StackStateRead = Readonly<{
+    files: readonly StackStateFile[];
+    /** Undefined when the stack has no coordination file. */
+    coordination: StateResult<StateRecord> | undefined;
+}>;
+/** The record files a stack has under one cockpit's namespace, read as bytes so an unparseable record is listed too. */
+export declare function inspectStackState(value: StateNamespace, stackId: StackId): Promise<StateResult<readonly StackStateFile[]>>;
+/** `inspectStackState`, plus the coordination record decoded from the bytes it read rather than from a second read. */
+export declare function inspectStackRecords(value: StateNamespace, stackId: StackId): Promise<StateResult<StackStateRead>>;
+/** What a guarded removal did: removed the named paths, or found them changed since the preview and left them. */
+type StateRemoval = Readonly<{
+    kind: 'removed';
+    paths: readonly string[];
+}> | Readonly<{
+    kind: 'changed';
+    reason: string;
+}>;
+/**
+ * Deletes a stack's record files, which releases its port lease, only when each file still holds the
+ * exact bytes `expected` names and no other file has appeared. It runs under the root port lock, so
+ * no `up` leases ports from a view that still counts the lease, and under the cockpit's own state
+ * lock, so no transaction rewrites a record between the check and the removal.
+ */
+export declare function removeStackState(value: StateNamespace, stackId: StackId, expected: readonly StackStateFile[], options: Readonly<{
+    ownerId: HolderId;
+}>): Promise<StateResult<StateRemoval>>;
+/** A digest of another cockpit's state folder that this version cannot read: every entry's path, mode, size and modification time. */
+export declare function inspectStateNamespaceFolder(value: StateNamespace, path: string): Promise<StateResult<string>>;
+/** Deletes another cockpit's unreadable state folder, under the root port lock, only while it still matches `fingerprint`. */
+export declare function removeStateNamespaceFolder(value: StateNamespace, path: string, fingerprint: string, options: Readonly<{
+    ownerId: HolderId;
+}>): Promise<StateResult<StateRemoval>>;
+export {};