@astrale-os/adapter-cloudflare 0.5.0-beta.18 → 0.5.0-beta.181

package/README.md

@@ -2,10 +2,238 @@
 
 Cloudflare Worker deployment adapter for Astrale Domains.
 
-During the SDK beta program, install the beta cohort explicitly:
+During the SDK beta program, install the beta package set explicitly:
 
 ```bash
 npm install @astrale-os/sdk@beta @astrale-os/adapter-cloudflare@beta
 ```
 
-Bare installs return to stable releases when the cohort is promoted and npm `latest` advances.
+Bare installs return to stable releases when the package set is promoted and npm `latest` advances.
+
+One `cloudflare()` value configures one Project Environment in a Workers for Platforms dispatch
+namespace. Each release becomes one immutable deployment on your own Cloudflare account or on a
+platform's. A deploy never installs: install the URL it prints with
+`astrale domain install <url> -i <instance>`.
+
+Generated Worker modules are minified by default, including separately loaded runtime modules.
+The Environment's `wrangler` overlay cannot change minification: every Environment of one source
+must emit the same JavaScript bytes. `cloudflare({ wrangler: { minify: false } })` is rejected.
+
+## Host it yourself
+
+Anyone with a Cloudflare account, Workers for Platforms and a domain of their own can host
+immutable deployments, with no Astrale infrastructure:
+
+1. **A domain.** Add a zone to Cloudflare and pick a routing domain under it dedicated to the
+   deployments, such as `deploy.example.dev`: every deployment answers at
+   `https://<label>.deploy.example.dev`. Nothing else may serve a host at, under or above it, and
+   its wildcard name needs an edge certificate (Advanced Certificate Manager, or Total TLS).
+2. **A token.** Create an API token with Workers Scripts Edit, Workers KV Storage Edit, Workers
+   Routes Edit and Zone DNS Edit on that zone. Export it as `CLOUDFLARE_API_TOKEN`, with
+   `CLOUDFLARE_ACCOUNT_ID` (and `CLOUDFLARE_ZONE_ID` when the zone cannot be found from the domain).
+3. **The Environment.**
+
+   ```ts
+   production: {
+     deployment: cloudflare({
+       namespace: { name: 'my-deployments', routingDomain: 'deploy.example.dev' },
+       secrets: '.env.production',
+     }),
+   },
+   ```
+
+4. **Provision once.** `astrale-domain cloudflare plan production` reads the account and prints
+   what provisioning does and what blocks it; `astrale-domain cloudflare init production`
+   provisions it (both are commands this adapter declares; `--json` prints the result):
+   the dispatch namespace, its routing KV, the dispatcher Worker (`<name>-dispatcher`, or
+   `--dispatcher <worker>`), a proxied `AAAA 100::` record `*.<domain>` and the route
+   `*.<domain>/*` to the dispatcher, then checks that a never-deployed host reaches it over HTTPS.
+   It is idempotent: a rerun adopts what exists and uploads the dispatcher again.
+5. **Deploy.** `astrale-domain deploy production` prints the deployment URL, which
+   `astrale domain install` takes.
+
+## Namespace mode
+
+`astrale-domain deploy <environment>` uploads one script named by the deployment label, create-only
+(`If-None-Match: *`), which answers at `https://<label>.<routingDomain>` through the namespace's
+dispatcher. Nothing is ever replaced in place: another build or configuration is another label.
+Every line is readable. Namespace mode is a thin layer over the hosting kit below.
+
+- **Credentials.** `CLOUDFLARE_API_TOKEN` must edit the namespace's scripts and the values of its
+  routing KV; the account is `namespace.account`, else `CLOUDFLARE_ACCOUNT_ID`. Neither is ever
+  written to the configuration.
+- **Routing KV.** The deploy finds the namespace's routing KV by its title,
+  `astrale-deployment-routing-<first 16 bytes of sha256(name), in hexadecimal>`, which
+  provisioning creates. A namespace without it is refused before any effect. The names of
+  Services' deployments namespaces (`astrale-deployments-<hex>`) are refused: Services manages
+  their scripts.
+- **Bindings.** Each new deployment binds `WORKER_URL`, `ASTRALE_BUILD_DIGEST`, `ASTRALE_SETTINGS`
+  (the router as `ROUTER`), the author's `vars`, the service and dispatch namespace bindings of
+  `wrangler`, the router, its version metadata, and as `secret_text` exactly the Environment's
+  secrets and `ASTRALE_SIGNING_IDENTITY`, a key generated for that deployment and kept nowhere
+  else. Its tags name its artifact (build digest), line and key; never `astrale-service`, which is
+  Services'.
+- **Activation.** The deploy writes `record:<label>` with its media type metadata, whose presence
+  makes the dispatcher route the label: the canonical `DeploymentRecordV1`, published through the
+  kit's opaque record, which the dispatcher serves at `/.well-known/astrale/deployment.json`. It
+  never holds a provider version or a secret digest. Readiness then waits, bounded, until the URL serves the
+  sealed release from the provider version the upload created.
+- **Reuse.** A redeploy of the same release finds the script under its label. It is reused only
+  when its artifact and line tags and its record name this build and configuration (only the
+  record's commit may differ: the deployment keeps the record it was first activated with), or,
+  when an interrupted deploy left it unactivated, when it binds exactly this configuration. Then only that
+  script's declared secrets are rewritten in place, and readiness waits for the version the
+  rewrite minted. Anything else is a `deployment-conflict`, refused with nothing written; no other
+  deployment is ever touched. A `summary:<label>` an older adapter wrote is ignored.
+- **Retirement.** A label whose `retirement:<label>` the kit's `markRetired` wrote answers
+  `DEPLOYMENT_RETIRED` at the dispatcher and is refused by every later deploy. The namespace keeps
+  every deployment until then: there is no retention, preview expiry or `retain`.
+- **Listing.** `astrale-domain list` lists the Environment's deployments from the routing KV and
+  the namespace, and writes nothing: one row per label of the Environment's line that
+  `record:<label>` activated or `retirement:<label>` withdrew, with its record as stored (a record
+  the SDK refuses is listed with `record: null` and the refusal), its script's creation instant and
+  key while the script exists, and the call target `{ kind: 'namespace', namespace, script }`. Its
+  state is `active`, `retiring` (tombstoned, script not deleted yet), `retired` (script deleted) or
+  `failed` (activated, script gone).
+- **Refused.** A direct-mode parameter beside `namespace` (`route`, `workerName`, `identityIssuer`,
+  `addressing`, `signingIdentity`), a `router.binding` other than `ROUTER`, and any `wrangler` key
+  but `services`, `dispatch_namespaces` and `compatibility_flags`, `triggers` first: an immutable
+  deployment runs no cron of its own. A `dispatch_namespaces` entry is exactly
+  `{ binding, namespace }`; it is frozen into the configuration (`bindings.dispatchNamespaces`), so
+  into the label, bound at the create-only upload, and never names the namespace the deployment
+  lives in (AM-174). Which namespaces a deployment may bind is its host's to decide.
+  `durable` is frozen into the configuration (`settings.durableOptions`, AM-175), so into the
+  label, and bound in `ASTRALE_SETTINGS`: a durable run stays on the deployment that started it.
+
+## Hosting kit
+
+`@astrale-os/adapter-cloudflare/hosting` is the one implementation of this hosting, for namespace
+mode and for any other host that keeps its own routing beside it. Everything but provisioning runs in
+Node and inside a Worker (`fetch` and WebCrypto only).
+
+- **Client.** `CloudflareClient`: bounded bodies, `Retry-After`/429 waits by policy
+  (`DEFAULT_RATE_LIMIT`, `OPERATOR_RATE_LIMIT` or none), timeouts and a deadline, typed
+  `CloudflareApiError`s (`kind`, `status`, `codes`), cursor and numbered pagination, multipart
+  forms, raw KV text and bytes.
+- **Routing KV.** `RoutingKv` (by title or id) and the contract: `record:<label>` (the deployment's
+  record, opaque bytes with their media type in the value's metadata, `{"contentType":...}`, or
+  `-` with `{"contentType":null}` for a deployment that publishes none; written once and kept only
+  for the same bytes and media type), `retirement:<label>` (`withdrawn`), `current:<name>` (one of
+  the name's labels), `cron:<name>` (canonical UTC crons). The record's metadata is mandatory: a
+  `record:<label>` without it activates nothing at the dispatcher (every path of the label answers
+  as not active yet, and no cron fires on it) and the kit refuses it (`record-invalid`) instead of
+  reading it as any record. Every write is read back before it counts.
+- **Scripts.** `deploymentBindings`, `deploymentTags` (with a host's extra tags),
+  `uploadDeploymentScript` (create-only, every module kind, assets in parallel),
+  `observeScript`, `scriptSettings`, `scriptSecretNames`, `putScriptSecret`, `deleteScript`, and
+  `createSigningIdentity` (WebCrypto Ed25519).
+- **Lifecycle.** `activateDeployment` (a label and its record, `WorkerRecord` of
+  `@astrale-os/sdk/deployment/worker`, or `null`), `readRecord`, `promoteDeployment`,
+  `replaceSchedules`, two-phase retirement
+  (`markRetired`, then `completeRetirement` once `retirementVisible` sees the dispatcher answer
+  `DEPLOYMENT_RETIRED`), `waitForReadiness` through the public URL or a dispatch binding, and
+  `listLineDeployments`.
+- **Dispatcher.** Plain ES modules shipped with the package (`dispatcherModules()`), routing a label
+  to its script, a name to `current:<name>`, and firing `cron:<name>` on schedule. It serves a
+  label's record at `/.well-known/astrale/deployment.json`, its bytes and media type as published
+  (immutable, `405` but for `GET` and `HEAD`), and hands that path to a deployment that publishes
+  none. `createDispatcher()` owns routing and schedule admission. The public never reaches
+  `/__scheduled`; cron targets serve that internal POST endpoint.
+- **Provisioning.** `planHosting` reads; `applyHosting` refuses any blocker before its first write;
+  `provisionHosting` does both.
+- **Testing.** `@astrale-os/adapter-cloudflare/hosting/testing` exports `FakeCloudflare`, one fake
+  account that serves public requests with the real dispatcher.
+
+## Frontend files
+
+The Worker runs before Workers Static Assets on every request and owns frontend response headers
+and routing, for `cloudflare()` and `astrale()` deployments alike. Frontend preparation therefore
+refuses a built frontend whose root contains `_headers`, `_redirects`, or `.assetsignore`, in any
+letter case, as a file or a directory. Wrangler and managed deployments would otherwise interpret these files differently. The refusal happens while
+the artifact is prepared, before any provider change. Vite copies its public directory (`public/`
+by default) to that root: remove them there, or stop the plugin that emits them. The same names
+below the root, such as `docs/_headers`, remain ordinary files.
+
+The Worker is also the only server-side code, so preparation likewise refuses a root name starting
+with `_worker.js`, the name of a Cloudflare Pages worker script: a `_worker.js` file or directory,
+or a sibling such as `_worker.js.map`. Wrangler refuses to upload these as assets, since they may
+hold server-side code, so a direct deployment would fail at upload, while a managed deployment would
+publish them. Unlike the names above, the match is case-sensitive, as Wrangler's is: `_Worker.js`
+and a nested `docs/_worker.js` remain ordinary files. Remove such a file from the public directory,
+or rename it if it is a browser script.
+
+## Deployment bindings
+
+The bundled Worker carries no Environment value, so every Environment of one source bundles the
+same bytes. Each deployment binds its own values as plain Worker bindings:
+
+| Binding | Value |
+| --- | --- |
+| `WORKER_URL` | serving origin of the deployment |
+| `ASTRALE_SETTINGS` | canonical JSON of `{ invocationTimeoutMs, maximumRequestBytes, router, tokenExchange }`, defaults resolved, with optional `durableOptions` |
+| `ASTRALE_BUILD_DIGEST` | required build digest the host recomputed from the uploaded bytes |
+
+These names are adapter-owned: preparation refuses an author var, or a `wrangler.vars` entry, that
+takes one, and deployment refuses a secret that does. A host that deploys the Worker itself encodes
+the settings with `encodeWorkerSettings` from `@astrale-os/adapter-cloudflare/worker`. A generated
+Worker refuses execution without `ASTRALE_SETTINGS`.
+
+Every Worker requires `WORKER_URL` and `ASTRALE_BUILD_DIGEST`. It seals the `DomainRelease` v4
+of its code at that serving URL, which is also its issuer, and serves it at
+`/.well-known/astrale/release.json`. Routing must name that exact Release. The Worker refuses
+execution when either binding is missing or invalid; a foreign request origin is refused before
+loading the Service. `domain.json` serves no compatibility projection.
+
+The `wrangler` overlay reaches the deployment configuration, never the bundle. Preparation refuses
+an overlay key the bundler reads (`alias`, `build`, `define`, `jsx_factory`, `jsx_fragment`,
+`keep_names`, `minify`, `no_bundle`, `node_compat`, `preserve_file_names`, `rules`, `tsconfig`,
+`upload_source_maps`) and a compatibility flag it reads (Node.js, `navigator`, fetch iterable
+typing, Python) beyond the adapter's own `nodejs_compat`.
+
+## Build digest
+
+`cloudflare()` and `astrale()` bundle through one bundler, `cloudflare-worker` version `1`, so
+every Environment of either adapter shares one build: `astrale-domain build` prints its build
+digest, and `deploy` places that same Bundle. Two installed versions of this package are two
+copies of the bundler: when their code differs, `build` prints one build digest per copy and warns
+until the adapter versions are aligned.
+
+Services and namespace deployments upload the placed modules unchanged, so the digest names the
+bytes the deployment runs. A host with its own Worker entrypoint describes its final upload with
+`workerBuildManifest` and `WorkerUpload` from `@astrale-os/adapter-cloudflare/build`, then computes
+its digest with `buildDigest` from `@astrale-os/sdk/deployment/build/manifest`. Modules retain
+their uploaded names and an asset `/<path>` becomes the file `assets/<path>`. The host binds that
+digest as `ASTRALE_BUILD_DIGEST` and uploads those exact bytes without bundling them again.
+The bundler version names this layout, not a package release.
+
+## Material for a custom Worker entrypoint
+
+Workers with provider-specific routes or environment initialization can reuse the adapter's
+material emission without adopting the entire generated entrypoint:
+
+```ts
+import { generateBuildMaterialModule } from '@astrale-os/adapter-cloudflare/build'
+import { writeFile } from 'node:fs/promises'
+
+// build is an admitted Build returned by compile(domain).
+await writeFile('src/build-material.gen.ts', generateBuildMaterialModule(build))
+```
+
+The generated TypeScript module exports `loadBuildMaterial()`. Call it from the
+`load` callback of `generatedCloudflareWorkerEntry` alongside the Domain's Runtime.
+That callback loads deterministic local modules once per entrypoint. Concurrent execution and
+`prepare()` calls share the same result, including a rejection; subsequent calls do not retry it.
+A newly constructed entrypoint starts independently. Keep remote preparation that may recover
+from transient failures in its own lifecycle, rather than putting it in `load`.
+Such an entrypoint states its execution settings (`invocationTimeoutMs`, `maximumRequestBytes`,
+`tokenExchange`, `routeSubrequest`) in its configuration, or reads them from its
+deployment bindings with `settings: deploymentSettings`; one Worker never takes both.
+It constructs the same verified, deduplicated material as the adapter's generated Service;
+allocation is deferred until the factory is called and the SDK deep-freezes it before use.
+The generated file needs only a type import from the SDK. Keep its compiler and runtime SDK
+versions aligned, and regenerate it when either the Domain or that SDK version changes.
+
+Such an entrypoint can keep the same fast frontend path by answering from
+`cloudflareFrontDoor()` (`@astrale-os/adapter-cloudflare/worker/front`, which reaches no SDK
+runtime module) before importing its Service, and calling that Service's `prepare()` through
+`waitUntil` when the front door served a frontend file.

package/dist/adapter.d.ts

@@ -0,0 +1,11 @@
+import type { Deployment } from '@astrale-os/sdk/deployment';
+import type { Adapter } from '@astrale-os/sdk/deployment/adapter';
+import type { NamespaceDependencies } from './namespace/index.js';
+import type { CloudflareParams } from './params.js';
+export type { NamespaceDependencies } from './namespace/index.js';
+export interface CloudflareDependencies {
+    readonly namespace: NamespaceDependencies;
+}
+/** Deploy each release as one immutable deployment in a Cloudflare dispatch namespace. */
+export declare function cloudflare(parameters: CloudflareParams): Deployment<CloudflareParams, Adapter<CloudflareParams>>;
+export declare function cloudflareWithDependencies(parameters: CloudflareParams, dependencies: CloudflareDependencies): Deployment<CloudflareParams, Adapter<CloudflareParams>>;

package/dist/adapter.js

@@ -0,0 +1,54 @@
+import { defineAdapter, defineDeployment } from '@astrale-os/sdk/deployment/adapter';
+import { createRequire } from 'node:module';
+import { cloudflareWorkerBundler } from './build/bundler.js';
+import { workerSettings } from './build/configuration.js';
+import { createSigningIdentity } from './hosting/identity.js';
+import { configureNamespace, deployNamespaceRelease, listNamespaceDeployments, hostingCommands, namespaceCoordinates, placeNamespace, } from './namespace/index.js';
+const packageVersion = createRequire(import.meta.url)('../package.json')
+    .version;
+/** Deploy each release as one immutable deployment in a Cloudflare dispatch namespace. */
+export function cloudflare(parameters) {
+    return cloudflareWithDependencies(parameters, { namespace: platformNamespaceDependencies() });
+}
+export function cloudflareWithDependencies(parameters, dependencies) {
+    const namespace = dependencies.namespace;
+    const adapter = defineAdapter({
+        name: 'cloudflare',
+        version: packageVersion,
+        bundler: cloudflareWorkerBundler,
+        admit: admitCloudflare,
+        configure: configureNamespace,
+        placement: async (parameters) => placeNamespace(parameters),
+        deployRelease: (parameters, context) => deployNamespaceRelease(parameters, context, namespace),
+        list: (parameters, context) => listNamespaceDeployments(parameters, context, namespace),
+        commands: hostingCommands(namespace),
+        secretsFile: (parameters) => parameters.secrets,
+    });
+    return defineDeployment(adapter, parameters);
+}
+/** Validate the deployment contract when the Project loads, before any build or provider effect. */
+function admitCloudflare(parameters) {
+    const allowed = [
+        'namespace',
+        'secrets',
+        'vars',
+        'maximumRequestBytes',
+        'invocationTimeoutMs',
+        'tokenExchange',
+        'durable',
+        'wrangler',
+        'router',
+    ];
+    if (Reflect.ownKeys(parameters).some((key) => !allowed.includes(key))) {
+        throw new TypeError('Cloudflare deployment parameters contain unknown fields.');
+    }
+    namespaceCoordinates(parameters);
+    workerSettings(parameters);
+}
+function platformNamespaceDependencies() {
+    return Object.freeze({
+        fetch: (input, init) => fetch(input, init),
+        environment: process.env,
+        createSigningIdentity,
+    });
+}

package/dist/build/bundle/admit.d.ts

@@ -0,0 +1,3 @@
+export declare function admitWorkerBundle(path: string): Promise<void>;
+/** Admit the separately emitted engine's actual platform exports, including its compiled WASM. */
+export declare function admitDurableEngineBundle(path: string): Promise<void>;

package/dist/build/bundle/admit.js

@@ -0,0 +1,46 @@
+import * as nodeModule from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { compiledWasmLoader, compiledWasmSource } from './compiled-wasm-loader.js';
+let compiledWasm = false;
+/**
+ * Import a WebAssembly module as Workers do for `CompiledWasm`: its default export is the compiled
+ * `WebAssembly.Module`, instantiated by the importing code. The CLI admits bundles under Bun; Node
+ * serves programmatic builds.
+ */
+function admitCompiledWasm() {
+    if (compiledWasm)
+        return;
+    if (process.versions.bun !== undefined) {
+        ;
+        Reflect.get(globalThis, 'Bun').plugin({
+            name: 'astrale-compiled-wasm',
+            setup(build) {
+                build.onLoad({ filter: /\.wasm$/ }, ({ path }) => ({
+                    loader: 'js',
+                    contents: compiledWasmSource(JSON.stringify(path)),
+                }));
+            },
+        });
+        compiledWasm = true;
+        return;
+    }
+    nodeModule.register(compiledWasmLoader);
+    compiledWasm = true;
+}
+export async function admitWorkerBundle(path) {
+    admitCompiledWasm();
+    const loaded = (await import(`${pathToFileURL(path).href}?admit=${Date.now()}`));
+    if (loaded.default === null ||
+        typeof loaded.default !== 'object' ||
+        typeof Reflect.get(loaded.default, 'fetch') !== 'function') {
+        throw new TypeError('Generated Worker bundle does not export a Fetch handler.');
+    }
+}
+/** Admit the separately emitted engine's actual platform exports, including its compiled WASM. */
+export async function admitDurableEngineBundle(path) {
+    admitCompiledWasm();
+    const engine = (await import(`${pathToFileURL(path).href}?admit=${Date.now()}`));
+    if (['createEndpointHandler', 'workflow', 'TerminalError', 'CancelledError'].some((key) => typeof engine[key] !== 'function')) {
+        throw new TypeError('Generated durable engine bundle does not export the platform Fetch entrypoint.');
+    }
+}

package/dist/build/bundle/compiled-wasm-loader.d.ts

@@ -0,0 +1,8 @@
+/** Workers expose CompiledWasm imports as modules, rather than instantiated exports. */
+export declare function compiledWasmSource(file: string): string;
+/**
+ * Async hooks run in a separate Node thread. A self-contained ESM hook admits both emitted JS and
+ * source builds under tsx without requiring that thread to resolve or transpile our source files.
+ * The emitted import source is shared with Bun.
+ */
+export declare const compiledWasmLoader: string;

package/dist/build/bundle/compiled-wasm-loader.js

@@ -0,0 +1,21 @@
+const SOURCE_PREFIX = "import { readFileSync } from 'node:fs'\nexport default new WebAssembly.Module(readFileSync(";
+const SOURCE_SUFFIX = '))\n';
+/** Workers expose CompiledWasm imports as modules, rather than instantiated exports. */
+export function compiledWasmSource(file) {
+    return `${SOURCE_PREFIX}${file}${SOURCE_SUFFIX}`;
+}
+/**
+ * Async hooks run in a separate Node thread. A self-contained ESM hook admits both emitted JS and
+ * source builds under tsx without requiring that thread to resolve or transpile our source files.
+ * The emitted import source is shared with Bun.
+ */
+export const compiledWasmLoader = `data:text/javascript,${encodeURIComponent(`
+export function load(url, context, nextLoad) {
+  if (!url.startsWith('file:') || !url.endsWith('.wasm')) return nextLoad(url, context);
+  return {
+    format: 'module',
+    shortCircuit: true,
+    source: ${JSON.stringify(SOURCE_PREFIX)} + 'new URL(' + JSON.stringify(url) + ')' + ${JSON.stringify(SOURCE_SUFFIX)},
+  };
+}
+`)}`;

package/dist/build/bundler.d.ts

@@ -0,0 +1,21 @@
+import type { Bundle, BundleContext, Bundler } from '@astrale-os/sdk/deployment/adapter';
+import type { frontend as frontendBuild } from '@astrale-os/sdk/deployment/build';
+import type { ReleaseModule } from './worker/execution.prepare.js';
+/**
+ * Environment-free bytes of one generated Worker: its entry, the modules it loads (the execution
+ * Service, the deferred workflow engine and their WASM) and its frontend.
+ */
+export interface WorkerBytes {
+    readonly entry: Uint8Array;
+    readonly modules: readonly ReleaseModule[];
+    readonly frontend: readonly frontendBuild.FrontendFile[];
+}
+/**
+ * Bundles every generated Cloudflare Worker, for adapter-cloudflare and adapter-astrale alike. It
+ * reads no Environment: settings, address, issuer and key are bound at deploy.
+ */
+export declare const cloudflareWorkerBundler: Bundler;
+/** Bundle the Worker modules and build the frontend they serve, in one scratch directory. */
+export declare function bundleWorker(context: BundleContext): Promise<WorkerBytes>;
+/** Read back the Worker bytes of a Bundle this bundler produced for the same Build. */
+export declare function bundledWorker(bundle: Bundle, build: Bundle['build']): WorkerBytes;

package/dist/build/bundler.js

@@ -0,0 +1,96 @@
+import { mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CLOUDFLARE_WORKER_BUNDLER, workerAssetFile } from '../release/build.js';
+import { frontendFiles } from './frontend/files.js';
+import { frontendRevision } from './frontend/revision.js';
+import { prepareExecution, RELEASE_ENTRY, RELEASE_SERVICE } from './worker/execution.prepare.js';
+/** Worker modules live beside the entry; WASM is the only non-ESM kind preparation emits. */
+const MODULE_DIRECTORY = 'bundle/';
+/**
+ * Bundles every generated Cloudflare Worker, for adapter-cloudflare and adapter-astrale alike. It
+ * reads no Environment: settings, address, issuer and key are bound at deploy.
+ */
+export const cloudflareWorkerBundler = Object.freeze({
+    id: CLOUDFLARE_WORKER_BUNDLER.id,
+    version: CLOUDFLARE_WORKER_BUNDLER.version,
+    async bundle(context) {
+        const worker = await bundleWorker(context);
+        return Object.freeze({
+            entrypoint: RELEASE_ENTRY,
+            files: Object.freeze([
+                { path: RELEASE_ENTRY, content: worker.entry },
+                ...worker.modules.map(({ path, content }) => ({ path, content })),
+                ...worker.frontend.map((file) => ({
+                    path: workerAssetFile(`/${file.path}`),
+                    content: file.bytes(),
+                })),
+            ]),
+        });
+    },
+});
+/** Bundle the Worker modules and build the frontend they serve, in one scratch directory. */
+export async function bundleWorker(context) {
+    const stateDirectory = join(context.projectDir, '.astrale');
+    await mkdir(stateDirectory, { recursive: true });
+    const directory = await mkdtemp(join(stateDirectory, 'prepare-'));
+    try {
+        // `frontend` is the served file list; `addressed` rides alongside it into the Worker, where it
+        // decides which of those files a browser may retain.
+        const { files: frontend, addressed } = await frontendFiles({
+            frontend: context.build.frontend,
+            projectDir: context.projectDir,
+            output: join(directory, 'frontend'),
+            recordSource: context.recordSource,
+            signal: context.signal,
+        });
+        const modules = await prepareExecution({
+            context,
+            directory,
+            ...(frontend.length === 0 ? {} : { frontendRevision: frontendRevision(frontend) }),
+            ...(addressed.length === 0 ? {} : { frontendAddressed: addressed }),
+        });
+        return Object.freeze({ entry: modules.entry, modules: modules.modules, frontend });
+    }
+    finally {
+        await rm(directory, { recursive: true, force: true });
+    }
+}
+/** Read back the Worker bytes of a Bundle this bundler produced for the same Build. */
+export function bundledWorker(bundle, build) {
+    const { id, version } = bundle.manifest.bundler;
+    if (bundle.build !== build ||
+        id !== CLOUDFLARE_WORKER_BUNDLER.id ||
+        version !== CLOUDFLARE_WORKER_BUNDLER.version ||
+        bundle.entrypoint !== RELEASE_ENTRY) {
+        throw new TypeError('Cloudflare preparation requires the Bundle of its Worker bundler.');
+    }
+    let entry;
+    const modules = [];
+    const frontend = [];
+    for (const file of bundle.files) {
+        if (file.path === RELEASE_ENTRY)
+            entry = file.bytes();
+        else if (file.path.startsWith(MODULE_DIRECTORY) && /\.(?:mjs|wasm)$/u.test(file.path)) {
+            modules.push(Object.freeze({
+                path: file.path,
+                kind: file.path.endsWith('.wasm') ? 'wasm' : 'esm',
+                content: file.bytes(),
+            }));
+        }
+        else if (file.path.startsWith('assets/')) {
+            const content = file.bytes();
+            frontend.push(Object.freeze({ path: file.path.slice('assets/'.length), bytes: () => content.slice() }));
+        }
+        else {
+            throw new TypeError(`Cloudflare Worker Bundle file ${file.path} is not a Worker file.`);
+        }
+    }
+    if (entry === undefined || !modules.some((module) => module.path === RELEASE_SERVICE)) {
+        throw new TypeError('Cloudflare Worker Bundle lacks its execution modules.');
+    }
+    return Object.freeze({
+        entry,
+        modules: Object.freeze(modules),
+        frontend: Object.freeze(frontend),
+    });
+}

package/dist/build/closure.d.ts

@@ -0,0 +1,2 @@
+/** Prove emitted Worker reachability excludes authoring, compilation, and broad Core Schema owners. */
+export declare function assertRuntimeClosure(metafilePath: string): Promise<void>;

package/dist/build/closure.js

@@ -0,0 +1,22 @@
+import { readWranglerMetafile } from './metafile.js';
+const FORBIDDEN_RUNTIME_INPUTS = [
+    '/v1/builder/',
+    '/v1/compiled/compiler/',
+    '/node_modules/ajv/',
+    '/node_modules/re2js/',
+    '/kernel-core/domain/',
+    '/core/domain/',
+    '/kernel-core/schema/index.',
+    '/core/schema/index.',
+];
+/** Prove emitted Worker reachability excludes authoring, compilation, and broad Core Schema owners. */
+export async function assertRuntimeClosure(metafilePath) {
+    const metafile = await readWranglerMetafile(metafilePath);
+    const forbidden = Object.keys(metafile.inputs).filter((input) => {
+        const normalized = `/${input.replaceAll('\\', '/')}`.replace(/(\/node_modules\/@astrale-os\/kernel-[^/]+)\/dist\//gu, '$1/');
+        return FORBIDDEN_RUNTIME_INPUTS.some((fragment) => normalized.includes(fragment));
+    });
+    if (forbidden.length > 0) {
+        throw new Error(`Cloudflare Worker reaches build-side modules: ${forbidden.sort().join(', ')}.`);
+    }
+}

package/dist/build/codegen/execution.d.ts

@@ -0,0 +1,3 @@
+export { generateExecutionEntry } from '../worker/codegen/entry.js';
+export { generateExecutionService } from '../worker/codegen/service.js';
+export type { ExecutionCodegenOptions } from '../worker/codegen/service.js';

package/dist/build/codegen/execution.js

@@ -0,0 +1,2 @@
+export { generateExecutionEntry } from '../worker/codegen/entry.js';
+export { generateExecutionService } from '../worker/codegen/service.js';

package/dist/build/codegen/merge.d.ts

@@ -17,4 +17,3 @@
  * the caller (`generateWranglerConfig`), not here — this stays a generic merge.
  */
 export declare function deepMergeConfig(base: Record<string, unknown>, overlay: Record<string, unknown>): Record<string, unknown>;
-//# sourceMappingURL=merge.d.ts.map

package/dist/build/codegen/merge.js

@@ -88,4 +88,3 @@ function isPlainObject(v) {
 function isPrimitive(v) {
     return v === null || (typeof v !== 'object' && typeof v !== 'function');
 }
-//# sourceMappingURL=merge.js.map

package/dist/build/codegen/wrangler.d.ts

@@ -13,22 +13,32 @@
  */
 export interface WranglerCodegenOptions {
     workerName: string;
+    /** Provider-ready entrypoint relative to the generated config. */
+    main?: string;
     /** Full custom hostname for a routed deploy (e.g. 'crm.acme.dev'). */
     route?: string;
     /** Exact materialized local frontend; absence means no ASSETS binding. */
     frontend?: {
         readonly directory: string;
-        readonly routes: readonly string[];
-        readonly dev: boolean;
     };
     /** Plain (non-secret) vars to bake in. */
     vars?: Record<string, string>;
+    /** Secret binding names required by generated Worker code. */
+    secretBindings?: readonly string[];
+    /** Modules retained outside the startup entry and loaded on demand. */
+    modules?: {
+        readonly baseDir: string;
+        readonly rules: readonly {
+            readonly type: 'ESModule' | 'CompiledWasm' | 'Text' | 'Data';
+            readonly globs: readonly string[];
+        }[];
+    };
     /** Add the SELF service binding (autobinding). */
     selfBinding: boolean;
     /**
      * Add a service binding to a router Worker for instance-host subrequest
-     * routing (see `CloudflareParams.router`). Pairs with the worker
-     * entry's `routeSubrequest`.
+     * routing (see `CloudflareParams.router`). Pairs with the router rule bound
+     * in `ASTRALE_SETTINGS`.
      */
     router?: {
         binding: string;
@@ -39,9 +49,25 @@ export interface WranglerCodegenOptions {
      * hatch for extra bindings (KV, R2, D1, queues, service bindings, extra
      * `compatibility_flags`, cron `triggers`, …). Arrays concat; new keys are
      * added as-is. The adapter-owned keys `name`, `main`, `assets`, `routes` are
-     * rejected (throws) — use `workerName` / `route` instead.
+     * rejected (throws) — use `workerName` / `route` instead — and so are the keys
+     * and compatibility flags Wrangler's bundler reads.
      */
     wrangler?: Record<string, unknown>;
 }
+/**
+ * The Workers runtime every generated Worker runs on, wherever it is deployed: its compatibility
+ * date, kept on the runtime baseline qualified with Wrangler 4.123.0, and its compatibility flags.
+ * Domain execution calls its Kernel through the invocation's public issuer, so Cloudflare must route
+ * same-zone callbacks through the public front door instead of bypassing Worker routes
+ * (`global_fetch_strictly_public`). An immutable deployment freezes it into its configuration.
+ */
+export declare const GENERATED_WORKER_RUNTIME: Readonly<{
+    compatibilityDate: "2026-08-11";
+    compatibilityFlags: readonly string[];
+}>;
 export declare function generateWranglerConfig(opts: WranglerCodegenOptions): string;
-//# sourceMappingURL=wrangler.d.ts.map
+/**
+ * Whether a compatibility flag shapes the bundle (Wrangler's bundler reads it), so that no
+ * Environment may add it: bundling takes no Environment.
+ */
+export declare function isBundlingCompatibilityFlag(flag: string): boolean;