@astrale-os/adapter-astrale 0.4.1 → 0.5.0-beta.2

package/README.md

@@ -0,0 +1,11 @@
+# `@astrale-os/adapter-astrale`
+
+Managed Astrale platform deployment adapter for Astrale Domains.
+
+During the SDK beta program, install the beta cohort explicitly:
+
+```bash
+npm install @astrale-os/sdk@beta @astrale-os/adapter-astrale@beta
+```
+
+Bare installs return to stable releases when the cohort is promoted and npm `latest` advances.

package/dist/astrale.d.ts

@@ -3,15 +3,15 @@
  *
  * Ships the domain THROUGH the target instance's `services` domain instead of to
  * the author's own cloud account. `deploy` builds the same single-module workerd
- * bundle the Cloudflare adapter ships (shared codegen + `wrangler deploy
- * --dry-run`), then:
+ * bundle and frontend artifact the Cloudflare adapter ships (shared codegen +
+ * `wrangler deploy --dry-run`), then:
  *
  *   1. hosts it on the instance's services domain — `CloudflareWorker.deploy
  *      { name, entry, modules, assets, vars }` → a public worker `url`;
  *   2. (optional) pushes runtime secrets via the service's `setSecret`;
  *   3. installs the domain on the instance from that `url`
  *      (`astrale domain install <url>` → the child kernel's `Domain.install`,
- *      which fetches + verifies the signed bundle and runs its `postInstall`).
+ *      which fetches, verifies, and reconciles the signed Publication).
  *
  * The admin control plane is NOT involved: hosting moved out of admin into the
  * per-instance `services` domain (a separate bounded context). No Cloudflare
@@ -24,9 +24,60 @@
  * `watch` is identical to the Cloudflare adapter's local dev (wrangler dev on
  * localhost) — managed deploys change WHERE the worker runs, not how you iterate.
  */
-import type { DomainAdapter } from '@astrale-os/sdk';
-import type { AstraleParams } from './params';
+import type { CompiledFrontendArtifact, DomainAdapter } from '@astrale-os/sdk';
+import { buildCloudflareWorker, buildFrontend, logTo, prepare, runWranglerBundle, runWranglerDev, runWranglerTypes, watchFrontend } from '@astrale-os/adapter-cloudflare/build';
+import { loadDeclaredSecrets } from '@astrale-os/sdk/cli';
+import type { AstraleParams } from './params.js';
+import { ensureServicesDomainInstalled, waitForManagedServiceReady } from './managed-service.js';
 export declare function astrale(envs: Record<string, AstraleParams>): DomainAdapter<AstraleParams>;
+export interface AstraleAdapterDependencies {
+    readonly astraleBin: typeof astraleBin;
+    readonly astraleCall: typeof astraleCall;
+    readonly buildCloudflareWorker: typeof buildCloudflareWorker;
+    readonly buildFrontend: typeof buildFrontend;
+    readonly ensureServicesDomainInstalled: typeof ensureServicesDomainInstalled;
+    readonly loadDeclaredSecrets: typeof loadDeclaredSecrets;
+    readonly logTo: typeof logTo;
+    readonly prepare: typeof prepare;
+    readonly readBytes: (path: string) => Buffer;
+    readonly readText: (path: string) => string;
+    readonly runAstrale: typeof runAstrale;
+    readonly runWranglerBundle: typeof runWranglerBundle;
+    readonly runWranglerDev: typeof runWranglerDev;
+    readonly runWranglerTypes: typeof runWranglerTypes;
+    readonly watchFrontend: typeof watchFrontend;
+    readonly waitForManagedServiceReady: typeof waitForManagedServiceReady;
+}
+/** Exact orchestration seam used by adapter-level managed deployment qualification. */
+export declare function astraleWithDependencies(envs: Record<string, AstraleParams>, dependencies: AstraleAdapterDependencies): DomainAdapter<AstraleParams>;
+export interface ManagedDeploymentVersionInput {
+    readonly bundle: Uint8Array;
+    readonly frontend?: CompiledFrontendArtifact;
+    readonly compatibilityDate?: string;
+    readonly compatibilityFlags?: readonly string[];
+    readonly serviceBindings?: readonly {
+        readonly name: string;
+        readonly service: string;
+    }[];
+    readonly vars?: Readonly<Record<string, string>>;
+}
+/**
+ * Stable generation for the whole managed serving contract. The Worker bytes
+ * alone are insufficient: frontend files/routes, compatibility settings,
+ * bindings, and vars can all change without producing a different bundle.
+ */
+export declare function managedDeploymentVersion(input: ManagedDeploymentVersionInput): string;
+/** Preserve author vars while reserving the generation value owned by the adapter. */
+export declare function managedDeploymentVars(vars: Readonly<Record<string, string>> | undefined, deploymentVersion: string): Readonly<Record<string, string>>;
+type AssetFile = {
+    path: string;
+    contentBase64: string;
+    contentType?: string;
+};
+/** Convert the materialized frontend into the services provider's immutable
+ * asset envelope. External frontends deliberately retain routes but no local
+ * files, so the callable worker and browser host remain independently swappable. */
+export declare function managedFrontendAssets(frontend: CompiledFrontendArtifact | undefined): readonly AssetFile[];
 /** Semantic method address; independent of the installed domain's tree placement. */
 export declare function servicesDeployMethodFor(origin: string): string;
 /** Service name from the origin: first DNS label (e.g. `my-notes.example.dev` → `my-notes`). */
@@ -36,4 +87,21 @@ export declare function serviceNameFor(origin: string): string;
  * (serviceNameFor) can collide across domains (`app.foo.dev` / `app.bar.dev`),
  * so the service NODE is placed by this; the display name stays the short label. */
 export declare function serviceSlugFor(origin: string): string;
+/**
+ * Invoke the user's `astrale` CLI for one platform call (against the target
+ * INSTANCE) and parse its JSON output. The CLI owns identity (IdP session,
+ * audience scoping, delegation minting) — reimplementing that here would fork
+ * the trust path.
+ */
+declare function astraleCall(projectDir: string, params: AstraleParams, call: {
+    instance: string;
+    path: string;
+    data: unknown;
+    viaStdin?: boolean;
+}): Promise<unknown>;
+/** Spawn the astrale CLI, feed optional stdin, and return stdout. Throws with bounded diagnostics. */
+declare function runAstrale(bin: string, cwd: string, args: string[], stdin?: string): Promise<string>;
+/** The user's astrale CLI: ~/.astrale/bin/astrale when present, else PATH. */
+declare function astraleBin(_projectDir: string): string;
+export {};
 //# sourceMappingURL=astrale.d.ts.map

package/dist/astrale.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"astrale.d.ts","sourceRoot":"","sources":["../src/astrale.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAa,aAAa,EAAY,MAAM,iBAAiB,CAAA;AAoBzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAW7C,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,aAAa,CAAC,aAAa,CAAC,CAuOzF;AAkGD,qFAAqF;AACrF,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,gGAAgG;AAChG,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED;;;oFAGoF;AACpF,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKrD"}
+{"version":3,"file":"astrale.d.ts","sourceRoot":"","sources":["../src/astrale.ts"],"names":[],"mappings":"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"}

package/dist/astrale.js

@@ -3,15 +3,15 @@
  *
  * Ships the domain THROUGH the target instance's `services` domain instead of to
  * the author's own cloud account. `deploy` builds the same single-module workerd
- * bundle the Cloudflare adapter ships (shared codegen + `wrangler deploy
- * --dry-run`), then:
+ * bundle and frontend artifact the Cloudflare adapter ships (shared codegen +
+ * `wrangler deploy --dry-run`), then:
  *
  *   1. hosts it on the instance's services domain — `CloudflareWorker.deploy
  *      { name, entry, modules, assets, vars }` → a public worker `url`;
  *   2. (optional) pushes runtime secrets via the service's `setSecret`;
  *   3. installs the domain on the instance from that `url`
  *      (`astrale domain install <url>` → the child kernel's `Domain.install`,
- *      which fetches + verifies the signed bundle and runs its `postInstall`).
+ *      which fetches, verifies, and reconciles the signed Publication).
  *
  * The admin control plane is NOT involved: hosting moved out of admin into the
  * per-instance `services` domain (a separate bounded context). No Cloudflare
@@ -27,31 +27,64 @@
 // The shared Cloudflare-Workers build toolkit — the managed adapter ships the
 // SAME bundle the direct `cloudflare` adapter does, then routes it through the
 // platform instead of `wrangler deploy`.
-import { buildClient, CLIENT_DIST_DIR, logTo, prepare, resolveClientDir, runWranglerBundle, runWranglerDev, } from '@astrale-os/adapter-cloudflare/build';
+import { buildCloudflareWorker, buildFrontend, logTo, prepare, runWranglerBundle, runWranglerDev, runWranglerTypes, watchFrontend, } from '@astrale-os/adapter-cloudflare/build';
 import { defineAdapter } from '@astrale-os/sdk';
 import { loadDeclaredSecrets } from '@astrale-os/sdk/cli';
 import { spawn } from 'node:child_process';
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
-import { join, relative } from 'node:path';
-import { ensureServicesDomainInstalled, runManagedInstallWithRetry, waitForManagedServiceReady, } from './managed-service';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ensureServicesDomainInstalled, waitForManagedServiceReady } from './managed-service.js';
 const DEFAULT_PORT = 8787;
 const DEFAULT_SERVICES_ORIGIN = 'services.astrale.ai';
+const DEPLOYMENT_VERSION_BINDING = 'ASTRALE_DEPLOYMENT_VERSION';
 export function astrale(envs) {
+    return astraleWithDependencies(envs, {
+        astraleBin,
+        astraleCall,
+        buildCloudflareWorker,
+        buildFrontend,
+        ensureServicesDomainInstalled,
+        loadDeclaredSecrets,
+        logTo,
+        prepare,
+        readBytes: (path) => readFileSync(path),
+        readText: (path) => readFileSync(path, 'utf8'),
+        runAstrale,
+        runWranglerBundle,
+        runWranglerDev,
+        runWranglerTypes,
+        watchFrontend,
+        waitForManagedServiceReady,
+    });
+}
+/** Exact orchestration seam used by adapter-level managed deployment qualification. */
+export function astraleWithDependencies(envs, dependencies) {
     return defineAdapter({
         name: 'astrale',
         envs,
+        async build(params, ctx) {
+            await dependencies.buildCloudflareWorker({
+                params,
+                context: ctx,
+                onLog: dependencies.logTo(),
+            });
+        },
         // Local dev is unchanged: wrangler dev on localhost. Managed deploys change
         // WHERE the worker ships, not the inner loop.
         async watch(params, ctx) {
-            const clientDir = resolveAstraleClientDir(params, ctx);
-            const { configPath } = await prepare({
+            const frontend = await dependencies.buildFrontend({
+                definition: ctx.definition,
+                projectDir: ctx.projectDir,
+                onLog: dependencies.logTo(),
+            });
+            const { configPath } = await dependencies.prepare({
                 ...(params.vars ? { vars: params.vars } : {}),
                 ...(params.host ? { host: params.host } : {}),
                 port: params.port ?? DEFAULT_PORT,
-            }, ctx, 'dev', { servesClient: Boolean(clientDir), bundleAssets: Boolean(clientDir) });
-            if (clientDir)
-                await buildClient(clientDir, ctx.projectDir, logTo());
-            const handle = await runWranglerDev({
+            }, ctx, 'dev', frontend);
+            const onLog = dependencies.logTo();
+            const handle = await dependencies.runWranglerDev({
                 projectDir: ctx.projectDir,
                 configPath,
                 port: params.port ?? DEFAULT_PORT,
@@ -59,61 +92,104 @@ export function astrale(envs) {
                 autoPickPort: params.port === undefined,
                 ...(params.host ? { ip: '0.0.0.0' } : {}),
                 onReload: ctx.onReload,
-                onLog: logTo(),
+                onLog,
             });
-            return { url: params.host ?? handle.url, stop: handle.stop };
+            let frontendWatch;
+            try {
+                frontendWatch = dependencies.watchFrontend({
+                    definition: ctx.definition,
+                    projectDir: ctx.projectDir,
+                    onLog,
+                    onRebuild: ctx.onReload,
+                });
+            }
+            catch (error) {
+                try {
+                    await handle.stop();
+                }
+                catch (stopError) {
+                    throw new AggregateError([error, stopError], 'frontend watcher failed to start and the local worker failed to stop');
+                }
+                throw error;
+            }
+            return {
+                url: params.host ?? handle.url,
+                async stop() {
+                    const results = await Promise.allSettled([
+                        frontendWatch?.stop() ?? Promise.resolve(),
+                        handle.stop(),
+                    ]);
+                    const failures = results
+                        .filter((result) => result.status === 'rejected')
+                        .map((result) => result.reason);
+                    if (failures.length === 1)
+                        throw failures[0];
+                    if (failures.length > 1)
+                        throw new AggregateError(failures, 'local development failed to stop');
+                },
+            };
         },
         // Config hot-regen for the local dev loop: same codegen as `watch` (the
         // running `wrangler dev` reloads its generated config + entry itself) —
         // the params mapping must stay identical to `watch`'s prepare call.
         async regenerate(params, ctx) {
-            const clientDir = resolveAstraleClientDir(params, ctx);
-            await prepare({
+            const frontend = await dependencies.buildFrontend({
+                definition: ctx.definition,
+                projectDir: ctx.projectDir,
+                onLog: dependencies.logTo(),
+            });
+            const { configPath } = await dependencies.prepare({
                 ...(params.vars ? { vars: params.vars } : {}),
                 ...(params.host ? { host: params.host } : {}),
                 port: params.port ?? DEFAULT_PORT,
-            }, ctx, 'dev', { servesClient: Boolean(clientDir), bundleAssets: Boolean(clientDir) });
-            if (clientDir)
-                await buildClient(clientDir, ctx.projectDir, logTo());
+            }, ctx, 'dev', frontend);
+            await dependencies.runWranglerTypes({
+                projectDir: ctx.projectDir,
+                configPath,
+                onLog: dependencies.logTo(),
+            });
         },
         async deploy(params, ctx) {
-            const log = logTo();
+            const log = dependencies.logTo();
             const instance = params.instance;
             if (!instance) {
                 throw new Error(`astrale adapter: this env has no "instance" — managed deploys need the target ` +
                     `instance slug (e.g. prod: { instance: '<your-instance-slug>' }).`);
             }
             const servicesOrigin = params.servicesOrigin ?? DEFAULT_SERVICES_ORIGIN;
-            const name = params.name ?? serviceNameFor(ctx.domain.origin);
-            const clientDir = resolveAstraleClientDir(params, ctx);
-            const runProjectAstrale = (args) => runAstrale(astraleBin(ctx.projectDir), ctx.projectDir, args);
-            await ensureServicesDomainInstalled({
+            const origin = ctx.definition.schema.origin;
+            const schemaRevision = ctx.definition.domain.$.revision;
+            const name = params.name ?? serviceNameFor(origin);
+            const runProjectAstrale = (args) => dependencies.runAstrale(dependencies.astraleBin(ctx.projectDir), ctx.projectDir, args);
+            await dependencies.ensureServicesDomainInstalled({
                 runAstrale: runProjectAstrale,
                 instance,
                 servicesOrigin,
                 identityArgs: identityArgs(params),
                 log,
             });
-            // Build + pack the client SPA: the services worker serves it under /ui.
-            let assetFiles = [];
-            if (clientDir) {
-                await buildClient(clientDir, ctx.projectDir, log);
-                assetFiles = readAssetFiles(join(ctx.projectDir, CLIENT_DIST_DIR));
-                if (assetFiles.length)
-                    log(`packed client SPA (${assetFiles.length} files) — /ui ships managed`);
+            // Materialize the exact Domain-owned frontend recipe through the same
+            // build boundary used by direct Cloudflare deployments. The managed
+            // provider receives those immutable files separately from the Worker
+            // module while the Worker publication retains the same route metadata.
+            const frontend = await dependencies.buildFrontend({
+                definition: ctx.definition,
+                projectDir: ctx.projectDir,
+                onLog: log,
+            });
+            const assetFiles = managedFrontendAssets(frontend);
+            if (assetFiles.length) {
+                log(`packed frontend (${assetFiles.length} files) — declared routes ship managed`);
             }
             // 1. Codegen + bundle: the exact worker module a Cloudflare deploy would
             //    ship, produced locally with `wrangler deploy --dry-run` (no auth).
-            const { configPath } = await prepare({}, ctx, 'dev', {
-                servesClient: Boolean(clientDir),
-                bundleAssets: false,
-            });
+            const { configPath } = await dependencies.prepare({}, ctx, 'dev', frontend);
             // The generated wrangler config is the single source of truth for the
             // runtime contract the bundle is validated against (compat date + flags,
             // incl. any `params.wrangler` overrides). Carry it to the managed deploy so
             // the live script matches the local dry-run exactly — notably `nodejs_compat`
             // for the `node:*` imports the worker runtime pulls in.
-            const wranglerConfig = JSON.parse(readFileSync(configPath, 'utf8'));
+            const wranglerConfig = JSON.parse(dependencies.readText(configPath));
             // Carry the worker's outbound service bindings (e.g. ROUTER → admin-router)
             // to the managed deploy — without them the deployed worker can't ride the
             // router to reach the kernel and its first credential verification 522s on
@@ -123,19 +199,28 @@ export function astrale(envs) {
                 .filter((s) => s.binding !== 'SELF')
                 .map((s) => ({ name: s.binding, service: s.service }));
             const outDir = join(ctx.projectDir, '.astrale', 'dist-managed');
-            const bundlePath = await runWranglerBundle({
+            const bundlePath = await dependencies.runWranglerBundle({
                 projectDir: ctx.projectDir,
                 configPath,
                 outDir,
                 onLog: log,
             });
-            const bundle = readFileSync(bundlePath);
+            const bundle = dependencies.readBytes(bundlePath);
+            const deploymentVersion = managedDeploymentVersion({
+                bundle,
+                frontend,
+                compatibilityDate: wranglerConfig.compatibility_date,
+                compatibilityFlags: wranglerConfig.compatibility_flags,
+                serviceBindings,
+                vars: params.vars,
+            });
+            const deploymentVars = managedDeploymentVars(params.vars, deploymentVersion);
             // 2. Host it on the instance's services domain. `CloudflareWorker.deploy`
             //    upserts a worker by name on the platform's CF Workers-for-Platforms
             //    backend and returns its public URL. Payload rides STDIN — a bundle is
             //    megabytes of base64, far past argv limits.
             log(`deploying "${name}" to the services domain on "${instance}"…`);
-            const deployed = (await astraleCall(ctx.projectDir, params, {
+            const deployed = (await dependencies.astraleCall(ctx.projectDir, params, {
                 instance,
                 path: servicesDeployMethodFor(servicesOrigin),
                 data: {
@@ -144,7 +229,7 @@ export function astrale(envs) {
                     // the services domain provisions no `/services` folder — so the service
                     // is a root child keyed by the origin slug (unique per instance); `name`
                     // stays the short display label.
-                    path: `/${serviceSlugFor(ctx.domain.origin)}`,
+                    path: `/${serviceSlugFor(origin)}`,
                     name,
                     entry: 'index.mjs',
                     ...(wranglerConfig.compatibility_date
@@ -159,12 +244,12 @@ export function astrale(envs) {
                         ? {
                             assets: {
                                 files: assetFiles,
-                                notFound: 'single-page-application',
+                                notFound: 'none',
                                 runWorkerFirst: true,
                             },
                         }
                         : {}),
-                    ...(params.vars ? { vars: params.vars } : {}),
+                    vars: deploymentVars,
                 },
                 viaStdin: true,
             }));
@@ -176,18 +261,18 @@ export function astrale(envs) {
             // 3. Author runtime secrets: read the env's dotenv locally and push each
             //    via the service's write-only `setSecret` (values ride stdin, never argv).
             if (params.secrets) {
-                const secrets = loadDeclaredSecrets(join(ctx.projectDir, params.secrets), params.secrets);
+                const secrets = dependencies.loadDeclaredSecrets(join(ctx.projectDir, params.secrets), params.secrets);
                 const keys = Object.keys(secrets);
                 if (keys.length)
                     log(`setting ${keys.length} secret(s) from ${params.secrets}…`);
                 for (const [key, value] of Object.entries(secrets)) {
-                    await astraleCall(ctx.projectDir, params, {
+                    await dependencies.astraleCall(ctx.projectDir, params, {
                         instance,
                         // setSecret is an instance method on the deployed service node, which
                         // step 2 placed at `/${serviceSlugFor(origin)}` (a root child — the
                         // services domain provisions no `/services` folder). Address it there,
                         // NOT under a `/services/<name>` path that doesn't exist.
-                        path: `/${serviceSlugFor(ctx.domain.origin)}::setSecret`,
+                        path: `/${serviceSlugFor(origin)}::setSecret`,
                         data: { name: key, value },
                         viaStdin: true,
                     });
@@ -196,17 +281,23 @@ export function astrale(envs) {
             // Cloudflare's dispatch namespace can acknowledge a script before the
             // public tenant host is consistently serving the new worker. Installing
             // before `/meta` + JWKS are reachable turns that propagation window into a
-            // postInstall fetch abort and leaves partial graph state behind.
-            const expectedSchemaHash = await expectedSchemaHashForManagedUrl(ctx, url, log);
-            log(`waiting for managed service "${ctx.domain.origin}" at ${url}…`);
-            await waitForManagedServiceReady(url, ctx.domain.origin, { log, expectedSchemaHash });
+            // Publication fetch abort with an outcome-ambiguous install request.
+            log(`waiting for managed service "${origin}" at ${url}…`);
+            await dependencies.waitForManagedServiceReady(url, origin, {
+                log,
+                expectedSchemaRevision: schemaRevision,
+                expectedDeploymentVersion: deploymentVersion,
+            });
             // 4. Install the domain on the instance from the hosted URL. The child
-            //    kernel fetches the signed bundle, verifies it, and runs its postInstall.
+            //    kernel fetches and verifies the signed Publication and bundle.
             //    A managed deploy ALWAYS aliases identity — the domain's origin
-            //    (`ctx.domain.origin`) is served from the platform host (`…svc.<routing>`)
+            //    (`origin`) is served from the platform host (`…svc.<routing>`)
             //    it never matches — so consent to the override is implicit and required.
-            log(`installing "${ctx.domain.origin}" on "${instance}" from ${url}…`);
-            await runManagedInstallWithRetry(() => runAstrale(astraleBin(ctx.projectDir), ctx.projectDir, [
+            log(`installing "${origin}" on "${instance}" from ${url}…`);
+            // A timeout, reset, or 5xx after delivery is outcome-ambiguous: the first
+            // install may already have committed. Never replay without a public
+            // idempotency/reconciliation contract.
+            await dependencies.runAstrale(dependencies.astraleBin(ctx.projectDir), ctx.projectDir, [
                 'domain',
                 'install',
                 url,
@@ -218,14 +309,11 @@ export function astrale(envs) {
                 '--timeout',
                 '240000',
                 ...identityArgs(params),
-            ]), {
-                log,
-                beforeRetry: () => waitForManagedServiceReady(url, ctx.domain.origin, { log, expectedSchemaHash }),
-            });
+            ]);
             return {
                 url,
                 nextSteps: `  installed on "${instance}" — call it:\n` +
-                    `      astrale call "/${ctx.domain.origin}/..." -i ${instance}`,
+                    `      astrale call "/${origin}/..." -i ${instance}`,
             };
         },
         secretsFile(params) {
@@ -233,29 +321,61 @@ export function astrale(envs) {
         },
     });
 }
-async function expectedSchemaHashForManagedUrl(ctx, url, log) {
-    if (!ctx.schemaHashForUrl)
-        return undefined;
-    try {
-        return await ctx.schemaHashForUrl(url);
-    }
-    catch (error) {
-        log(`warning: could not compute expected schema hash for ${url}; ` +
-            `readiness will verify domain/JWKS only (${errorMessage(error)})`);
-        return undefined;
-    }
+/**
+ * Stable generation for the whole managed serving contract. The Worker bytes
+ * alone are insufficient: frontend files/routes, compatibility settings,
+ * bindings, and vars can all change without producing a different bundle.
+ */
+export function managedDeploymentVersion(input) {
+    const hash = createHash('sha256');
+    const assets = managedFrontendAssets(input.frontend);
+    updateHashFrame(hash, 'format', 'astrale-managed-deployment-v2');
+    updateHashFrame(hash, 'worker', input.bundle);
+    updateHashFrame(hash, 'serving', JSON.stringify({
+        frontend: input.frontend === undefined
+            ? null
+            : {
+                source: input.frontend.artifact.source.kind,
+                digest: input.frontend.digest,
+                assets: assets.length > 0
+                    ? {
+                        files: assets.map(({ path, contentType }) => ({
+                            path,
+                            contentType: contentType ?? null,
+                        })),
+                        notFound: 'none',
+                        runWorkerFirst: true,
+                    }
+                    : null,
+            },
+        compatibilityDate: input.compatibilityDate ?? null,
+        compatibilityFlags: [...(input.compatibilityFlags ?? [])].sort(),
+        serviceBindings: [...(input.serviceBindings ?? [])]
+            .map(({ name, service }) => ({ name, service }))
+            .sort((left, right) => compareStable(`${left.name}\0${left.service}`, `${right.name}\0${right.service}`)),
+        vars: Object.entries(input.vars ?? {}).sort(([left], [right]) => compareStable(left, right)),
+    }));
+    return hash.digest('hex');
 }
-function errorMessage(error) {
-    return error instanceof Error ? error.message : String(error);
+function compareStable(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
 }
-function resolveAstraleClientDir(params, ctx) {
-    return resolveClientDir({
-        adapterName: 'astrale',
-        env: ctx.env,
-        projectDir: ctx.projectDir,
-        domain: ctx.domain,
-        ...(params.client ? { client: params.client } : {}),
-    });
+function updateHashFrame(hash, label, value) {
+    const bytes = typeof value === 'string' ? Buffer.from(value) : value;
+    hash.update(`${Buffer.byteLength(label)}:`);
+    hash.update(label);
+    hash.update(`:${bytes.byteLength}:`);
+    hash.update(bytes);
+}
+/** Preserve author vars while reserving the generation value owned by the adapter. */
+export function managedDeploymentVars(vars, deploymentVersion) {
+    if (Object.hasOwn(vars ?? {}, DEPLOYMENT_VERSION_BINDING)) {
+        throw new Error(`astrale adapter: \`${DEPLOYMENT_VERSION_BINDING}\` is adapter-managed and cannot be set in \`vars\`.`);
+    }
+    if (deploymentVersion.length === 0) {
+        throw new TypeError('astrale adapter: deployment version must not be empty.');
+    }
+    return Object.freeze({ ...vars, [DEPLOYMENT_VERSION_BINDING]: deploymentVersion });
 }
 /** Serving MIME by file extension. The provider serves each asset with the type
  * declared here VERBATIM — Cloudflare does NOT re-infer it from the path, so an
@@ -291,30 +411,22 @@ function assetMime(path) {
     const dot = path.lastIndexOf('.');
     return dot === -1 ? undefined : ASSET_MIME[path.slice(dot + 1).toLowerCase()];
 }
-/** Walk a built SPA dir into the services schema's `AssetFileSchema[]` (paths
- * rooted at `/`), stamping each file's serving MIME from its extension. */
-function readAssetFiles(distClientDir) {
-    const out = [];
-    if (!existsSync(distClientDir))
-        return out;
-    const walk = (dir) => {
-        for (const entry of readdirSync(dir)) {
-            const full = join(dir, entry);
-            if (statSync(full).isDirectory())
-                walk(full);
-            else {
-                const path = `/${relative(distClientDir, full).split('\\').join('/')}`;
-                const contentType = assetMime(path);
-                out.push({
-                    path,
-                    contentBase64: readFileSync(full).toString('base64'),
-                    ...(contentType ? { contentType } : {}),
-                });
-            }
-        }
-    };
-    walk(distClientDir);
-    return out;
+/** Convert the materialized frontend into the services provider's immutable
+ * asset envelope. External frontends deliberately retain routes but no local
+ * files, so the callable worker and browser host remain independently swappable. */
+export function managedFrontendAssets(frontend) {
+    if (frontend === undefined || frontend.artifact.source.kind === 'external') {
+        return Object.freeze([]);
+    }
+    return Object.freeze(frontend.files.map((file) => {
+        const path = `/${file.path}`;
+        const contentType = file.mediaType ?? assetMime(path);
+        return Object.freeze({
+            path,
+            contentBase64: Buffer.from(file.content).toString('base64'),
+            ...(contentType === undefined ? {} : { contentType }),
+        });
+    }));
 }
 /** Semantic method address; independent of the installed domain's tree placement. */
 export function servicesDeployMethodFor(origin) {
@@ -361,17 +473,18 @@ async function astraleCall(projectDir, params, call) {
 function identityArgs(params) {
     return params.identity ? ['--as', params.identity] : [];
 }
-/** Spawn the astrale CLI, feed optional stdin, return stdout+stderr. Throws on non-zero exit. */
+/** Spawn the astrale CLI, feed optional stdin, and return stdout. Throws with bounded diagnostics. */
 async function runAstrale(bin, cwd, args, stdin) {
-    const { code, out } = await new Promise((resolve, reject) => {
+    const { code, stdout, stderr } = await new Promise((resolve, reject) => {
         const child = spawn(bin, args, {
             cwd,
             stdio: [stdin !== undefined ? 'pipe' : 'ignore', 'pipe', 'pipe'],
         });
-        let out = '';
-        child.stdout?.on('data', (b) => (out += b.toString()));
-        child.stderr?.on('data', (b) => (out += b.toString()));
-        child.on('exit', (c) => resolve({ code: c ?? 1, out }));
+        let stdout = '';
+        let stderr = '';
+        child.stdout?.on('data', (b) => (stdout += b.toString()));
+        child.stderr?.on('data', (b) => (stderr += b.toString()));
+        child.on('exit', (c) => resolve({ code: c ?? 1, stdout, stderr }));
         child.on('error', reject);
         if (stdin !== undefined) {
             child.stdin?.write(stdin);
@@ -379,11 +492,12 @@ async function runAstrale(bin, cwd, args, stdin) {
         }
     });
     if (code !== 0) {
-        const authShaped = /AUTH_ERROR|expired|not signed in|credential/i.test(out);
-        throw new Error(`astrale ${args[0]} ${args[1] ?? ''} failed (exit ${code}): ${out.trim().slice(0, 500)}` +
+        const diagnostics = `${stdout}\n${stderr}`.trim();
+        const authShaped = /AUTH_ERROR|expired|not signed in|credential/i.test(diagnostics);
+        throw new Error(`astrale ${args[0]} ${args[1] ?? ''} failed (exit ${code}): ${diagnostics.slice(0, 500)}` +
             (authShaped ? `\nIs the astrale CLI installed and signed in? (astrale auth login)` : ''));
     }
-    return out;
+    return stdout;
 }
 /** The user's astrale CLI: ~/.astrale/bin/astrale when present, else PATH. */
 function astraleBin(_projectDir) {