@evident-ai/runner-cdk 0.1.1-dev.da70cd4 → 3.4.1-dev.1856549

package/dist/microvm/controller/handle-doorbell.js

@@ -0,0 +1,480 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleDoorbell = handleDoorbell;
+const node_crypto_1 = require("node:crypto");
+const sdk_1 = require("@evident/sdk");
+const constants_1 = require("../constants");
+const doorbell_1 = require("./doorbell");
+const throttle_retry_1 = require("./throttle-retry");
+const REASON = {
+    invalidSignature: 'invalid_signature',
+    noMicrovmId: 'no_microvm_id',
+    microvmNotFound: 'microvm_not_found',
+    alreadyRunning: 'already_running',
+    alreadyStarting: 'already_starting',
+    terminated: 'terminated_or_terminating',
+    imageVersionOutdated: 'image_version_outdated',
+    resumeFailedFallingBackToRun: 'resume_failed_falling_back_to_run',
+    suspendingPollExhausted: 'suspending_poll_exhausted',
+    suspendWithoutMicrovmId: 'suspend_without_microvm_id',
+    suspendAlreadyGone: 'suspend_already_gone',
+    getStateFailed: 'get_state_failed',
+    runFailed: 'run_failed',
+    runAlreadyStartedForToken: 'run_already_started_for_token',
+    suspendFailed: 'suspend_failed',
+    suspended: 'suspended',
+    resumed: 'resumed',
+    started: 'started',
+    shapesDescribed: 'shapes_described',
+    unknownShape: 'unknown_shape',
+};
+/** The log vocabulary the runbook greps for; `none`/`rejected` read as `noop`/`reject`. */
+const LOG_ACTION = {
+    none: 'noop',
+    run: 'run',
+    resume: 'resume',
+    suspend: 'suspend',
+    rejected: 'reject',
+    describe: 'describe',
+};
+function decide({ statusCode, action, reason, state, runnerId, microvmId, startedAt, shapes, polled, }) {
+    const line = `[doorbell] state=${state ?? 'none'} action=${LOG_ACTION[action]} ` +
+        `microvm_id=${microvmId ?? '-'} runner_id=${runnerId ?? '-'} reason=${reason}` +
+        (polled === undefined ? '' : ` polled=${polled}`);
+    if (statusCode >= 500) {
+        console.error(line);
+    }
+    else if (statusCode >= 400) {
+        console.warn(line);
+    }
+    else {
+        console.log(line);
+    }
+    return {
+        statusCode,
+        body: JSON.stringify({
+            reason,
+            ...(microvmId === undefined ? {} : { microvm_id: microvmId }),
+            ...(startedAt === undefined ? {} : { microvm_started_at: startedAt.toISOString() }),
+            ...(shapes === undefined ? {} : { shapes }),
+            ...(polled === true ? { polled: true } : {}),
+        }),
+        action: { kind: action },
+    };
+}
+/**
+ * `RunMicrovm`'s idempotency key. Keyed on `runner_id` plus a "generation"
+ * marker: the dead VM's `microvm_id` on the recovery arms (`doorbell.microvmId`
+ * is defined — TERMINATED/TERMINATING/not_found and the resume-failed
+ * fallback), else `occurred_at` on the cold arm (no `microvm_id` yet). The id
+ * advances every VM generation — `mvm-A` dies, the token keyed on it starts
+ * `mvm-B`; once Evident learns `mvm-B`, the NEXT doorbell for that runner is
+ * keyed on `mvm-B` instead — so the token self-advances, and the only case
+ * that ever replays is the one we want collapsed: two concurrent wakes racing
+ * to replace the SAME dead id (#940). The cold arm keeps `occurred_at`: with
+ * no id yet, keying on `runner_id` alone would be stable for the runner's
+ * whole life, so an unrelated cold wake later in that runner's life would
+ * replay a stale cached response and start nothing.
+ *
+ * `RunMicrovm`'s idempotency is parameter-sensitive (measured, #895): a
+ * repeated token with a different `runHookPayload` is rejected
+ * (`ValidationException`, not the `ConflictException` the docs advertise).
+ * Evident mints a fresh runner key per delivery attempt, so a retry reuses
+ * this token but carries a different `runHookPayload` — exactly that
+ * rejection. `isClientTokenParameterMismatch` maps it to a 200 replay rather
+ * than a 500 (#938): AWS already accepted the token and started a VM under
+ * it, but the API gives idempotency, not lookup, so that response cannot
+ * carry a `microvm_id`. See the README's "occurred_at is required..."
+ * section.
+ *
+ * Deliberately excludes `shape` (D4): including it would mean a sender bug
+ * that retried the same event with a different shape starts TWO concurrent
+ * 8-hour VMs instead of deduping to one.
+ */
+function clientTokenFor(doorbell) {
+    const generation = doorbell.microvmId ?? doorbell.occurredAt;
+    return (0, node_crypto_1.createHash)('sha256').update(`${doorbell.runnerId}:${generation}`).digest('hex');
+}
+/**
+ * MicroVM image versions are dotted decimals (`48.0`, `50.0`), so they must NOT
+ * be compared as strings — `'9.0' > '10.0'` lexically. Returns the numeric
+ * components, or `undefined` for anything not exclusively digits and dots,
+ * which the caller must treat as "cannot tell".
+ *
+ * Deliberately private to the controller rather than imported from
+ * `@evident-ai/lambda-microvm-cdk`, which exports the same logic for pruning:
+ * this file is bundled into the controller Lambda, and importing that package
+ * would pull `aws-cdk-lib` into the bundle. Same reasoning as the duplicated
+ * `package-independence.test.ts` guards — a small copy beats a dependency that
+ * drags a whole CDK library across a runtime boundary.
+ */
+function parseImageVersion(value) {
+    const parts = value.trim().split('.');
+    if (parts.some((part) => !/^\d+$/.test(part))) {
+        return undefined;
+    }
+    const numbers = parts.map(Number);
+    return numbers.every(Number.isSafeInteger) ? numbers : undefined;
+}
+/** Negative when `a` orders before `b`, positive when after, 0 when equal. */
+function compareImageVersions(a, b) {
+    for (let i = 0; i < Math.max(a.length, b.length); i++) {
+        const mine = a[i] ?? 0;
+        const theirs = b[i] ?? 0;
+        if (mine !== theirs) {
+            return mine - theirs;
+        }
+    }
+    return 0;
+}
+/**
+ * Whether the SUSPENDED VM must be thrown away and recreated because a newer
+ * image has been published since it booted — a resume would otherwise keep
+ * that VM on its old baked-in hooks and repo checkout for up to 8 hours.
+ *
+ * FAIL-SAFE, one direction only: recreating destroys the VM's filesystem
+ * (only the credentials and `opencode.db` in the object store survive), so
+ * ONLY provably-contrary evidence — a running version we parsed, a latest
+ * version we parsed, and the first strictly below the second — returns true.
+ * A throwing/denied lookup, an absent version on either side, and anything
+ * unparseable all warn and return false, i.e. resume exactly as before
+ * (`development-workflow.mdc`: never fail a gate on absent evidence).
+ */
+async function shouldRecreateForNewerImage(doorbell, shape, runningVersion, microvm) {
+    if (runningVersion === undefined) {
+        console.warn(`[doorbell] GetMicrovm reported no imageVersion for runner ${doorbell.runnerId}; resuming`);
+        return false;
+    }
+    const running = parseImageVersion(runningVersion);
+    if (running === undefined) {
+        console.warn(`[doorbell] unparseable running imageVersion "${runningVersion}" for runner ` +
+            `${doorbell.runnerId}; resuming`);
+        return false;
+    }
+    let latestVersion;
+    try {
+        // Not wrapped in `withThrottleRetry`, unlike every mutation: this runs on
+        // a path with a hard 8 s deadline and its failure mode is already the safe
+        // one, so spending the backoff budget to defend a resume buys nothing.
+        latestVersion = await microvm.latestImageVersion(shape.imageArn);
+    }
+    catch (error) {
+        console.warn(`[doorbell] GetMicrovmImage failed for runner ${doorbell.runnerId}; resuming on the ` +
+            `running image ${runningVersion}: ${error instanceof Error ? error.message : String(error)}`);
+        return false;
+    }
+    const latest = latestVersion === undefined ? undefined : parseImageVersion(latestVersion);
+    if (latest === undefined) {
+        console.warn(`[doorbell] no comparable latest image version (${latestVersion ?? 'none'}) for runner ` +
+            `${doorbell.runnerId}; resuming on the running image ${runningVersion}`);
+        return false;
+    }
+    // Strictly below, not merely different: a running version ABOVE the latest
+    // active one is not contrary evidence — the version it booted from has since
+    // been deactivated, and recreating would not roll it forward. Resume.
+    return compareImageVersions(running, latest) < 0;
+}
+async function handleDoorbell({ rawBody, signatureHeader, doorbellSecret, shapes, microvm, sleep, random, }) {
+    if (!(0, sdk_1.verifyEvidentSignature)(rawBody, signatureHeader, doorbellSecret)) {
+        return decide({
+            statusCode: 401,
+            action: 'rejected',
+            reason: REASON.invalidSignature,
+        });
+    }
+    const parsed = (0, doorbell_1.parseDoorbell)(rawBody);
+    if (!parsed.ok) {
+        return decide({
+            statusCode: 400,
+            action: 'rejected',
+            reason: parsed.reason,
+        });
+    }
+    const doorbell = parsed.doorbell;
+    const timing = { sleep, random };
+    if (doorbell.type === doorbell_1.SHAPES_EVENT_TYPE) {
+        // A pure read of deploy-time metadata — see doorbell.ts's header comment
+        // (D2) for why replay is deliberately undefended here.
+        return decide({
+            statusCode: 200,
+            action: 'describe',
+            reason: REASON.shapesDescribed,
+            shapes: shapes.advertise(),
+        });
+    }
+    // Resolve the requested shape immediately after parseDoorbell/the describe
+    // arm — BEFORE the suspend_requested branch and the whole state machine
+    // (D5). Resolving lazily inside runMicrovm would return 200 and silently
+    // ignore a removed shape on the RUNNING/PENDING no-op path and the
+    // successful-resume path, since runMicrovm is never reached on either. A
+    // suspend doorbell has no `shape` field, so nothing here runs for it.
+    if (doorbell.type !== 'runner.suspend_requested') {
+        const resolvedShape = shapes.resolve(doorbell.shape);
+        if (resolvedShape === undefined) {
+            // 400, not 404/409: a redelivery of the identical body cannot fix this.
+            // Never echo the requested shape name — the closed-constant rule
+            // (doorbell.ts's DOORBELL_REJECTION) applies to every reason here too,
+            // and Evident persists response_body.
+            return decide({
+                statusCode: 400,
+                action: 'rejected',
+                reason: REASON.unknownShape,
+                runnerId: doorbell.runnerId,
+                microvmId: doorbell.microvmId,
+            });
+        }
+        return handleWakeDoorbell(doorbell, resolvedShape, microvm, timing);
+    }
+    return suspendMicrovm(doorbell, microvm, timing);
+}
+async function handleWakeDoorbell(doorbell, shape, microvm, timing) {
+    if (doorbell.microvmId === undefined) {
+        return runMicrovm(doorbell, shape, microvm, timing, false, REASON.noMicrovmId);
+    }
+    let described;
+    let polled = false;
+    try {
+        described = await microvm.describe(doorbell.microvmId);
+        if (described.state === 'SUSPENDING') {
+            described = await pollWhileSuspending(doorbell.microvmId, microvm, timing.sleep);
+            polled = true;
+        }
+    }
+    catch (error) {
+        console.error(`[doorbell] GetMicrovm failed for runner ${doorbell.runnerId}: ` +
+            `${error instanceof Error ? error.message : String(error)}`);
+        // `polled` is omitted here, not passed as `false`: it is only assigned
+        // `true` after `pollWhileSuspending` returns, so a throw mid-poll would
+        // make `false` a fabricated claim that no poll was ever attempted.
+        return decide({
+            statusCode: 500,
+            action: 'none',
+            reason: REASON.getStateFailed,
+            runnerId: doorbell.runnerId,
+            microvmId: doorbell.microvmId,
+        });
+    }
+    const state = described.state;
+    if (state === 'SUSPENDING') {
+        // Retryable: Evident redelivers, by which time the suspend has settled.
+        // This arm is only reachable after a poll (the initial describe would
+        // not still be SUSPENDING), so `polled` is always true here.
+        return decide({
+            statusCode: 409,
+            action: 'none',
+            reason: REASON.suspendingPollExhausted,
+            state,
+            runnerId: doorbell.runnerId,
+            microvmId: doorbell.microvmId,
+            polled,
+        });
+    }
+    switch (state) {
+        case 'RUNNING':
+        case 'PENDING':
+            // Not a silent no-op: the doorbell fired because Evident believes the
+            // tunnel is down, so a live VM here is worth seeing in the logs.
+            return decide({
+                statusCode: 200,
+                action: 'none',
+                reason: state === 'RUNNING' ? REASON.alreadyRunning : REASON.alreadyStarting,
+                state,
+                runnerId: doorbell.runnerId,
+                microvmId: doorbell.microvmId,
+                polled,
+                startedAt: described.startedAt,
+            });
+        case 'SUSPENDED':
+            // A newer image has been published since this VM booted: resuming would
+            // keep it on the old baked-in hooks and repo checkout for up to 8 h, so
+            // take the same recreate path the arm below takes — which, passing no
+            // `imageVersion`, boots the latest (handler.ts's `run`).
+            if (await shouldRecreateForNewerImage(doorbell, shape, described.imageVersion, microvm)) {
+                return runMicrovm(doorbell, shape, microvm, timing, polled, REASON.imageVersionOutdated, state);
+            }
+            return resumeMicrovm(doorbell, doorbell.microvmId, shape, microvm, timing, polled, described.startedAt);
+        default:
+            // TERMINATED, TERMINATING, not_found — gone or going, so a fresh VM either
+            // way. This is what self-heals a stale `microvm_id`.
+            return runMicrovm(doorbell, shape, microvm, timing, polled, state === 'not_found' ? REASON.microvmNotFound : REASON.terminated, state);
+    }
+}
+/**
+ * Phase 0 measured suspend at ~405 ms, so resolving the race in-handler beats
+ * bouncing it through a Cloudflare Queues retry (backoff, a failed delivery, a
+ * stuck conversation). Returns the first non-`SUSPENDING` state it reads.
+ */
+async function pollWhileSuspending(microvmId, microvm, sleep) {
+    let described = { state: 'SUSPENDING' };
+    for (let read = 1; read < constants_1.SUSPENDING_POLL_ATTEMPTS && described.state === 'SUSPENDING'; read++) {
+        await sleep(constants_1.SUSPENDING_POLL_INTERVAL_MS);
+        described = await microvm.describe(microvmId);
+    }
+    return described;
+}
+/**
+ * True only when AWS rejected a repeated `clientToken` for carrying a
+ * different `runHookPayload` (measured, #895 / README's "occurred_at is
+ * required..." section) — the case #938 exists to fix: the VM this token
+ * names has actually started, so the retry that hit this must not 500 into a
+ * DLQ. Both the exception name AND both message substrings are required:
+ * `name` alone is far too wide (a genuine `RunMicrovm` failure sharing the
+ * name would then get a false 200, and the queue would stop retrying it —
+ * the runner never wakes, silently). Any wording this doesn't recognise falls
+ * through to today's 500, which is the safe direction to fail in.
+ */
+function isClientTokenParameterMismatch(error) {
+    const e = error;
+    if (e?.name !== 'ValidationException' && e?.name !== 'ConflictException') {
+        return false;
+    }
+    const message = typeof e.message === 'string' ? e.message.toLowerCase() : '';
+    return message.includes('clienttoken') && message.includes('different request parameters');
+}
+async function runMicrovm(doorbell, shape, microvm, timing, polled, reason, state) {
+    let started;
+    try {
+        started = await (0, throttle_retry_1.withThrottleRetry)(() => microvm.run({
+            imageIdentifier: shape.imageArn,
+            runHookPayload: doorbell.runHookPayload,
+            clientToken: clientTokenFor(doorbell),
+        }), timing);
+    }
+    catch (error) {
+        if (isClientTokenParameterMismatch(error)) {
+            // AWS already accepted this clientToken and started a VM under it; we
+            // just can't name it (RunMicrovm's idempotency gives no lookup) — see
+            // clientTokenFor's docstring. Log the complete AWS message verbatim, not
+            // just the runner id: the predicate above is matched against an
+            // untrusted, AWS-owned string, so if AWS ever rewords it we need to
+            // learn that from a log line, not from a runner that silently never
+            // wakes.
+            const name = error instanceof Error ? error.name : 'unknown';
+            const message = error instanceof Error ? error.message : String(error);
+            console.warn(`[doorbell] RunMicrovm clientToken already used for runner ${doorbell.runnerId}: ` +
+                `${name}: ${message}`);
+            // No `microvmId` (see the comment above), and therefore deliberately no
+            // `startedAt` either: `decide`'s invariant is that `microvm_started_at`
+            // only ever appears beside `microvm_id`. A timestamp with no id to pair
+            // it with is exactly the stale pairing this feature exists to prevent
+            // — Evident would have no VM to attach the expiry deadline to.
+            return decide({
+                statusCode: 200,
+                action: 'run',
+                reason: REASON.runAlreadyStartedForToken,
+                state,
+                runnerId: doorbell.runnerId,
+                polled,
+            });
+        }
+        console.error(`[doorbell] RunMicrovm failed for runner ${doorbell.runnerId}: ` +
+            `${error instanceof Error ? error.message : String(error)}`);
+        return decide({
+            statusCode: 500,
+            action: 'run',
+            reason: REASON.runFailed,
+            state,
+            runnerId: doorbell.runnerId,
+            polled,
+        });
+    }
+    return decide({
+        statusCode: 200,
+        action: 'run',
+        reason,
+        state,
+        runnerId: doorbell.runnerId,
+        microvmId: started.microvmId,
+        polled,
+        startedAt: started.startedAt,
+    });
+}
+async function resumeMicrovm(doorbell, microvmId, shape, microvm, timing, polled, 
+// Threaded in from the `describe()` result that led here — `ResumeMicrovm`
+// itself returns no `startedAt` (its response is empty), so this arm has no
+// timestamp of its own to report.
+startedAt) {
+    try {
+        await (0, throttle_retry_1.withThrottleRetry)(() => microvm.resume(microvmId), timing);
+    }
+    catch (error) {
+        console.error(`[doorbell] ResumeMicrovm failed for runner ${doorbell.runnerId}: ` +
+            `${error instanceof Error ? error.message : String(error)}`);
+        return runMicrovm(doorbell, shape, microvm, timing, polled, REASON.resumeFailedFallingBackToRun, 'SUSPENDED');
+    }
+    return decide({
+        statusCode: 200,
+        action: 'resume',
+        reason: REASON.resumed,
+        state: 'SUSPENDED',
+        runnerId: doorbell.runnerId,
+        microvmId,
+        polled,
+        startedAt,
+    });
+}
+async function suspendMicrovm(doorbell, microvm, timing) {
+    const microvmId = doorbell.microvmId;
+    if (microvmId === undefined) {
+        // Nothing to suspend, and a redelivery would not change that — 200 so the
+        // doorbell is not retried, but loudly enough to notice a mis-wired sender.
+        return decide({
+            statusCode: 200,
+            action: 'none',
+            reason: REASON.suspendWithoutMicrovmId,
+            runnerId: doorbell.runnerId,
+        });
+    }
+    let state;
+    try {
+        // Only the state matters here: a suspend never consults the image version.
+        ({ state } = await microvm.describe(microvmId));
+    }
+    catch (error) {
+        console.error(`[doorbell] GetMicrovm failed for runner ${doorbell.runnerId}: ` +
+            `${error instanceof Error ? error.message : String(error)}`);
+        return decide({
+            statusCode: 500,
+            action: 'none',
+            reason: REASON.getStateFailed,
+            runnerId: doorbell.runnerId,
+            microvmId,
+        });
+    }
+    if (state === 'TERMINATED' || state === 'TERMINATING' || state === 'not_found') {
+        // The desired end state already holds — the VM is gone or going, so
+        // SuspendMicrovm must never be called here (that is what turned a
+        // no-op into a blanket 500-into-DLQ, #1182).
+        return decide({
+            statusCode: 200,
+            action: 'none',
+            reason: REASON.suspendAlreadyGone,
+            state,
+            runnerId: doorbell.runnerId,
+            microvmId,
+        });
+    }
+    try {
+        await (0, throttle_retry_1.withThrottleRetry)(() => microvm.suspend(microvmId), timing);
+    }
+    catch (error) {
+        console.error(`[doorbell] SuspendMicrovm failed for runner ${doorbell.runnerId}: ` +
+            `${error instanceof Error ? error.message : String(error)}`);
+        return decide({
+            statusCode: 500,
+            action: 'suspend',
+            reason: REASON.suspendFailed,
+            state,
+            runnerId: doorbell.runnerId,
+            microvmId,
+        });
+    }
+    return decide({
+        statusCode: 200,
+        action: 'suspend',
+        reason: REASON.suspended,
+        state,
+        runnerId: doorbell.runnerId,
+        microvmId,
+    });
+}

package/dist/microvm/controller/microvm-client.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The MicroVM lifecycle surface the decision core depends on — one method per AWS
+ * operation, no SDK types, so tests drive it with a hand-rolled fake and the
+ * runtime shell is the only place that knows about `@aws-sdk/client-lambda-microvms`.
+ */
+/** Mirrors the SDK's `MicrovmState`; all six values, not just the three §4 names. */
+export type MicrovmLifecycleState = 'PENDING' | 'RUNNING' | 'SUSPENDED' | 'SUSPENDING' | 'TERMINATED' | 'TERMINATING';
+/** What one `GetMicrovm` tells the decision core. */
+export type MicrovmDescription = {
+    state: MicrovmLifecycleState | 'not_found';
+    /**
+     * The image version this VM is running, absent when `not_found` or when
+     * `GetMicrovm` returned none. Its absence must never be read as "up to
+     * date" — see `handle-doorbell.ts`'s `shouldRecreateForNewerImage`.
+     */
+    imageVersion?: string;
+    /**
+     * When this VM instance started, straight from `GetMicrovm`'s own
+     * `startedAt` — absent when `not_found` or when `GetMicrovm` returned none.
+     * Evident derives this VM's AWS-imposed 8 h expiry deadline from this
+     * value, so its absence must ALWAYS be read as UNKNOWN, never as "it just
+     * started" — a fabricated timestamp is worse than none. Never synthesize
+     * one (e.g. `new Date()`) here or in any caller.
+     */
+    startedAt?: Date;
+};
+export interface MicrovmClient {
+    describe(microvmId: string): Promise<MicrovmDescription>;
+    /**
+     * The image's latest ACTIVE version — the one a `run()` below boots, since
+     * it passes no `imageVersion`. `undefined` when the image reports none.
+     * Throws whatever the API threw; callers must treat both that and
+     * `undefined` as "unknown", never as "unchanged".
+     */
+    latestImageVersion(imageIdentifier: string): Promise<string | undefined>;
+    /**
+     * `imageIdentifier` is chosen by the decision core from the shape catalogue
+     * (a doorbell asks for a shape by name; the core resolves it to an image
+     * ARN before calling here). `clientToken` is still derived by the decision
+     * core (from `runner_id:occurred_at`) and deliberately excludes the shape —
+     * it is idempotency-critical, so it is unit-tested where it is built.
+     *
+     * No `idlePolicy` field (AC5, #732) — deliberately omitted, not an oversight.
+     * `maxIdleDurationSeconds` measures INBOUND endpoint traffic only; our runner
+     * is outbound-only (it dials the Cloudflare relay), so AWS sees an idle
+     * endpoint no matter how busy the agent is — Phase 0 measured a VM with
+     * `maxIdleDurationSeconds=60` and zero inbound traffic suspended after 71 s
+     * while its guest process was alive and working
+     * (docs/spikes/lambda-microvms-phase0/README.md). AWS's own Claude-agents
+     * guidance recommending `maxIdleDurationSeconds: 120` targets VMs reached
+     * inbound and does not apply here. Idle is instead decided IN the VM by
+     * `evident run --idle-timeout` (runner/docker-images/microvm/hooks/common.sh's
+     * `IDLE_TIMEOUT_SECONDS`), whose clean exit drives this
+     * client's own `suspend()` via the `runner.suspend_requested` doorbell.
+     */
+    run(input: {
+        imageIdentifier: string;
+        runHookPayload: string;
+        clientToken: string;
+    }): Promise<{
+        microvmId: string;
+        /**
+         * When AWS reports this VM instance started, straight from
+         * `RunMicrovm`'s own `startedAt` (verified: `RunMicrovmResponse` returns
+         * it — `@aws-sdk/client-lambda-microvms` `models_0.d.ts`). Absent means
+         * AWS's own response omitted it, and must be read as UNKNOWN, never as
+         * "it just started" — Evident derives this VM's AWS-imposed 8 h expiry
+         * deadline from this value, so a fabricated timestamp is worse than
+         * none. Never synthesize one (e.g. `new Date()`) here or in any caller.
+         */
+        startedAt?: Date;
+    }>;
+    resume(microvmId: string): Promise<void>;
+    suspend(microvmId: string): Promise<void>;
+}

package/dist/microvm/controller/microvm-client.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * The MicroVM lifecycle surface the decision core depends on — one method per AWS
+ * operation, no SDK types, so tests drive it with a hand-rolled fake and the
+ * runtime shell is the only place that knows about `@aws-sdk/client-lambda-microvms`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/microvm/controller/shape-catalogue.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Parses the `MICROVM_SHAPES` environment variable (a JSON array, written by
+ * CloudFormation from `infrastructure/evident-microvm/src/shapes.ts` at
+ * deploy time — see D6/D7 in the plan) into a `ShapeCatalogue` the pure
+ * decision core can query, without that core ever touching `process.env`
+ * itself.
+ *
+ * A malformed catalogue means a broken deploy: `parseShapeCatalogue` throws
+ * once, loudly, at cold start rather than handing back a half-parsed
+ * catalogue that degrades per-request.
+ *
+ * `resolve()` never falls back to the default shape for a *named* request —
+ * only the absence of a name (`undefined`) means "give me the default". An
+ * unrecognised name returns `undefined` so the caller can reject loudly
+ * (AC-4) instead of silently launching the default shape a doorbell did not
+ * ask for.
+ */
+export interface ControllerShape {
+    readonly name: string;
+    readonly title: string;
+    readonly description: string;
+    readonly memoryMiB: number;
+    readonly imageArn: string;
+    readonly isDefault: boolean;
+}
+/**
+ * The wire projection of a shape for Evident's future picker. Deliberately
+ * omits `imageArn`: it is an account-internal identifier Evident never needs
+ * (it asks for a shape by name; the controller resolves the ARN) and has no
+ * business crossing the account boundary.
+ */
+export interface AdvertisedShape {
+    readonly name: string;
+    readonly title: string;
+    readonly description: string;
+    readonly memory_mib: number;
+    readonly is_default: boolean;
+}
+export interface ShapeCatalogue {
+    /**
+     * `undefined` (no `shape` field on the doorbell) resolves to the default
+     * shape. A defined-but-unrecognised name resolves to `undefined` — the
+     * caller must treat that as a rejection, never as "use the default".
+     */
+    resolve(name: string | undefined): ControllerShape | undefined;
+    /**
+     * Returns every shape in catalogue order — the order the operator wrote
+     * them in `shapes.ts`, with the default first (enforced there). Evident's
+     * future picker gets a deliberate ordering rather than an accidental one.
+     */
+    advertise(): AdvertisedShape[];
+}
+/**
+ * Parses and validates the `MICROVM_SHAPES` catalogue. Mirrors
+ * `validateShapes`'s (`src/shapes.ts`) message vocabulary so an operator
+ * reading a controller cold-start failure recognises it as the same rule
+ * they already met at synth time.
+ *
+ * Throws on: invalid JSON, a non-array, an empty array, an entry missing a
+ * non-blank `name`/`title`/`description`/`image_arn`, a non-number
+ * `memory_mib`, a non-boolean `is_default`, a duplicate `name`, or
+ * zero/multiple `is_default: true` entries.
+ */
+export declare function parseShapeCatalogue(raw: string): ShapeCatalogue;