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

package/dist/microvm/controller/shape-catalogue.js

@@ -0,0 +1,108 @@
+"use strict";
+/**
+ * Parses the `MICROVM_SHAPES` environment variable (a JSON array, written by
+ * CloudFormation from `aws/runner-cdk/src/microvm/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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseShapeCatalogue = parseShapeCatalogue;
+function nonBlankString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function parseShapeEntry(entry, index) {
+    if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+        throw new Error(`MICROVM_SHAPES[${index}] is not an object.`);
+    }
+    const { name, title, description, memory_mib: memoryMiB, image_arn: imageArn, is_default: isDefault, } = entry;
+    if (!nonBlankString(name)) {
+        throw new Error(`MICROVM_SHAPES[${index}] is missing a non-blank "name".`);
+    }
+    if (!nonBlankString(title)) {
+        throw new Error(`Shape "${name}" is missing a non-blank "title".`);
+    }
+    if (!nonBlankString(description)) {
+        throw new Error(`Shape "${name}" is missing a non-blank "description".`);
+    }
+    if (typeof memoryMiB !== 'number' || !Number.isFinite(memoryMiB)) {
+        throw new Error(`Shape "${name}" has a non-number "memory_mib".`);
+    }
+    if (!nonBlankString(imageArn)) {
+        throw new Error(`Shape "${name}" is missing a non-blank "image_arn".`);
+    }
+    if (typeof isDefault !== 'boolean') {
+        throw new Error(`Shape "${name}" has a non-boolean "is_default".`);
+    }
+    return { name, title, description, memoryMiB, imageArn, isDefault };
+}
+/**
+ * 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.
+ */
+function parseShapeCatalogue(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error('MICROVM_SHAPES is not valid JSON.');
+    }
+    if (!Array.isArray(parsed)) {
+        throw new Error('MICROVM_SHAPES must be a JSON array.');
+    }
+    if (parsed.length === 0) {
+        throw new Error('MICROVM_SHAPES must not be empty.');
+    }
+    const shapes = parsed.map((entry, index) => parseShapeEntry(entry, index));
+    const seenNames = new Set();
+    for (const shape of shapes) {
+        if (seenNames.has(shape.name)) {
+            throw new Error(`Duplicate MicroVM shape name "${shape.name}" in MICROVM_SHAPES — shape names must be unique.`);
+        }
+        seenNames.add(shape.name);
+    }
+    const defaults = shapes.filter((shape) => shape.isDefault);
+    if (defaults.length === 0) {
+        throw new Error('MICROVM_SHAPES must mark exactly one shape is_default: true — none does.');
+    }
+    if (defaults.length > 1) {
+        throw new Error('MICROVM_SHAPES must mark exactly one shape is_default: true — ' +
+            `found ${defaults.length}: ${defaults.map((shape) => shape.name).join(', ')}.`);
+    }
+    const defaultShape = defaults[0];
+    return {
+        resolve(name) {
+            if (name === undefined) {
+                return defaultShape;
+            }
+            return shapes.find((shape) => shape.name === name);
+        },
+        advertise() {
+            return shapes.map((shape) => ({
+                name: shape.name,
+                title: shape.title,
+                description: shape.description,
+                memory_mib: shape.memoryMiB,
+                is_default: shape.isDefault,
+            }));
+        },
+    };
+}

package/dist/microvm/controller/throttle-retry.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Retry for the mutating MicroVM operations. `RunMicrovm`/`ResumeMicrovm` are 5/s
+ * and `SuspendMicrovm` is 2/s burst 2, so a doorbell burst throttles in normal
+ * operation. Full jitter over `[300, 900] ms` — worst case 1.2 s, which has to
+ * coexist with the `SUSPENDING` poll (≤ 2 s) inside the Lambda's 8 s timeout.
+ */
+export type Timing = {
+    sleep: (ms: number) => Promise<void>;
+    random: () => number;
+};
+export declare function withThrottleRetry<T>(operation: () => Promise<T>, { sleep, random }: Timing): Promise<T>;

package/dist/microvm/controller/throttle-retry.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * Retry for the mutating MicroVM operations. `RunMicrovm`/`ResumeMicrovm` are 5/s
+ * and `SuspendMicrovm` is 2/s burst 2, so a doorbell burst throttles in normal
+ * operation. Full jitter over `[300, 900] ms` — worst case 1.2 s, which has to
+ * coexist with the `SUSPENDING` poll (≤ 2 s) inside the Lambda's 8 s timeout.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withThrottleRetry = withThrottleRetry;
+const BACKOFF_MS = [300, 900];
+function isThrottling(error) {
+    const name = error?.name;
+    return name === 'ThrottlingException' || name === 'TooManyRequestsException';
+}
+async function withThrottleRetry(operation, { sleep, random }) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            if (attempt >= BACKOFF_MS.length || !isThrottling(error)) {
+                throw error;
+            }
+            await sleep(Math.floor(random() * BACKOFF_MS[attempt]));
+        }
+    }
+}

package/dist/microvm/image/stage-context.d.ts

@@ -0,0 +1,33 @@
+export interface StageMicrovmImageContextOptions {
+    /**
+     * The repository baked into the image as the agent's workspace. This is the
+     * CONSUMER's repository, not Evident's — the image is a dev box for whatever
+     * codebase the agent works on. Must be a full (non-shallow) clone.
+     */
+    readonly repositoryPath: string;
+    /**
+     * `origin` of the baked repository, as the VM will see it. Must be a
+     * credential-free URL (typically `https://github.com/<owner>/<repo>.git`):
+     * this string ships inside the shared snapshot, so a token in it would be
+     * baked into every VM. The credential arrives per-VM instead.
+     */
+    readonly originUrl: string;
+    /** Directory to write the build context to. Removed and recreated. */
+    readonly destination: string;
+    /**
+     * The published template to copy from. Defaults to the one inside this
+     * package; named directly by the tests, which assert against a template they
+     * built themselves rather than whichever `dist/` happens to be present.
+     */
+    readonly templateDir?: string;
+}
+/**
+ * Writes the build context AWS unpacks — the Dockerfile, the hook server, the
+ * per-phase hook scripts and the repository — and returns its path. The result
+ * is what `EvidentMicrovmConstruct`'s `imageSource` takes.
+ *
+ * The first three come from this package's published `dist/`, so a consumer
+ * needs no checkout of `sroze/evident` and no copy of the Dockerfile or hook
+ * scripts (#1528). Only `repositoryPath` is theirs to supply.
+ */
+export declare function stageMicrovmImageContext(options: StageMicrovmImageContextOptions): string;

package/dist/microvm/image/stage-context.js

@@ -0,0 +1,148 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stageMicrovmImageContext = stageMicrovmImageContext;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const path = __importStar(require("node:path"));
+/**
+ * The image build context template published inside this package.
+ *
+ * Resolved from the PACKAGE ROOT, THREE directories above `__dirname` — either
+ * compiled (`dist/microvm/image`) or via ts-node (`src/microvm/image`) — the
+ * same way `microvm/construct.ts` resolves the controller Lambda asset, but one
+ * `..` deeper because this file sits a directory below it. It is
+ * written by `scripts/build.ts` at PACKAGE build time, not at stage time, so a
+ * consumer needs no esbuild and no checkout of this repo (#1528).
+ */
+const TEMPLATE_DIR = path.resolve(__dirname, '..', '..', '..', 'dist', 'microvm-image-context');
+function git(args, cwd) {
+    return (0, node_child_process_1.execFileSync)('git', args, { cwd, encoding: 'utf8' }).trim();
+}
+/**
+ * `git rev-parse --is-shallow-repository` throws an opaque `execFileSync`
+ * error (e.g. "not a git repository") when `repositoryPath` isn't usable at
+ * all, so that failure is rethrown naming the path.
+ */
+function isShallowRepository(repositoryPath) {
+    try {
+        return git(['rev-parse', '--is-shallow-repository'], repositoryPath) === 'true';
+    }
+    catch (err) {
+        throw new Error(`${repositoryPath} is not a usable git repository: ` +
+            `${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Clones the caller's repository into the build context, so the Dockerfile can
+ * ship the workspace already installed.
+ *
+ * `file://` rather than a plain path: a path triggers git's local-clone
+ * optimisation, which copies the whole object store — every branch and worktree
+ * ref on the staging machine (50 MB here). The file transport negotiates like a
+ * network fetch and packs only what the checked-out branch reaches (9 MB), with
+ * one branch and one remote-tracking ref. Ignored files, `node_modules` first
+ * among them, are not part of a clone at all.
+ */
+function stageRepository(repositoryPath, destination, originUrl) {
+    if (isShallowRepository(repositoryPath)) {
+        throw new Error(`refusing to stage a shallow checkout (${repositoryPath}): the agent branches, ` +
+            'commits and opens PRs, so the image needs real history. Run `git fetch --unshallow`.');
+    }
+    // Absolute on both sides: `file://` needs an absolute path to mean anything,
+    // and the clone's cwd is the destination's parent (the only directory both
+    // are guaranteed to resolve against).
+    git(['clone', '--quiet', '--single-branch', `file://${repositoryPath}`, destination], path.dirname(destination));
+    // The clone points `origin` at this machine's filesystem; the VM's origin is
+    // the caller's own remote over HTTPS, with no credential in it.
+    git(['remote', 'set-url', 'origin', originUrl], destination);
+    // The asset hash of the resulting image must be a pure function of the commit,
+    // or every deploy publishes a new `AWS::Lambda::MicrovmImage` version and wedges
+    // the stack at its per-image version ceiling. Two things break that purity:
+    // - `pack-objects`' delta search is multithreaded (`pack.threads` defaults to
+    //   the CPU count) and its output varies run to run; `-f`/`-F`
+    //   (`--no-reuse-delta`/`--no-reuse-object`) additionally stop it from reusing
+    //   whatever packing the source checkout happened to have. All three together
+    //   make the pack a pure function of the object set, independent of the source.
+    // - `.git/index` carries stat data (inode/mtime/size) and `.git/logs/**` carries
+    //   wall-clock reflog timestamps; neither is byte-stable for a fixed commit.
+    git(['-c', 'pack.threads=1', 'repack', '-adfqF'], destination);
+    (0, node_fs_1.rmSync)(path.join(destination, '.git', 'index'), { force: true });
+    (0, node_fs_1.rmSync)(path.join(destination, '.git', 'logs'), { recursive: true, force: true });
+    console.log(`[stage] repo ${git(['rev-parse', 'HEAD'], destination)}`);
+    if (!(0, node_fs_1.existsSync)(path.join(destination, 'pnpm-lock.yaml'))) {
+        console.log(`[stage] ${repositoryPath} has no pnpm-lock.yaml — the image build will skip dependency installation`);
+    }
+}
+/**
+ * Writes the build context AWS unpacks — the Dockerfile, the hook server, the
+ * per-phase hook scripts and the repository — and returns its path. The result
+ * is what `EvidentMicrovmConstruct`'s `imageSource` takes.
+ *
+ * The first three come from this package's published `dist/`, so a consumer
+ * needs no checkout of `sroze/evident` and no copy of the Dockerfile or hook
+ * scripts (#1528). Only `repositoryPath` is theirs to supply.
+ */
+function stageMicrovmImageContext(options) {
+    const { originUrl, templateDir = TEMPLATE_DIR } = options;
+    // `file://` and the clone below only mean anything against absolute paths,
+    // and a caller may reasonably pass either.
+    const repositoryPath = path.resolve(options.repositoryPath);
+    const destination = path.resolve(options.destination);
+    if (!(0, node_fs_1.existsSync)(templateDir)) {
+        throw new Error(`the MicroVM image context template is missing from ${templateDir}. It is written by ` +
+            "this package's build (`pnpm --filter @evident-ai/runner-cdk build`) and ships in the " +
+            'published tarball, so an installed copy should always have it.');
+    }
+    (0, node_fs_1.rmSync)(destination, { recursive: true, force: true });
+    (0, node_fs_1.mkdirSync)(destination, { recursive: true });
+    (0, node_fs_1.copyFileSync)(path.join(templateDir, 'Dockerfile'), path.join(destination, 'Dockerfile'));
+    (0, node_fs_1.copyFileSync)(path.join(templateDir, 'hook-server.js'), path.join(destination, 'hook-server.js'));
+    const hooksSource = path.join(templateDir, 'hooks');
+    const hooksStage = path.join(destination, 'hooks');
+    (0, node_fs_1.mkdirSync)(hooksStage);
+    for (const entry of (0, node_fs_1.readdirSync)(hooksSource)) {
+        const staged = path.join(hooksStage, entry);
+        (0, node_fs_1.copyFileSync)(path.join(hooksSource, entry), staged);
+        // The runtime only runs a hook it can execute. Set here rather than
+        // inherited from the template, so the staged mode is a property of THIS
+        // function rather than of however the template reached disk — `npm pack`
+        // does carry the bit, but a zip-based vendoring, a CI cache restore or a
+        // hand-copied directory need not.
+        (0, node_fs_1.chmodSync)(staged, entry.endsWith('.sh') ? 0o644 : 0o755);
+    }
+    stageRepository(repositoryPath, path.join(destination, 'repo'), originUrl);
+    return destination;
+}

package/dist/microvm/image-version-reporter/construct.d.ts

@@ -0,0 +1,35 @@
+import { Construct } from 'constructs';
+import * as secretsmanager from 'aws-cdk-lib/aws-secretsmanager';
+import type { MicrovmImageBuildInputs } from '@evident-ai/lambda-microvm-cdk';
+export type ImageVersionReporterProps = {
+    /** The secret whose value is the same HMAC key the controller verifies every doorbell against. */
+    doorbellSecret: secretsmanager.ISecret;
+    /** Base URL of Evident's own API — non-secret. */
+    evidentApiUrl: string;
+    /** The pool runner id the report is filed against — non-secret, public UUID. */
+    evidentRunnerId: string;
+    /** Shape name -> the `Fn::GetAtt LatestActiveImageVersion` published this deploy. */
+    imageVersions: Record<string, string>;
+    /**
+     * Shape name -> {@link MicrovmImageBuildInputs}, a STRUCTURED object (never
+     * a delimiter-joined string — see its docstring for why flattening is
+     * unsafe) that changes whenever THIS deploy's build inputs change. Unlike
+     * `imageVersions`' `Fn::GetAtt` (a runtime attribute of the MicroVM image
+     * service, whose deploy-time propagation to a dependent resource this
+     * construct cannot itself guarantee), every field here is either a
+     * synth-time-computed literal or a plain `Ref`/`Fn::GetAtt` to a resource
+     * IN THIS STACK — CloudFormation diffs the full resolved property tree, so
+     * a change anywhere in this object is a certain, not merely likely,
+     * re-invocation trigger.
+     */
+    buildTriggers: Record<string, MicrovmImageBuildInputs>;
+};
+/**
+ * Deploy-time push: reports each shape's just-published MicroVM image version to
+ * Evident, once per deploy that actually changes it. `imageVersions` is the
+ * payload; `buildTriggers` is what guarantees re-invocation on exactly the
+ * deploy that matters, independent of `imageVersions`' own resolution timing.
+ */
+export declare class ImageVersionReporter extends Construct {
+    constructor(scope: Construct, id: string, props: ImageVersionReporterProps);
+}

package/dist/microvm/image-version-reporter/construct.js

@@ -0,0 +1,91 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ImageVersionReporter = void 0;
+const path = __importStar(require("path"));
+const cdk = __importStar(require("aws-cdk-lib"));
+const constructs_1 = require("constructs");
+const lambda = __importStar(require("aws-cdk-lib/aws-lambda"));
+const cr = __importStar(require("aws-cdk-lib/custom-resources"));
+/** The JSON field name inside the doorbell secret, same key the controller reads. */
+const DOORBELL_SECRET_KEY = 'DOORBELL_SECRET';
+/**
+ * Deploy-time push: reports each shape's just-published MicroVM image version to
+ * Evident, once per deploy that actually changes it. `imageVersions` is the
+ * payload; `buildTriggers` is what guarantees re-invocation on exactly the
+ * deploy that matters, independent of `imageVersions`' own resolution timing.
+ */
+class ImageVersionReporter extends constructs_1.Construct {
+    constructor(scope, id, props) {
+        super(scope, id);
+        const handler = new lambda.Function(this, 'Function', {
+            runtime: lambda.Runtime.NODEJS_22_X,
+            // Pre-bundled at PACKAGE build time, same reasoning as the waker's and the
+            // controller's own `Code.fromAsset` (see their comments) — resolved from
+            // the PACKAGE ROOT, two directories below this file either compiled
+            // (`dist/microvm/image-version-reporter`) or via ts-node
+            // (`src/microvm/image-version-reporter`).
+            code: lambda.Code.fromAsset(path.join(__dirname, '..', '..', '..', 'dist', 'image-version-reporter-lambda')),
+            handler: 'handler.handler',
+            memorySize: 128,
+            // A deploy hook must not hold CloudFormation for its default 1 h — this is
+            // the hard stop; the handler's own internal REPORT_TIMEOUT_MS is well under it.
+            timeout: cdk.Duration.seconds(30),
+            environment: {
+                // ARN + field name only, never the value (mirrors the controller and waker).
+                DOORBELL_SECRET_ARN: props.doorbellSecret.secretArn,
+                DOORBELL_SECRET_KEY: DOORBELL_SECRET_KEY,
+                EVIDENT_API_URL: props.evidentApiUrl,
+                EVIDENT_RUNNER_ID: props.evidentRunnerId,
+            },
+        });
+        props.doorbellSecret.grantRead(handler);
+        const provider = new cr.Provider(this, 'Provider', {
+            onEventHandler: handler,
+        });
+        new cdk.CustomResource(this, 'Resource', {
+            serviceToken: provider.serviceToken,
+            properties: {
+                imageVersions: props.imageVersions,
+                // Not read by the handler — its only job is to be a property value
+                // CloudFormation can see change (a structured object, so any field
+                // changing anywhere is a real property diff), so the resource is
+                // invoked on exactly the deploy that changes a build input.
+                buildTriggers: props.buildTriggers,
+            },
+        });
+    }
+}
+exports.ImageVersionReporter = ImageVersionReporter;

package/dist/microvm/image-version-reporter/handler.d.ts

@@ -0,0 +1,26 @@
+export type ImageVersionPair = {
+    shape: string;
+    image_version: string;
+};
+export type ReporterEvent = {
+    RequestType: 'Create' | 'Update' | 'Delete';
+    ResourceProperties?: {
+        imageVersions?: unknown;
+    };
+};
+export type ReporterConfig = {
+    doorbellSecretArn: string;
+    doorbellSecretKey: string;
+    evidentApiUrl: string;
+    evidentRunnerId: string;
+};
+type ReporterDependencies = {
+    getSecret: (secretArn: string, secretKey: string) => Promise<string>;
+    fetch: typeof fetch;
+};
+type ReporterResponse = {
+    PhysicalResourceId: string;
+};
+export declare function handleImageVersionReport(event: ReporterEvent, getConfig: () => ReporterConfig, dependencies?: ReporterDependencies): Promise<ReporterResponse>;
+export declare const handler: (event: ReporterEvent) => Promise<ReporterResponse>;
+export {};

package/dist/microvm/image-version-reporter/handler.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handler = void 0;
+exports.handleImageVersionReport = handleImageVersionReport;
+const node_crypto_1 = require("node:crypto");
+const client_secrets_manager_1 = require("@aws-sdk/client-secrets-manager");
+const PHYSICAL_RESOURCE_ID = 'evident-image-version-report';
+const REPORT_TIMEOUT_MS = 5_000;
+const secrets = new client_secrets_manager_1.SecretsManagerClient({});
+async function fetchDoorbellSecret(secretArn, secretKey) {
+    const { SecretString } = await secrets.send(new client_secrets_manager_1.GetSecretValueCommand({ SecretId: secretArn }));
+    if (!SecretString) {
+        throw new Error(`doorbell secret ${secretArn} has no SecretString`);
+    }
+    const parsed = JSON.parse(SecretString);
+    const value = parsed !== null && typeof parsed === 'object'
+        ? parsed[secretKey]
+        : undefined;
+    if (typeof value !== 'string' || value === '') {
+        throw new Error(`doorbell secret ${secretArn} is missing a non-empty '${secretKey}' field`);
+    }
+    return value;
+}
+function requireEnv(name) {
+    const value = process.env[name];
+    if (!value) {
+        throw new Error(`missing required env var ${name}`);
+    }
+    return value;
+}
+function readImageVersions(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('imageVersions must be an object');
+    }
+    return Object.entries(value).map(([shape, imageVersion]) => {
+        if (typeof imageVersion !== 'string') {
+            throw new Error(`imageVersions.${shape} must be a string`);
+        }
+        return { shape, image_version: imageVersion };
+    });
+}
+function response() {
+    return { PhysicalResourceId: PHYSICAL_RESOURCE_ID };
+}
+const runtimeDependencies = {
+    getSecret: fetchDoorbellSecret,
+    fetch: globalThis.fetch,
+};
+async function handleImageVersionReport(event, getConfig, dependencies = runtimeDependencies) {
+    if (event.RequestType === 'Delete') {
+        return response();
+    }
+    let runnerId = 'unknown';
+    let versions = [];
+    let responseStatus;
+    try {
+        versions = readImageVersions(event.ResourceProperties?.imageVersions);
+        const config = getConfig();
+        runnerId = config.evidentRunnerId;
+        const secret = await dependencies.getSecret(config.doorbellSecretArn, config.doorbellSecretKey);
+        const body = JSON.stringify({
+            type: 'runner.microvm_image_versions_reported',
+            versions,
+        });
+        const signature = (0, node_crypto_1.createHmac)('sha256', secret).update(body).digest('hex');
+        const url = `${config.evidentApiUrl.replace(/\/+$/, '')}/v1/runners/${encodeURIComponent(runnerId)}/microvm-image-versions`;
+        const result = await dependencies.fetch(url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                'x-evident-signature': signature,
+            },
+            body,
+            signal: AbortSignal.timeout(REPORT_TIMEOUT_MS),
+        });
+        responseStatus = result.status;
+        console.log('runner.microvm_image_versions_reported', {
+            runnerId,
+            versions,
+            status: result.status,
+        });
+        if (!result.ok) {
+            throw new Error(`Evident returned HTTP ${result.status}`);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn('MicroVM image version report failed', {
+            operation: event.RequestType,
+            runnerId,
+            versions,
+            ...(responseStatus === undefined ? {} : { status: responseStatus }),
+            error: message,
+        });
+    }
+    return response();
+}
+const handler = (event) => handleImageVersionReport(event, () => ({
+    doorbellSecretArn: requireEnv('DOORBELL_SECRET_ARN'),
+    doorbellSecretKey: requireEnv('DOORBELL_SECRET_KEY'),
+    evidentApiUrl: requireEnv('EVIDENT_API_URL'),
+    evidentRunnerId: requireEnv('EVIDENT_RUNNER_ID'),
+}));
+exports.handler = handler;

package/dist/microvm/shapes.d.ts

@@ -0,0 +1,72 @@
+import { type MicrovmMemoryMiB } from '@evident-ai/lambda-microvm-cdk';
+/**
+ * An operator-authored MicroVM shape: a named memory footprint the controller
+ * can launch a session on. A shape's size is fixed on its image (#723) —
+ * there is no launch-time resource dial — so "a bigger machine" means "a
+ * different shape", each backed by its own `MicrovmImage`.
+ *
+ * `constructId` and `imageName` are carried **explicitly** rather than
+ * derived from `name`, because for the default shape they are frozen
+ * deployment identity (see the comment on `MICROVM_SHAPES` below): deriving
+ * them would let an innocent rename of `name` silently rebuild the live
+ * image. Every other shape is free to name these however is convenient.
+ */
+export interface MicrovmShape {
+    /** The stable id a doorbell asks for; crosses the wire to Evident. */
+    readonly name: string;
+    /** Operator-authored, for Evident's future shape picker. */
+    readonly title: string;
+    /**
+     * Operator-authored; also becomes the image's CloudFormation
+     * `Description`.
+     */
+    readonly description: string;
+    readonly memoryMiB: MicrovmMemoryMiB;
+    /**
+     * Exactly one shape must set this, and — see the ordering contract below —
+     * it must be the first entry in `MICROVM_SHAPES`.
+     */
+    readonly isDefault: boolean;
+    /** The `MicrovmImage` construct id within the stack. */
+    readonly constructId: string;
+    /** The account-unique `imageName` passed to `MicrovmImage`. */
+    readonly imageName: string;
+}
+/**
+ * The committed shape list. Ordering contract (load-bearing, not cosmetic):
+ * the list is ordered, the default shape MUST be the first entry, and the
+ * stack constructs shapes in list order. That is because every non-default
+ * shape's image is built with the default shape's own execution role (D3 in
+ * the plan) — so the default has to exist before any other shape can borrow
+ * its role. Reordering this list to put the default anywhere but index 0 is
+ * a synth-time error (`validateShapes`), not a cosmetic change. The same
+ * order is what `advertise()` (controller-side) hands Evident's future
+ * picker, so default-first is also the picker's ordering — a small price for
+ * making the construction-order contract enforceable rather than a
+ * convention.
+ *
+ * The default entry's `constructId` ("Image") and `imageName`
+ * ("evident-microvm") are FROZEN: they are today's live, hand-deployed
+ * image's identity. Changing either destroys and rebuilds it (~4m45s,
+ * measured) plus a window with no image. Its `description` is copied
+ * verbatim from the image that is live today so the deploy changes nothing
+ * about it.
+ *
+ * "Frozen" means unchanged under OUR OWN synth (no `microvm:*` context set —
+ * `main.ts` passes none). `imageName` MAY carry a customer's
+ * `microvm:namePrefix` (`deployment.ts`'s `resolveShapeCatalogue`) — that is
+ * account-scoped naming, not a change to this module. `constructId` stays
+ * frozen unconditionally, with no override anywhere: it is the
+ * CloudFormation logical-id path, and prefixing it is the resource
+ * replacement this whole file's FROZEN warning exists to prevent.
+ */
+export declare const MICROVM_SHAPES: readonly MicrovmShape[];
+/**
+ * Validates a shape list at synth time. Deliberately lean
+ * (`code-simplicity.mdc`): this is a hand-edited constant list in a typed
+ * file, so it only checks what `tsc` cannot already catch — CDK itself
+ * rejects a duplicate `constructId`, so that one needs no check here, and no
+ * byte-budget cap is applied (the image ARNs are unresolved tokens at synth,
+ * so a rendered size is not measurable anyway).
+ */
+export declare function validateShapes(shapes: readonly MicrovmShape[]): readonly MicrovmShape[];