@cuna_labs/cli 0.1.0

package/dist/api/supervisor-live-update.d.ts

@@ -0,0 +1,248 @@
+import { type Machine } from "./contracts.js";
+/**
+ * `sessions.updateSupervisorInPlace` and `sessions.readSupervisorInPlaceUpdate`
+ * — the running-Machine supervisor update, and the read that recovers it.
+ *
+ * WHAT THE PATH ID IS. `POST /v1/sessions/{id}/supervisor/live-update` reads
+ * `{id}` as a MACHINE, exactly like its stopped-boundary sibling
+ * `sessions.replaceSupervisor`: the producer parses it with `canonicalUuid` into
+ * `machineId` and the `Session` schema it answers with is the Machine row. It is
+ * NOT an AgentSession id, and the per-session custody it reports is a separate
+ * array of `agent_session_id` values. Binding the response to the requested
+ * Machine is therefore a real check, and `api/client.ts` performs it.
+ *
+ * THE OPERATION IDENTITY, which is what makes a lost answer recoverable. The
+ * POST now carries a required body — one field, `operation_id`, chosen by the
+ * CALLER before sending. The producer records that identity durably before it
+ * issues any supervisor enrollment, so repeating the SAME value never rotates a
+ * second time: it resumes an attempt that spent nothing, reconciles one that
+ * may have spent something, and returns the recorded answer once the operation
+ * has settled. A DIFFERENT value for a Machine whose update has not settled is
+ * refused. `sessions.readSupervisorInPlaceUpdate` is the read of that record: it
+ * dispatches no installer, sends nothing to the Machine and changes no state.
+ *
+ * WHERE THE SHAPES BELOW COME FROM, exactly. The VENDORED producer contract at
+ * `contracts/infra/cuna-api.openapi.json`, synchronized by
+ * `npm run contract:sync:infra` from producer repository `Cuna-Labs/infra` at
+ * commit `7b1b3e425ed273986a909a68395b5272bd6a01ba` — read from a clean,
+ * detached, read-only reference worktree, never from a mutable one. The sync
+ * runs the producer's own `contracts/tools/verify-contract.mjs` and refuses
+ * unless the consumer's recomputed canonical digest equals the digest that
+ * verifier attests, so the artifact in this repository is the producer's bytes
+ * and is provably so. `contracts/infra/cuna-api.openapi.identity.json` carries
+ * the commit, tree and blob ids.
+ *
+ * WHY THE TABLE BELOW IS STILL HAND-WRITTEN. The repository's convention for a
+ * canonical DTO is a generated projection (`scripts/project-provider-v2.mjs`
+ * and its siblings). This module keeps its own declaration for one reason a
+ * schema projection cannot cover: the decoders enforce CROSS-FIELD invariants
+ * the producer states in prose and encodes nowhere — a settled phase agrees
+ * with `next_action: "none"` and with a non-null `settled_at`; a declared
+ * session carries no verdict; one AgentSession is never accounted for twice. A
+ * generated shape would check none of those.
+ *
+ * It is not therefore unchecked. `test/machines-live-update-supervisor.test.mjs`
+ * reads the vendored artifact and asserts that every key list, enum and bound
+ * in `SUPERVISOR_LIVE_UPDATE_WIRE` equals the producer's own, so this table is
+ * a VERIFIED projection rather than a copy that can drift in silence. If the
+ * next sync moves any of them, that test names which.
+ */
+export declare const SUPERVISOR_LIVE_UPDATE_WIRE: Readonly<{
+    readonly operationId: "sessions.updateSupervisorInPlace";
+    readonly method: "POST";
+    /** `{id}` is the Machine, not the AgentSession. */
+    readonly pathTemplate: "/v1/sessions/{id}/supervisor/live-update";
+    readonly pathParameterSubject: "machine";
+    readonly requestSchema: "SupervisorLiveUpdateRequest";
+    readonly responseSchema: "SupervisorLiveUpdateResult";
+    readonly sessionSchema: "SupervisorLiveUpdateSession";
+    readonly requiredPermission: "machines:update";
+    /**
+     * A required JSON body carrying the caller's chosen operation identity. There
+     * is still no idempotency key: this identity is the durable one, and it is the
+     * producer's own journal key rather than a transport-level retry token.
+     */
+    readonly hasRequestBody: true;
+    readonly requestContentType: "application/json; charset=utf-8";
+    readonly requestKeys: readonly ["operation_id"];
+    readonly responseKeys: readonly ["machine", "operation_id", "control_generation", "artifact_sha256", "installed_at", "agent_sessions"];
+    readonly sessionKeys: readonly ["agent_session_id", "process_epoch", "outcome"];
+    readonly outcomes: readonly ["preserved", "exited", "ended", "unknown"];
+    /** `maxItems` on `agent_sessions` in the producer schema. */
+    readonly maximumSessions: 64;
+    /**
+     * The read that recovers a lost answer.
+     *
+     * `machines:read`, not `machines:update`: it is a database read scoped to the
+     * owner and the exact Machine. `dispatchesInstaller: false` is the producer's
+     * own statement about it and the reason this CLI may call it freely after an
+     * interruption — the thing a caller must NOT do to resolve an operation is
+     * send a second one, and this is not that.
+     */
+    readonly recovery: Readonly<{
+        operationId: "sessions.readSupervisorInPlaceUpdate";
+        method: "GET";
+        pathTemplate: "/v1/sessions/{id}/supervisor/live-update/{operationId}";
+        pathParameterSubject: "machine";
+        responseSchema: "SupervisorLiveUpdateOperation";
+        declaredSessionSchema: "SupervisorLiveUpdateDeclaredSession";
+        failureSchema: "SupervisorLiveUpdateFailure";
+        requiredPermission: "machines:read";
+        dispatchesInstaller: false;
+        operationKeys: readonly ["operation_id", "machine_id", "phase", "control_rotated", "installer_outcome", "control_generation", "artifact_sha256", "installed_at", "installation_evidence", "declared_sessions", "agent_sessions", "failure", "next_action", "claimed_at", "updated_at", "settled_at", "retired_at", "retirement_outcome"];
+        declaredSessionKeys: readonly ["agent_session_id", "process_epoch"];
+        failureKeys: readonly ["status", "code", "title", "detail", "retryable", "action"];
+        phases: readonly ["claimed", "control_rotated", "installed", "settled"];
+        installerOutcomes: readonly ["not_sent", "unknown", "refused", "installed"];
+        /** `null` is a declared member of the producer's own enum, not an absence. */
+        installationEvidence: readonly ["installer_exit", "reconciled"];
+        nextActions: readonly ["none", "repeat_same_operation"];
+        failureActions: readonly ["retry", "none"];
+        /**
+         * What the Machine's install fence had recorded for this operation's
+         * control generation when the fence was advanced past it. `null` is a
+         * declared member of the producer's enum — "not retired yet" — and is
+         * decoded as absence rather than listed here.
+         *
+         * NEVER a substitute for `installerOutcome`. `installed` here says the
+         * fence recorded an admitted installer that finished; `installerOutcome`
+         * says what CUNA observed, and only it may be rendered as an installation.
+         */
+        retirementOutcomes: readonly ["retired", "partial", "installed"];
+    }>;
+    readonly source: Readonly<{
+        state: "vendored";
+        producerRepository: "Cuna-Labs/infra";
+        producerRevision: "7b1b3e425ed273986a909a68395b5272bd6a01ba";
+        /**
+         * The producer-side artifact is `contracts/` plus the producer's own file
+         * name, which still carries the earlier brand. That literal now exists in
+         * exactly ONE shipped place — `scripts/sync-infra-openapi.mjs`'s
+         * `expectedSourceName`, whose classification `test/error-namespace.test.mjs`
+         * pins line-exactly — and the sync refuses any other source, so restating it
+         * here bought no authority and minted a second unclassified copy of it.
+         * `contracts/infra/cuna-api.openapi.identity.json` records the commit, tree
+         * and blob this table is attributed to.
+         */
+        /** `sha256` of the artifact's exact bytes at that commit. */
+        rawDigest: "f4c2d396b94f296b22df276435dc04ecf1da48807efa1e819c4cbff9ea59a83e";
+        /** The producer's own published digest, under its own canonical semantics. */
+        canonicalDigest: "43213c2adac602676437b612b7d4153707e09155bdc4fa3029cca15a0b207ecc";
+        digestSemantics: "sha256(canonical-json:utf8;recursive-object-key-sort;array-order-preserved)";
+        operations: 101;
+        sdkOperations: 40;
+        vendoredArtifact: "contracts/infra/cuna-api.openapi.json";
+        /** Synchronized 2026-09-13. The declarations above are checked against it. */
+        vendoredCarriesOperation: true;
+        synchronizeWith: "npm run contract:sync:infra";
+    }>;
+}>;
+export type SupervisorLiveUpdateOutcome = (typeof SUPERVISOR_LIVE_UPDATE_WIRE.outcomes)[number];
+export type SupervisorLiveUpdatePhase = (typeof SUPERVISOR_LIVE_UPDATE_WIRE.recovery.phases)[number];
+export type SupervisorLiveUpdateInstallerOutcome = (typeof SUPERVISOR_LIVE_UPDATE_WIRE.recovery.installerOutcomes)[number];
+export type SupervisorLiveUpdateInstallationEvidence = (typeof SUPERVISOR_LIVE_UPDATE_WIRE.recovery.installationEvidence)[number];
+export type SupervisorLiveUpdateNextAction = (typeof SUPERVISOR_LIVE_UPDATE_WIRE.recovery.nextActions)[number];
+export type SupervisorLiveUpdateFailureAction = (typeof SUPERVISOR_LIVE_UPDATE_WIRE.recovery.failureActions)[number];
+export type SupervisorLiveUpdateRetirementOutcome = (typeof SUPERVISOR_LIVE_UPDATE_WIRE.recovery.retirementOutcomes)[number];
+export interface SupervisorLiveUpdateSession {
+    readonly agentSessionId: string;
+    readonly processEpoch: string;
+    /**
+     * The producer's own account of ONE AgentSession that existed before the
+     * update. `preserved` is the only value that means the same process, PTY and
+     * stored master survived; `unknown` is an absent answer and is never folded
+     * into either decided outcome.
+     */
+    readonly outcome: SupervisorLiveUpdateOutcome;
+}
+/**
+ * An AgentSession the attempt MEASURED and is accountable for.
+ *
+ * A statement of scope, never of outcome. It carries no verdict on purpose, and
+ * a renderer that turns a declared session into an `unknown` outcome has
+ * invented an answer the producer withheld.
+ */
+export interface SupervisorLiveUpdateDeclaredSession {
+    readonly agentSessionId: string;
+    readonly processEpoch: string;
+}
+export interface SupervisorLiveUpdate {
+    readonly machine: Machine;
+    /** Echoed from the request. The client checks it against what it sent. */
+    readonly operationId: string;
+    readonly controlGeneration: number;
+    readonly artifactSha256: string;
+    readonly installedAt: string;
+    readonly sessions: readonly SupervisorLiveUpdateSession[];
+}
+/** The refusal a settled operation recorded, in the fields the mutation returned. */
+export interface SupervisorLiveUpdateFailure {
+    readonly status: number;
+    readonly code: string;
+    readonly title: string;
+    readonly detail: string;
+    readonly retryable: boolean;
+    readonly action: SupervisorLiveUpdateFailureAction;
+}
+export interface SupervisorLiveUpdateOperation {
+    readonly operationId: string;
+    readonly machineId: string;
+    readonly phase: SupervisorLiveUpdatePhase;
+    /** True is irreversible and stays true in every later phase. */
+    readonly controlRotated: boolean;
+    readonly installerOutcome: SupervisorLiveUpdateInstallerOutcome;
+    readonly controlGeneration?: number;
+    readonly artifactSha256?: string;
+    /**
+     * When Cuna ESTABLISHED the installation, which is the installation time only
+     * when `installationEvidence` is `installer_exit`.
+     */
+    readonly installedAt?: string;
+    readonly installationEvidence?: SupervisorLiveUpdateInstallationEvidence;
+    /** Scope: the AgentSessions this attempt measured. Empty until prestate binds. */
+    readonly declaredSessions: readonly SupervisorLiveUpdateDeclaredSession[];
+    /** Account: empty unless the operation settled with one. Never fabricated. */
+    readonly sessions: readonly SupervisorLiveUpdateSession[];
+    readonly failure?: SupervisorLiveUpdateFailure;
+    readonly nextAction: SupervisorLiveUpdateNextAction;
+    readonly claimedAt: string;
+    readonly updatedAt: string;
+    readonly settledAt?: string;
+    /**
+     * When Cuna advanced this Machine's install fence past this operation's
+     * control generation. After it, the installer this operation authorized can
+     * perform no configuration write, binary replacement or service restart,
+     * however long it was delayed. Absent until that happens.
+     *
+     * It is what tells one `installerOutcome: "unknown"` from another. Absent,
+     * `unknown` means an authorized installer may still arrive. Present, it means
+     * Cuna never observed that installer AND it can no longer act — and those two
+     * are not interchangeable for anyone deciding whether this Machine is safe to
+     * touch.
+     */
+    readonly retiredAt?: string;
+    /**
+     * What the fence had recorded for this generation when it was retired, and
+     * NEVER a substitute for `installerOutcome`, which is what Cuna observed.
+     *
+     *   `retired`   no admission existed, so the installer never reached the
+     *               fence and the fence precedes every write it could perform.
+     *   `partial`   admitted and unfinished: it began writing.
+     *   `installed` admitted and finished.
+     */
+    readonly retirementOutcome?: SupervisorLiveUpdateRetirementOutcome;
+}
+/** Strict: the producer declares `additionalProperties: false` on both objects. */
+export declare function decodeSupervisorLiveUpdate(value: unknown): SupervisorLiveUpdate;
+/**
+ * The authoritative phase and known result of ONE owned in-place update.
+ *
+ * Everything optional here is optional because the producer types it nullable,
+ * and every one of those nulls means "Cuna has not established this". None of
+ * them is defaulted: a `control_generation` of null is not generation zero, an
+ * empty `agent_sessions` is not a set of `unknown` outcomes, and an
+ * `installed_at` with `installation_evidence: reconciled` is when Cuna LOOKED,
+ * not when the artifact arrived.
+ */
+export declare function decodeSupervisorLiveUpdateOperation(value: unknown): SupervisorLiveUpdateOperation;
+//# sourceMappingURL=supervisor-live-update.d.ts.map

package/dist/api/supervisor-live-update.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor-live-update.d.ts","sourceRoot":"","sources":["../../src/api/supervisor-live-update.ts"],"names":[],"mappings":"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"}