@atomic-chat/core 0.5.1 → 0.13.2

package/dist/runtime/environment/service.d.ts

@@ -0,0 +1,280 @@
+/**
+ * The part that actually runs a setup: it holds the record, decides nothing itself, and turns each
+ * decision the reducer makes into one piece of external work.
+ *
+ * The split matters because the two halves fail differently. The reducer is a table and is proved
+ * by reading it. Everything the machine does — probing a host, pulling sixteen gigabytes, asking
+ * for a password, importing a distribution — fails in ways nobody enumerates in advance, so it all
+ * arrives here through injected seams that a test can make fail at any point.
+ *
+ * Two things are deliberate. Work is committed with the revision it was computed from, so a result
+ * from an attempt that has been superseded is dropped instead of applied. And the privileged step
+ * is not work this service performs: it hands the step out, and waits for the app to come back with
+ * a receipt, which is then verified against the machine rather than believed.
+ */
+import type { BeginOperation, EnvironmentDiagnostics, EnvironmentOperation, EnvironmentResetResult, EnvironmentSnapshot, ErrorBody, ManagedHostReceipt, ManagedHostStep, ManagedProgress, ProbeEnvironmentInput, RequirementPlan, ResumeOperation, RuntimeDescriptorSummary } from '../../contracts/index.js';
+import type { IdentityDeps } from '../../lock/index.js';
+import type { RuntimeDescriptorProvider } from './descriptor-provider.js';
+import { type EffectInventory } from './recovery.js';
+import { type OperationStore, type PersistedOperation } from './store.js';
+/** What the probe that follows a host-step receipt shows. The receipt itself is never believed. */
+export interface HostStepVerdict {
+    /** Nothing is left to install or authorize: the setup may go on. */
+    prerequisites_met: boolean;
+    /** The `docker` group is granted, the daemon runs, and only a sign-in is missing. */
+    needs_relogin: boolean;
+    /** What is still missing, as the operation's failure when neither of the above holds. */
+    error: ErrorBody | null;
+    /**
+     * A failed step whose log shows Docker found no free address pool: whether `daemon.json` sets
+     * `bip` or `default-address-pools` (task 2.23, review round 1). Absent otherwise.
+     */
+    address_pools_configured?: boolean | 'unknown';
+}
+/** A probe's answer: the plan, the privileged step it needs if any, and whether the image is there. */
+export interface ProvisionerProbe {
+    plan: RequirementPlan;
+    host_step: ManagedHostStep | null;
+    /** The runtime image this operation installs is already present by digest (restart mid-pull). */
+    image_present?: boolean;
+}
+/** What a host recipe can do. One implementation per platform; none of it is decided here. */
+export interface EnvironmentProvisioner {
+    /** Read the machine and say what setting this up would involve. Never changes anything. */
+    probe(record: PersistedOperation, signal: AbortSignal): Promise<ProvisionerProbe>;
+    /** Re-probe after a host-step receipt that claims the step ran (task 2.6). Changes nothing. */
+    verifyHostStep(record: PersistedOperation, signal: AbortSignal): Promise<HostStepVerdict>;
+    /**
+     * Whether `/etc/docker/daemon.json` sets `bip` or `default-address-pools` — read-only, asked only
+     * to explain a failed step whose log shows Docker found no free address pool (task 2.23). Absent
+     * where the host has no such file (off Linux).
+     */
+    addressPoolsConfigured?(): Promise<boolean | 'unknown'>;
+    /**
+     * `own` records, durably and at once, resources the step is about to create, before it creates
+     * them (`OperationStore.recordOwned`): what the operation later removes is only what it made.
+     */
+    prepare(record: PersistedOperation, signal: AbortSignal, own: (resourceIds: string[]) => Promise<void>): Promise<void>;
+    pull(record: PersistedOperation, onProgress: (progress: ManagedProgress) => void, signal: AbortSignal): Promise<void>;
+    verify(record: PersistedOperation, signal: AbortSignal): Promise<void>;
+    /** Take the GPU back from whatever is running on the digest being replaced. */
+    unloadResident(record: PersistedOperation, signal: AbortSignal): Promise<void>;
+    activate(record: PersistedOperation, signal: AbortSignal): Promise<void>;
+    remove(record: PersistedOperation, signal: AbortSignal): Promise<void>;
+    /** Undo only what this operation tentatively created. Never touches what it did not make. */
+    cleanup(record: PersistedOperation, signal: AbortSignal): Promise<void>;
+    inventory: EffectInventory;
+}
+export interface EnvironmentServiceOptions {
+    store: OperationStore;
+    environmentId: string;
+    instanceId: string;
+    newEffectId: () => string;
+    /**
+     * Null when this host has no qualified recipe. The probe then answers with a blocker rather than
+     * failing: an unsupported machine is a fact to report, not a transport error.
+     */
+    provisioner: EnvironmentProvisioner | null;
+    readSnapshot: () => Promise<EnvironmentSnapshot[]>;
+    emit?: (event: 'environment:operation', payload: EnvironmentOperation) => void;
+    /**
+     * How to tell whether the process that last wrote a record (`PersistedOperation.owner_pid`) is
+     * still running — real process checks by default (`src/lock/process-identity.ts`, the same
+     * primitive `InstanceLock` uses for its own takeover decision); tests inject a fake so recovery
+     * is deterministic instead of depending on what is actually alive on the machine running them.
+     */
+    identityDeps?: IdentityDeps;
+    /** The clock progress ticks are throttled by; `Date.now` by default. */
+    now?: () => number;
+    /**
+     * The descriptor cache `descriptor()` answers from (task 2.22). Only `forInstallation`, the
+     * cache-only read: this service is never handed a way to fetch a descriptor for that call.
+     */
+    descriptors?: Pick<RuntimeDescriptorProvider, 'forInstallation'>;
+    /**
+     * Called after `reset()` archived finished operations, with their ids: the snapshot's own view of
+     * operations forgets them and is published again. Absent in tests that do not look.
+     */
+    onReset?: (archivedIds: string[]) => void;
+    /** Builds `diagnostics()`'s report; absent where nothing assembles one (tests). */
+    diagnostics?: () => Promise<EnvironmentDiagnostics>;
+    /** The archive folder's name for a reset: a sortable UTC time by default. */
+    resetStamp?: () => string;
+    /**
+     * A reinstall (`beginReinstall`) began, or its chain ended: the setup it began finished one way or
+     * another, or the removal ended without `removed`. Called with the engine id.
+     */
+    onReinstall?: (engineId: string, moment: 'started' | 'finished') => void;
+    /**
+     * A setup outside a reinstall ended `ready` (`install`), or such a removal ended `removed`
+     * (`uninstall`): the engine's installed build changed. Called with the engine id.
+     */
+    onInstallationChanged?: (engineId: string, change: 'install' | 'uninstall') => void;
+}
+/** What `beginReinstall` takes: the client's idempotency key, the installation, the release to set up. */
+export interface BeginReinstall {
+    request_id: string;
+    target: Extract<BeginOperation['target'], {
+        kind: 'runtime';
+    }>;
+    descriptor_id: string;
+}
+/** How often byte progress of a pull is announced, at most. The first tick always goes out. */
+export declare const PROGRESS_EMIT_INTERVAL_MS = 250;
+export declare class EnvironmentService {
+    private readonly options;
+    private readonly aborts;
+    /**
+     * Byte progress of a pull in flight, by operation. Kept in memory and announced on
+     * `environment:operation` without a new revision: the pull effect was issued at the current
+     * revision and has to answer at it, so a revision per tick would make its own result stale.
+     */
+    private readonly progress;
+    /** The last state of each operation this service announced: what a progress tick is checked against. */
+    private readonly latest;
+    private running;
+    private stopped;
+    constructor(options: EnvironmentServiceOptions);
+    list(): Promise<EnvironmentSnapshot[]>;
+    /** What setting this up would involve, without touching the machine. */
+    probe(input: ProbeEnvironmentInput): Promise<RequirementPlan>;
+    /**
+     * One cached runtime descriptor, as a client shows it (task 2.22): read from the cache by id, never
+     * fetched, so asking cannot change which descriptor an installation or a plan names.
+     * `MANAGED_ADAPTER_UNAVAILABLE` where no host recipe applies (off Linux), like a probe answering
+     * `unsupported` there; `MANAGED_METADATA_INVALID` for an id this core has not cached.
+     */
+    descriptor(descriptorId: string): Promise<RuntimeDescriptorSummary>;
+    /**
+     * Put the environment's bookkeeping back to "nothing was ever attempted" without uninstalling
+     * anything: every finished operation is archived, so no failed setup is shown or resumed any more
+     * and the next setup starts from a fresh probe — with whatever descriptor conf serves now, not the
+     * one an old consent pinned. Refused with `MANAGED_OPERATION_CONFLICT` while an operation is still
+     * running. The distribution, the images, the models, the installation records and the cached conf
+     * documents stay exactly as they are; removing those is `remove`'s job.
+     */
+    reset(environmentId: string): Promise<EnvironmentResetResult>;
+    /** A read-only report on the environment for a support message (`EnvironmentDiagnostics`). */
+    diagnostics(environmentId: string): Promise<EnvironmentDiagnostics>;
+    /**
+     * Start, or hand back the operation this request already started.
+     *
+     * Recovery only runs when a core starts, so an operation whose core died while another core kept
+     * running would refuse every later `begin` on its environment until that other core restarted.
+     * When the operation in the way belongs to a process that can be shown to be gone, it is ended
+     * here instead (task 2.6), and the new request goes ahead.
+     */
+    begin(environmentId: string, input: BeginOperation): Promise<EnvironmentOperation>;
+    private beginWith;
+    /**
+     * The plan a removal of `target` would show, computed as the removal's own probe computes it: what
+     * a caller consenting on the user's behalf approves (a reinstall, `DELETE /engines/…`). Changes
+     * nothing.
+     */
+    planRemoval(environmentId: string, target: BeginOperation['target'], retainModels: boolean): Promise<RequirementPlan>;
+    /**
+     * Reinstall an engine from a newer release (change `unify-engine-lifecycle`, design D6): a removal
+     * that keeps the models, approved here — the client's call to update is the consent to remove — and
+     * on disk the setup that follows it. The setup is begun by this core once the removal ends
+     * `removed` (or by the next core, if this one stops first), and it asks for consent like any
+     * setup: the new image is tens of gigabytes. A retried request answers the same removal.
+     */
+    beginReinstall(environmentId: string, input: BeginReinstall): Promise<EnvironmentOperation>;
+    /** The setup a `removed` reinstall names; idempotent by its request id, across cores and restarts. */
+    private beginFollowUp;
+    /** A finished operation that is part of a reinstall moves the chain on, or ends it. */
+    private afterFinished;
+    get(operationId: string): Promise<EnvironmentOperation>;
+    cancel(operationId: string): Promise<EnvironmentOperation>;
+    /** Approve a plan, or continue after a sign-out, a reboot, a failure or a cancellation. */
+    resume(operationId: string, input: ResumeOperation): Promise<EnvironmentOperation>;
+    /**
+     * Take the app's word for what the OS prompt did, then check it. A receipt is an assertion: the
+     * machine is re-probed before the step counts as done, and a helper that claims success it cannot
+     * show is refused by the reducer.
+     *
+     * A receipt is bound to the pending step by all of its identity: step id, single-use nonce, the
+     * revision the step was issued at, and the recipe and parameter digests. A nonce already used —
+     * the identical receipt again included — a nonce this operation is not waiting for, or another
+     * revision is `MANAGED_RECEIPT_CONFLICT` (spec "Повтор квитанции"); a client that lost the answer
+     * reads the operation instead. Recording the nonce and applying the transition are one
+     * compare-and-swap, so a receipt that races itself is applied once: the loser re-reads, finds its
+     * nonce spent, and is refused.
+     */
+    acceptHostReceipt(operationId: string, receipt: ManagedHostReceipt): Promise<EnvironmentOperation>;
+    /**
+     * Pick up whatever the previous core left behind, against what this machine actually shows.
+     *
+     * A non-terminal operation is not automatically abandoned: app and CLI cores share this store,
+     * so the core that wrote it may simply still be running it right now. Only when the recorded
+     * owner (`PersistedOperation.owner_pid`) can be shown to be gone does this core touch the
+     * record — otherwise two cores would drive the same operation at once, each believing the other
+     * is not there.
+     */
+    recover(instanceId: string): Promise<void>;
+    /** Stop what is in flight. The intent stays on disk, so the next core resumes from it. */
+    shutdown(signal: AbortSignal): Promise<void>;
+    /**
+     * Resolves when nothing is running, or when `signal` fires — whichever comes first. Used by
+     * shutdown, and by tests that drive a whole flow to completion.
+     *
+     * Racing the signal against the wait itself, not just checking it between iterations, is what
+     * actually enforces a caller's deadline: a single effect that ignores its own abort (a
+     * provisioner step that does not return promptly, or a test double that never resolves) would
+     * otherwise leave nothing to check between — `Promise.allSettled` on one such promise simply
+     * never settles, and the loop never reaches its next look at `signal.aborted`.
+     */
+    idle(signal?: AbortSignal): Promise<void>;
+    /** A record shaped like the one a real operation would have, for a probe that starts nothing. */
+    private speculative;
+    /**
+     * What the machine shows after a receipt. A refusal or a failure changed nothing, so there is
+     * nothing to look at; a receipt claiming the step ran is checked by a fresh probe.
+     */
+    private verdictFor;
+    /**
+     * Announce a committed state, and remember it as the operation's current one while it runs. A
+     * finished operation is forgotten, so this map stays as small as what is in flight.
+     */
+    private announce;
+    /** Work that `idle()` and `shutdown()` wait for, like a dispatched effect. */
+    private track;
+    /** `current` is the pull `pulling` started at, still: same phase, same revision. Unknown counts as still. */
+    private stillPulling;
+    /** The operation with the byte progress of a pull still in flight, when there is one. */
+    private withProgress;
+    /**
+     * `begin` was refused because another operation is running on this environment. If that
+     * operation's owner is provably gone, end it and say so; the caller then tries again once.
+     */
+    private endAbandonedBlocker;
+    /**
+     * Apply one event and commit it against the revision it was computed from.
+     *
+     * `owned: false` means somebody else — another call in this core, or the other core over the
+     * same shared store — committed a change to this operation between this call's read and its
+     * compare-and-swap. Its own transition never happened; `record` is simply the current state,
+     * handed back so the caller has something to return. The caller must not dispatch on it: the
+     * write that *did* land already came from a call whose own `apply` returned `owned: true`, and
+     * that call already dispatched whatever comes next. Dispatching again here would run the same
+     * external step (a pull, an activation, a removal) a second time for no reason a retry would.
+     */
+    private apply;
+    /**
+     * Whether the process that last wrote `record` (`owner_pid`) can still be shown to be running.
+     * `unknown` counts as alive, the same as `InstanceLock`'s own takeover decision: an unproven
+     * claim that a core is gone must not let a second core start driving the same operation.
+     */
+    private ownerAlive;
+    /**
+     * Give up on an operation whose owner is gone and that no provisioner exists to reconcile: with
+     * no recipe to check the host against, this operation can never reach a terminal phase on its
+     * own, and leaving it non-terminal would refuse every later `begin` on its environment forever
+     * (`MANAGED_OPERATION_CONFLICT`, `OperationStore.createOrGet`'s busy check).
+     */
+    private failAbandoned;
+    /** Run whatever the machine is now waiting on, without making the caller wait for it. */
+    private dispatch;
+    private perform;
+    private execute;
+}