@lunora/codegen 1.0.0-alpha.31 → 1.0.0-alpha.32

package/dist/index.d.mts

@@ -287,6 +287,18 @@ interface IdentityIR {
   exportName: string;
 }
 /**
+* The single `defineEnv({...})` contract discovered in `lunora/env.ts`. Like
+* {@link IdentityIR}, only the export binding is lifted — the emitted
+* `_generated/server.ts` recovers the validated shape from the declaration
+* itself (`ReturnType` over the accessor's `typeof`), and the generated ShardDO
+* applies the same accessor to the worker `env` at ctx-build time to populate
+* `ctx.env`. Exactly one per app; absent ⇒ generated output is byte-identical.
+*/
+interface EnvIR {
+  /** Export binding name — the namespace member `_generated/server.ts` reads via `typeof`. */
+  exportName: string;
+}
+/**
 * A `defineMutator({...})` declaration discovered in `lunora/mutators.ts`
 * (local-first sync engine, Phase 7). The emitted registry registers the
 * authoritative `server` impl into the DO's `LUNORA_FUNCTIONS` table (so
@@ -1851,6 +1863,13 @@ declare const emitCollections: (shapes: ReadonlyArray<ShapeIR>, hasDatabase: boo
 interface EmitServerOptions {
   containers?: ReadonlyArray<ContainerIR>;
   /**
+  * The single `defineEnv(...)` contract declared in `lunora/env.ts`. When
+  * present, `ctx.env` is typed as the validated `InferEnv` shape (recovered
+  * via `ReturnType` over the accessor's `typeof`). `undefined` leaves `ctx.env`
+  * the base optional binding record — byte-identical to today.
+  */
+  env?: EnvIR;
+  /**
   * A `lunora/` source reads `ctx.access` — wires the verified Cloudflare Access
   * facade (`@lunora/cloudflare-access/context`) onto every ctx. Distinct from
   * `emitApp`'s `hasAccess` (which gates the worker's `.access()` resolveIdentity
@@ -1894,6 +1913,7 @@ interface EmitServerOptions {
 }
 declare const emitServer: ({
   containers,
+  env,
   hasAccessFacade,
   hasAi,
   hasAnalytics,
@@ -1951,6 +1971,8 @@ declare const emitWorkflows: (workflows: ReadonlyArray<WorkflowIR>) => string;
 interface EmitShardOptions {
   advisories?: ReadonlyArray<Finding>;
   containers?: ReadonlyArray<ContainerIR>;
+  /** The single `defineEnv(...)` contract declared in `lunora/env.ts` — applies the accessor to the worker `env` to populate `ctx.env`. */
+  env?: EnvIR;
   /** Statically-discovered `ctx.flags.&lt;type>("key")` reads — the studio Flags page + reactive evaluation iterate these. */
   flagKeys?: ReadonlyArray<{
     key: string;
@@ -1994,6 +2016,7 @@ interface EmitShardOptions {
 declare const emitShard: ({
   advisories,
   containers,
+  env,
   flagKeys,
   hasAccessFacade,
   hasAi,

package/dist/index.d.ts

@@ -287,6 +287,18 @@ interface IdentityIR {
   exportName: string;
 }
 /**
+* The single `defineEnv({...})` contract discovered in `lunora/env.ts`. Like
+* {@link IdentityIR}, only the export binding is lifted — the emitted
+* `_generated/server.ts` recovers the validated shape from the declaration
+* itself (`ReturnType` over the accessor's `typeof`), and the generated ShardDO
+* applies the same accessor to the worker `env` at ctx-build time to populate
+* `ctx.env`. Exactly one per app; absent ⇒ generated output is byte-identical.
+*/
+interface EnvIR {
+  /** Export binding name — the namespace member `_generated/server.ts` reads via `typeof`. */
+  exportName: string;
+}
+/**
 * A `defineMutator({...})` declaration discovered in `lunora/mutators.ts`
 * (local-first sync engine, Phase 7). The emitted registry registers the
 * authoritative `server` impl into the DO's `LUNORA_FUNCTIONS` table (so
@@ -1851,6 +1863,13 @@ declare const emitCollections: (shapes: ReadonlyArray<ShapeIR>, hasDatabase: boo
 interface EmitServerOptions {
   containers?: ReadonlyArray<ContainerIR>;
   /**
+  * The single `defineEnv(...)` contract declared in `lunora/env.ts`. When
+  * present, `ctx.env` is typed as the validated `InferEnv` shape (recovered
+  * via `ReturnType` over the accessor's `typeof`). `undefined` leaves `ctx.env`
+  * the base optional binding record — byte-identical to today.
+  */
+  env?: EnvIR;
+  /**
   * A `lunora/` source reads `ctx.access` — wires the verified Cloudflare Access
   * facade (`@lunora/cloudflare-access/context`) onto every ctx. Distinct from
   * `emitApp`'s `hasAccess` (which gates the worker's `.access()` resolveIdentity
@@ -1894,6 +1913,7 @@ interface EmitServerOptions {
 }
 declare const emitServer: ({
   containers,
+  env,
   hasAccessFacade,
   hasAi,
   hasAnalytics,
@@ -1951,6 +1971,8 @@ declare const emitWorkflows: (workflows: ReadonlyArray<WorkflowIR>) => string;
 interface EmitShardOptions {
   advisories?: ReadonlyArray<Finding>;
   containers?: ReadonlyArray<ContainerIR>;
+  /** The single `defineEnv(...)` contract declared in `lunora/env.ts` — applies the accessor to the worker `env` to populate `ctx.env`. */
+  env?: EnvIR;
   /** Statically-discovered `ctx.flags.&lt;type>("key")` reads — the studio Flags page + reactive evaluation iterate these. */
   flagKeys?: ReadonlyArray<{
     key: string;
@@ -1994,6 +2016,7 @@ interface EmitShardOptions {
 declare const emitShard: ({
   advisories,
   containers,
+  env,
   flagKeys,
   hasAccessFacade,
   hasAi,

package/dist/index.mjs

@@ -19,11 +19,11 @@ export { default as discoverSchema } from './packem_shared/discoverSchema-CeXJWV
 export { SHAPES_FILENAME, discoverShapes } from './packem_shared/SHAPES_FILENAME-DOhPGi-6.mjs';
 export { default as discoverStorageRulesMetadata } from './packem_shared/discoverStorageRulesMetadata-CFHByjIl.mjs';
 export { WORKFLOWS_FILENAME, discoverWorkflows } from './packem_shared/WORKFLOWS_FILENAME-CCC_42o3.mjs';
-export { GENERATED_HEADER, emitApi, emitCollections, emitContainers, emitCrons, emitDataModel, emitDrizzleSchema, emitFunctions, emitServer, emitShard, emitVectors, emitWorkflows, emitWranglerCronTriggers } from './packem_shared/GENERATED_HEADER-f6nMvllu.mjs';
-export { emitApp } from './packem_shared/emitApp-BUCrHOeI.mjs';
-export { buildOpenApiDocument, emitOpenApi, emitOpenApiModule } from './packem_shared/buildOpenApiDocument-AgKWmlry.mjs';
-export { OPENRPC_VERSION, buildOpenRpcDocument, emitOpenRpc, emitOpenRpcModule } from './packem_shared/OPENRPC_VERSION-u5SqDDGk.mjs';
-export { SCHEMA_SNAPSHOT_FILENAME, createCodegenProject, refreshCodegenProject, runCodegen } from './packem_shared/SCHEMA_SNAPSHOT_FILENAME-Ca-TlVEc.mjs';
+export { G as GENERATED_HEADER, e as emitApi, a as emitCollections, b as emitContainers, c as emitCrons, d as emitDataModel, f as emitDrizzleSchema, g as emitFunctions, h as emitServer, i as emitShard, j as emitVectors, k as emitWorkflows, l as emitWranglerCronTriggers } from './packem_shared/emit-CBwEvCXQ.mjs';
+export { emitApp } from './packem_shared/emitApp-nQ2oC-8G.mjs';
+export { buildOpenApiDocument, emitOpenApi, emitOpenApiModule } from './packem_shared/buildOpenApiDocument-bp1pYSV6.mjs';
+export { OPENRPC_VERSION, buildOpenRpcDocument, emitOpenRpc, emitOpenRpcModule } from './packem_shared/OPENRPC_VERSION-4YIeMkOI.mjs';
+export { SCHEMA_SNAPSHOT_FILENAME, createCodegenProject, refreshCodegenProject, runCodegen } from './packem_shared/SCHEMA_SNAPSHOT_FILENAME-OBXQBJV0.mjs';
 export { SCHEMA_SNAPSHOT_VERSION, SchemaSnapshotParseError, buildSchemaSnapshot, diffSchemaSnapshots, evaluateSchemaDrift, parseSchemaSnapshot, serializeSchemaSnapshot } from './packem_shared/SCHEMA_SNAPSHOT_VERSION-D0ARY6rL.mjs';
 export { schemaFromIr } from './packem_shared/schemaFromIr-DTYsLBaA.mjs';
 export { LUNORA_ERROR_CODES, validatorIrToJsonSchema } from './packem_shared/LUNORA_ERROR_CODES-CySpQPD3.mjs';

package/dist/packem_shared/GENERATED_HEADER-CLwPlCQe.mjs

@@ -0,0 +1,3 @@
+import '@lunora/errors';
+export { G as GENERATED_HEADER, m as buildStorageColumns, e as emitApi, a as emitCollections, b as emitContainers, c as emitCrons, d as emitDataModel, f as emitDrizzleSchema, g as emitFunctions, n as emitQueues, o as emitSeed, h as emitServer, i as emitShard, j as emitVectors, k as emitWorkflows, l as emitWranglerCronTriggers } from './emit-CBwEvCXQ.mjs';
+import './paths-BRd6JHuF.mjs';

package/dist/packem_shared/{OPENRPC_VERSION-u5SqDDGk.mjs → OPENRPC_VERSION-4YIeMkOI.mjs}

@@ -1,4 +1,4 @@
-import { GENERATED_HEADER } from './GENERATED_HEADER-f6nMvllu.mjs';
+import { G as GENERATED_HEADER } from './emit-CBwEvCXQ.mjs';
 import { s as sanitizeNamespace } from './paths-BRd6JHuF.mjs';
 import { argsObjectSchema, LUNORA_ERROR_CODES } from './LUNORA_ERROR_CODES-CySpQPD3.mjs';
 

package/dist/packem_shared/{SCHEMA_SNAPSHOT_FILENAME-Ca-TlVEc.mjs → SCHEMA_SNAPSHOT_FILENAME-OBXQBJV0.mjs}

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { performance } from 'node:perf_hooks';
 import { LunoraError } from '@lunora/errors';
@@ -8,9 +8,10 @@ import { listLunoraSourceFiles, lunoraRelativePath, classifyProcedureCall, inlin
 import discoverAuthApiCalls from './discoverAuthApiCalls-URDoTADN.mjs';
 import { discoverContainers } from './CONTAINERS_FILENAME-DjpXMqhp.mjs';
 import discoverCrons from './discoverCrons-DdZOeroL.mjs';
+import { diagnosticAt } from './CodegenDiagnosticError-DyQ5FwkM.mjs';
+import { C as CAPABILITIES, m as buildStorageColumns, d as emitDataModel, e as emitApi, h as emitServer, g as emitFunctions, i as emitShard, a as emitCollections, b as emitContainers, k as emitWorkflows, n as emitQueues, c as emitCrons, j as emitVectors, f as emitDrizzleSchema, o as emitSeed, l as emitWranglerCronTriggers } from './emit-CBwEvCXQ.mjs';
 import { discoverFlagKeys } from './FLAGS_FILENAME-BjpS5w08.mjs';
 import discoverHttpRoutes from './discoverHttpRoutes-CcwP-Rkr.mjs';
-import { diagnosticAt } from './CodegenDiagnosticError-DyQ5FwkM.mjs';
 import discoverInserts from './discoverInserts-BpFhM32L.mjs';
 import discoverMaskProcedures, { discoverMaskStrategies, discoverMaskMetadata } from './discoverMaskProcedures-DT-v8wvj.mjs';
 import discoverMigrations from './discoverMigrations-cG1idBVM.mjs';
@@ -26,10 +27,9 @@ import { discoverShapes } from './SHAPES_FILENAME-DOhPGi-6.mjs';
 import discoverStorageRulesMetadata from './discoverStorageRulesMetadata-CFHByjIl.mjs';
 import { e as enclosingExportName$2 } from './discover-ast-CT6BgBr4.mjs';
 import { discoverWorkflows } from './WORKFLOWS_FILENAME-CCC_42o3.mjs';
-import { buildStorageColumns, emitDataModel, emitApi, emitServer, emitFunctions, emitShard, emitCollections, emitContainers, emitWorkflows, emitQueues, emitCrons, emitVectors, emitDrizzleSchema, emitSeed, emitWranglerCronTriggers } from './GENERATED_HEADER-f6nMvllu.mjs';
-import { emitApp } from './emitApp-BUCrHOeI.mjs';
-import { buildOpenApiDocument, emitOpenApiModule } from './buildOpenApiDocument-AgKWmlry.mjs';
-import { buildOpenRpcDocument, emitOpenRpcModule } from './OPENRPC_VERSION-u5SqDDGk.mjs';
+import { emitApp } from './emitApp-nQ2oC-8G.mjs';
+import { buildOpenApiDocument, emitOpenApiModule } from './buildOpenApiDocument-bp1pYSV6.mjs';
+import { buildOpenRpcDocument, emitOpenRpcModule } from './OPENRPC_VERSION-4YIeMkOI.mjs';
 import { buildSchemaSnapshot, serializeSchemaSnapshot } from './SCHEMA_SNAPSHOT_VERSION-D0ARY6rL.mjs';
 
 const HTTP_VERBS$1 = /* @__PURE__ */ new Set(["delete", "get", "head", "options", "patch", "post", "put"]);
@@ -878,6 +878,89 @@ const discoverContainerOverrides = (project, lunoraDirectory) => {
   return rows;
 };
 
+const ENV_FILENAME = "env.ts";
+const ENV_MODULE_SPECIFIERS = /* @__PURE__ */ new Set(["@lunora/server", "lunorash/server"]);
+const isDefineEnv = (identifier) => {
+  const symbol = identifier.getSymbol();
+  if (!symbol) {
+    return identifier.getText() === "defineEnv";
+  }
+  for (const declaration of symbol.getDeclarations()) {
+    if (!Node.isImportSpecifier(declaration)) {
+      continue;
+    }
+    if (!ENV_MODULE_SPECIFIERS.has(declaration.getImportDeclaration().getModuleSpecifierValue())) {
+      return false;
+    }
+    return declaration.getNameNode().getText() === "defineEnv";
+  }
+  return false;
+};
+const isEnvNamespaceImport = (identifier) => {
+  const symbol = identifier.getSymbol();
+  if (!symbol) {
+    return false;
+  }
+  for (const declaration of symbol.getDeclarations()) {
+    if (!Node.isNamespaceImport(declaration)) {
+      continue;
+    }
+    const importDeclaration = declaration.getFirstAncestorByKind(SyntaxKind.ImportDeclaration);
+    return importDeclaration !== void 0 && ENV_MODULE_SPECIFIERS.has(importDeclaration.getModuleSpecifierValue());
+  }
+  return false;
+};
+const isDefineEnvCallee = (callee) => {
+  if (Node.isIdentifier(callee)) {
+    return isDefineEnv(callee);
+  }
+  if (Node.isPropertyAccessExpression(callee)) {
+    const object = callee.getExpression();
+    return callee.getName() === "defineEnv" && Node.isIdentifier(object) && isEnvNamespaceImport(object);
+  }
+  return false;
+};
+const environmentsFromSource = (source) => {
+  const environments = [];
+  for (const declaration of source.getVariableDeclarations()) {
+    if (!declaration.isExported()) {
+      continue;
+    }
+    const initializer = declaration.getInitializer();
+    if (initializer?.getKind() !== SyntaxKind.CallExpression) {
+      continue;
+    }
+    const callExpression = initializer;
+    if (!isDefineEnvCallee(callExpression.getExpression())) {
+      continue;
+    }
+    const nameNode = declaration.getNameNode();
+    if (!Node.isIdentifier(nameNode)) {
+      throw diagnosticAt(nameNode, "defineEnv exports must be plain named exports (no destructuring)");
+    }
+    environments.push({ exportName: nameNode.getText() });
+  }
+  return environments;
+};
+const discoverEnv = (project, lunoraDirectory) => {
+  const envPath = join(lunoraDirectory, ENV_FILENAME);
+  if (!existsSync(envPath)) {
+    return void 0;
+  }
+  const source = project.getSourceFile(envPath) ?? project.addSourceFileAtPath(envPath);
+  const environments = environmentsFromSource(source);
+  if (environments.length === 0) {
+    return void 0;
+  }
+  if (environments.length > 1) {
+    throw diagnosticAt(
+      source,
+      `lunora/env.ts declares ${environments.length.toString()} defineEnv() contracts (${environments.map((env) => env.exportName).join(", ")}); exactly one is allowed`
+    );
+  }
+  return environments[0];
+};
+
 const OPTIONS_ARGUMENT_INDEX$1 = /* @__PURE__ */ new Map([
   ["dbRateLimit", 2],
   ["rateLimit", 2],
@@ -932,35 +1015,6 @@ const discoverFailOpenGuards = (project, lunoraDirectory) => {
   return guards;
 };
 
-const PROBES = {
-  // The middleware (`accessContext()` / `accessRoles()`) imports the `/context`
-  // and `/roles` subpaths, NOT the bare `@lunora/cloudflare-access` specifier —
-  // so the per-procedure middleware never trips the global `ctx.access` wiring.
-  // A handler reading `ctx.access` is the signal that wires it onto every ctx.
-  access: { contextProperty: "access", moduleSpecifier: "@lunora/cloudflare-access" },
-  ai: { contextProperty: "ai", moduleSpecifier: "@lunora/ai" },
-  analytics: { contextProperty: "analytics", moduleSpecifier: "@lunora/bindings/analytics" },
-  browser: { contextProperty: "browser", moduleSpecifier: "@lunora/browser" },
-  // `lunora/containers.ts` imports `defineContainer` from `@lunora/container`,
-  // and handlers reach live instances via `ctx.containers` — either signals the
-  // app wires containers, so the studio should show the Containers page.
-  container: { contextProperty: "containers", moduleSpecifier: "@lunora/container" },
-  flags: { contextProperty: "flags", moduleSpecifier: "@lunora/flags" },
-  hyperdrive: { contextProperty: "sql", moduleSpecifier: "@lunora/hyperdrive" },
-  images: { contextProperty: "images", moduleSpecifier: "@lunora/bindings/images" },
-  kv: { contextProperty: "kv", moduleSpecifier: "@lunora/bindings/kv" },
-  mail: { moduleSpecifier: "@lunora/mail" },
-  payments: { contextProperty: "payments", moduleSpecifier: "@lunora/payment" },
-  // Pipelines is its own `@lunora/bindings/pipelines` subpath (distinct from
-  // `/analytics`), so a real import is a clean signal that won't be flipped by a
-  // plain analytics import; `ctx.pipelines` reads flip it too.
-  pipelines: { contextProperty: "pipelines", moduleSpecifier: "@lunora/bindings/pipelines" },
-  r2sql: { contextProperty: "r2sql", moduleSpecifier: "@lunora/bindings/r2sql" },
-  scheduler: { contextProperty: "scheduler", moduleSpecifier: "@lunora/scheduler" },
-  storage: { contextProperty: "storage", moduleSpecifier: "@lunora/storage" },
-  vectors: { contextProperty: "vectors", moduleSpecifier: "@lunora/bindings/vectors" },
-  workflows: { contextProperty: "workflows", moduleSpecifier: "@lunora/workflow" }
-};
 const contextPropertiesRead = (sourceFile) => {
   const reachesContext = (receiver) => Node.isIdentifier(receiver) && receiver.getText() === "ctx";
   const names = /* @__PURE__ */ new Set();
@@ -985,44 +1039,24 @@ const contextPropertiesRead = (sourceFile) => {
   return names;
 };
 const discoverFeatureUsage = (project, lunoraDirectory) => {
-  const usage = {
-    access: false,
-    ai: false,
-    analytics: false,
-    browser: false,
-    container: false,
-    flags: false,
-    hyperdrive: false,
-    images: false,
-    kv: false,
-    mail: false,
-    payments: false,
-    pipelines: false,
-    r2sql: false,
-    scheduler: false,
-    storage: false,
-    vectors: false,
-    workflows: false
-  };
-  const keys = Object.keys(PROBES);
+  const usage = Object.fromEntries(CAPABILITIES.map((capability) => [capability.key, false]));
   for (const filePath of listLunoraSourceFiles(lunoraDirectory)) {
     const sourceFile = project.getSourceFile(filePath) ?? project.addSourceFileAtPath(filePath);
     const importSpecifiers = new Set(sourceFile.getImportDeclarations().map((declaration) => declaration.getModuleSpecifierValue()));
     const contextProperties = contextPropertiesRead(sourceFile);
-    for (const key of keys) {
-      if (usage[key]) {
+    for (const capability of CAPABILITIES) {
+      if (usage[capability.key]) {
         continue;
       }
-      const probe = PROBES[key];
-      if (importSpecifiers.has(probe.moduleSpecifier)) {
-        usage[key] = true;
+      if (importSpecifiers.has(capability.moduleSpecifier)) {
+        usage[capability.key] = true;
         continue;
       }
-      if (probe.contextProperty !== void 0 && contextProperties.has(probe.contextProperty)) {
-        usage[key] = true;
+      if (capability.contextProperty !== void 0 && contextProperties.has(capability.contextProperty)) {
+        usage[capability.key] = true;
       }
     }
-    if (keys.every((key) => usage[key])) {
+    if (CAPABILITIES.every((capability) => usage[capability.key])) {
       break;
     }
   }
@@ -3134,9 +3168,11 @@ const writeIfChanged = (filePath, content) => {
   writeFileSync(filePath, content, "utf8");
 };
 const writeIfPresent = (filePath, content) => {
-  if (content !== "") {
-    writeIfChanged(filePath, content);
+  if (content === "") {
+    rmSync(filePath, { force: true });
+    return;
   }
+  writeIfChanged(filePath, content);
 };
 const readProjectVersion = (projectRoot) => {
   const manifestPath = join(projectRoot, "package.json");
@@ -3210,6 +3246,7 @@ const runCodegen = (options) => {
   const shapes = discoverShapes(project, lunoraDirectory);
   const mutators = discoverMutators(project, lunoraDirectory);
   const identity = discoverIdentity(project, lunoraDirectory);
+  const env = discoverEnv(project, lunoraDirectory);
   const workflows = discoverWorkflows(project, lunoraDirectory);
   const queues = discoverQueues(project, lunoraDirectory);
   const crons = discoverCrons(project, lunoraDirectory, workflows);
@@ -3296,6 +3333,7 @@ const runCodegen = (options) => {
   const apiContent = emitApi(functions, workflows, useUmbrella);
   const serverContent = emitServer({
     containers,
+    env,
     hasAccessFacade,
     hasAi,
     hasAnalytics,
@@ -3318,6 +3356,7 @@ const runCodegen = (options) => {
   const shardContent = emitShard({
     advisories,
     containers,
+    env,
     flagKeys,
     hasAccessFacade,
     hasAi,

package/dist/packem_shared/{buildOpenApiDocument-AgKWmlry.mjs → buildOpenApiDocument-bp1pYSV6.mjs}

@@ -1,4 +1,4 @@
-import { GENERATED_HEADER } from './GENERATED_HEADER-f6nMvllu.mjs';
+import { G as GENERATED_HEADER } from './emit-CBwEvCXQ.mjs';
 import { s as sanitizeNamespace } from './paths-BRd6JHuF.mjs';
 import { LUNORA_ERROR_CODES, objectSchema, argsObjectSchema, validatorIrToJsonSchema } from './LUNORA_ERROR_CODES-CySpQPD3.mjs';
 

package/dist/packem_shared/{GENERATED_HEADER-f6nMvllu.mjs → emit-CBwEvCXQ.mjs}

@@ -1,6 +1,170 @@
 import { LunoraError } from '@lunora/errors';
 import { s as sanitizeNamespace } from './paths-BRd6JHuF.mjs';
 
+const CAPABILITY_ROWS = [
+  // The middleware (`accessContext()` / `accessRoles()`) imports the `/context`
+  // and `/roles` subpaths, NOT the bare `@lunora/cloudflare-access` specifier —
+  // so the per-procedure middleware never trips the global `ctx.access` wiring.
+  // A handler reading `ctx.access` is the signal that wires it onto every ctx.
+  // `access` has a synchronous facade type, so its ctx field stays bespoke in
+  // `emit.ts` (no `serverCtxField` here).
+  { contextProperty: "access", key: "access", moduleSpecifier: "@lunora/cloudflare-access" },
+  {
+    appMethod: { configKey: "ai", doc: "Override the Workers AI binding backing `ctx.ai` (defaults to `env.AI`).", method: "ai" },
+    contextProperty: "ai",
+    key: "ai",
+    moduleSpecifier: "@lunora/ai"
+  },
+  {
+    appMethod: {
+      configKey: "analytics",
+      doc: "Override the Analytics Engine dataset backing `ctx.analytics` (defaults to `env.ANALYTICS`).",
+      method: "analytics"
+    },
+    contextProperty: "analytics",
+    key: "analytics",
+    moduleSpecifier: "@lunora/bindings/analytics",
+    // `ctx.analytics` — Analytics Engine write helper. EVERY ctx: a write-only,
+    // fire-and-forget side effect, not a determinism hazard for reads.
+    serverCtxField: {
+      field: `
+    /** Analytics Engine telemetry sink. Fire-and-forget and sampled; do not read it back in-handler. */
+    readonly analytics: import("@lunora/bindings/analytics").AnalyticsClient;`,
+      tier: "every"
+    }
+  },
+  {
+    appMethod: {
+      configKey: "browser",
+      doc: "Override the Browser Rendering binding backing `ctx.browser` (defaults to `env.BROWSER`).",
+      method: "browser"
+    },
+    contextProperty: "browser",
+    key: "browser",
+    moduleSpecifier: "@lunora/browser",
+    // `ctx.browser` — Browser Rendering. ActionCtx ONLY: non-deterministic network I/O.
+    serverCtxField: {
+      field: `
+    /** Browser Rendering (screenshots/PDF/scrape). Non-deterministic — available only in actions. */
+    readonly browser: import("@lunora/browser").Browser;`,
+      tier: "action"
+    }
+  },
+  // `lunora/containers.ts` imports `defineContainer` from `@lunora/container`,
+  // and handlers reach live instances via `ctx.containers` — either signals the
+  // app wires containers, so the studio should show the Containers page. The ctx
+  // field is a per-declaration emitter (kept bespoke), so no `serverCtxField`.
+  { contextProperty: "containers", key: "container", moduleSpecifier: "@lunora/container" },
+  // `ctx.flags` — OpenFeature. Umbrella-aware specifier + its own provider
+  // client, so both the ctx field and the shard fragment stay bespoke.
+  { contextProperty: "flags", key: "flags", moduleSpecifier: "@lunora/flags" },
+  {
+    appMethod: {
+      configKey: "sql",
+      doc: "Wire the Hyperdrive SQL client backing `ctx.sql` — build it with `createHyperdrive` + `fromPostgresJs`/`fromNodePg`/`fromMysql2`.",
+      method: "hyperdrive"
+    },
+    contextProperty: "sql",
+    key: "hyperdrive",
+    moduleSpecifier: "@lunora/hyperdrive",
+    // `ctx.sql` — Hyperdrive (external Postgres/MySQL). ActionCtx ONLY: external,
+    // non-deterministic I/O whose writes are invisible to Lunora live queries.
+    serverCtxField: {
+      field: `
+    /**
+     * External database access via Hyperdrive. Non-deterministic — available only in actions. Writes here are NOT tracked by Lunora live queries; subscriptions will not re-run on external DB changes.
+     */
+    readonly sql: import("@lunora/hyperdrive").SqlClient;`,
+      tier: "action"
+    }
+  },
+  {
+    appMethod: { configKey: "images", doc: "Override the Images binding backing `ctx.images` (defaults to `env.IMAGES`).", method: "images" },
+    contextProperty: "images",
+    key: "images",
+    moduleSpecifier: "@lunora/bindings/images",
+    // `ctx.images` — Cloudflare Images binding transforms. ActionCtx ONLY: non-deterministic compute/network I/O.
+    serverCtxField: {
+      field: `
+    /** Cloudflare Images transforms (resize/format/optimize). Non-deterministic — available only in actions. */
+    readonly images: import("@lunora/bindings/images").Images;`,
+      tier: "action"
+    }
+  },
+  {
+    appMethod: { configKey: "kv", doc: "Override the Workers KV binding backing `ctx.kv` (defaults to `env.KV`).", method: "kv" },
+    contextProperty: "kv",
+    key: "kv",
+    moduleSpecifier: "@lunora/bindings/kv",
+    // `ctx.kv` — Workers KV. Typed on EVERY ctx (a KV read is allowed in a
+    // deterministic read path the way `ctx.db` is; the binding is user-named).
+    serverCtxField: { field: `
+    readonly kv: import("@lunora/bindings/kv").Kv;`, tier: "every" }
+  },
+  // `mail` is import-only — no `ctx.mail` helper (mail is reached through its own
+  // client), so only a `@lunora/mail` import flips it.
+  { key: "mail", moduleSpecifier: "@lunora/mail" },
+  {
+    appMethod: { configKey: "payment", doc: "Wire the payment options backing `ctx.payments`.", method: "payment" },
+    contextProperty: "payments",
+    key: "payments",
+    moduleSpecifier: "@lunora/payment"
+  },
+  // Pipelines is its own `@lunora/bindings/pipelines` subpath (distinct from
+  // `/analytics`), so a real import is a clean signal that won't be flipped by a
+  // plain analytics import; `ctx.pipelines` reads flip it too.
+  {
+    contextProperty: "pipelines",
+    key: "pipelines",
+    moduleSpecifier: "@lunora/bindings/pipelines",
+    // `ctx.pipelines` — Pipelines (R2-backed) ingestion sink. ActionCtx ONLY
+    // (write-only fire-and-forget, but external I/O — kept off query/mutation).
+    serverCtxField: {
+      field: `
+    /** Pipelines ingestion sink (durable, R2-backed). Fire-and-forget and batched; do not read it back in-handler. */
+    readonly pipelines: import("@lunora/bindings/pipelines").PipelineClient;`,
+      tier: "action"
+    }
+  },
+  {
+    appMethod: {
+      configKey: "r2sql",
+      doc: "Wire the R2 SQL client backing `ctx.r2sql` — build it with `createR2Sql({ accountId, apiToken, bucket })` (defaults to env `R2_SQL_TOKEN` / `R2_SQL_ACCOUNT_ID` / `R2_SQL_BUCKET`).",
+      method: "r2sql"
+    },
+    contextProperty: "r2sql",
+    key: "r2sql",
+    moduleSpecifier: "@lunora/bindings/r2sql",
+    // `ctx.r2sql` — R2 SQL (serverless query engine over Apache Iceberg tables).
+    // ActionCtx ONLY: external REST I/O, non-deterministic, and non-reactive
+    // (reads are not tracked by Lunora live queries).
+    serverCtxField: {
+      field: `
+    /**
+     * R2 SQL over Apache Iceberg tables (window functions, DISTINCT, set operations). Non-deterministic — available only in actions. Reads here are NOT tracked by Lunora live queries.
+     */
+    readonly r2sql: import("@lunora/bindings/r2sql").R2SqlClient;`,
+      tier: "action"
+    }
+  },
+  { contextProperty: "scheduler", key: "scheduler", moduleSpecifier: "@lunora/scheduler" },
+  { contextProperty: "storage", key: "storage", moduleSpecifier: "@lunora/storage" },
+  {
+    appMethod: { configKey: "vectors", doc: "Wire the Vectorize index map backing `ctx.vectors`.", method: "vectors" },
+    contextProperty: "vectors",
+    key: "vectors",
+    moduleSpecifier: "@lunora/bindings/vectors"
+  },
+  { contextProperty: "workflows", key: "workflows", moduleSpecifier: "@lunora/workflow" }
+];
+const CAPABILITIES = CAPABILITY_ROWS;
+const SERVER_CTX_FIELDS = new Map(
+  CAPABILITIES.flatMap((capability) => capability.serverCtxField ? [[capability.key, capability.serverCtxField]] : [])
+);
+const APP_METHOD_CAPABILITIES = CAPABILITY_ROWS.flatMap(
+  (capability) => "appMethod" in capability ? [{ appMethod: capability.appMethod, key: capability.key }] : []
+);
+
 const LITERAL_VALUE_RE = /^(?:"[^"\\]*"|'[^'\\]*'|-?\d+(?:\.\d+)?|true|false|null)$/u;
 
 const PASS_THROUGH_KINDS = /* @__PURE__ */ new Set(["any", "bigint", "boolean", "date", "id", "null", "number", "storage", "string", "timestamp"]);
@@ -755,6 +919,7 @@ const buildStorageBucketNames = (schema, ruleBuckets = []) => {
 };
 const emitServer = ({
   containers = [],
+  env,
   hasAccessFacade = false,
   hasAi = false,
   hasAnalytics = false,
@@ -827,36 +992,20 @@ ${envBindingFields}` : ""}
 
 /** Alias for {@link CloudflareBindings} — the typed shape of \`env\`. */
 export type Env = CloudflareBindings;`;
-  const kvContextField = hasKv ? `
-    readonly kv: import("@lunora/bindings/kv").Kv;` : "";
+  const serverCapabilityField = (key, enabled) => enabled ? SERVER_CTX_FIELDS.get(key)?.field ?? "" : "";
+  const kvContextField = serverCapabilityField("kv", hasKv);
+  const analyticsContextField = serverCapabilityField("analytics", hasAnalytics);
+  const hyperdriveActionField = serverCapabilityField("hyperdrive", hasHyperdrive);
+  const browserActionField = serverCapabilityField("browser", hasBrowser);
+  const imagesActionField = serverCapabilityField("images", hasImages);
+  const pipelinesActionField = serverCapabilityField("pipelines", hasPipelines);
+  const r2sqlActionField = serverCapabilityField("r2sql", hasR2sql);
   const accessContextField = hasAccessFacade ? `
     /** Verified Cloudflare Access identity — a synchronous facade over the resolved claims (email / groups / hasGroup / claims). Anonymous when no Access token is present. */
     readonly access: import("@lunora/cloudflare-access/context").AccessFacade;` : "";
   const flagsContextField = hasFlags ? `
     /** Feature-flag evaluation (OpenFeature). Reads are memoized per request; evaluations never throw — a provider error resolves to the supplied default. */
     readonly flags: import("${base.flags}").LunoraFlags;` : "";
-  const hyperdriveActionField = hasHyperdrive ? `
-    /**
-     * External database access via Hyperdrive. Non-deterministic — available only in actions. Writes here are NOT tracked by Lunora live queries; subscriptions will not re-run on external DB changes.
-     */
-    readonly sql: import("@lunora/hyperdrive").SqlClient;` : "";
-  const browserActionField = hasBrowser ? `
-    /** Browser Rendering (screenshots/PDF/scrape). Non-deterministic — available only in actions. */
-    readonly browser: import("@lunora/browser").Browser;` : "";
-  const imagesActionField = hasImages ? `
-    /** Cloudflare Images transforms (resize/format/optimize). Non-deterministic — available only in actions. */
-    readonly images: import("@lunora/bindings/images").Images;` : "";
-  const analyticsContextField = hasAnalytics ? `
-    /** Analytics Engine telemetry sink. Fire-and-forget and sampled; do not read it back in-handler. */
-    readonly analytics: import("@lunora/bindings/analytics").AnalyticsClient;` : "";
-  const pipelinesActionField = hasPipelines ? `
-    /** Pipelines ingestion sink (durable, R2-backed). Fire-and-forget and batched; do not read it back in-handler. */
-    readonly pipelines: import("@lunora/bindings/pipelines").PipelineClient;` : "";
-  const r2sqlActionField = hasR2sql ? `
-    /**
-     * R2 SQL over Apache Iceberg tables (window functions, DISTINCT, set operations). Non-deterministic — available only in actions. Reads here are NOT tracked by Lunora live queries.
-     */
-    readonly r2sql: import("@lunora/bindings/r2sql").R2SqlClient;` : "";
   const hasWorkflows = workflows.length > 0;
   const workflowsTypeImport = hasWorkflows ? `import type { WorkflowHandle } from "@lunora/workflow";
 import type * as lunoraWorkflowDefinitions from "../workflows.js";
@@ -906,6 +1055,16 @@ type NarrowedAuth = Omit<QueryCtxBase["auth"], "getIdentity"> & { getIdentity: (
   const authContextField = identity ? `
     readonly auth: NarrowedAuth;` : "";
   const policyIdentityArgument = identity ? ", Identity" : "";
+  const envTypeImport = env ? `import type * as lunoraEnvContract from "../env.js";
+` : "";
+  const envTypeBlock = env ? `
+
+/** This app's declared env contract (\`defineEnv\` in \`lunora/env.ts\`) — the validated, coercion-aware shape of \`ctx.env\`. */
+export type LunoraEnv = ReturnType<typeof lunoraEnvContract.${env.exportName}>;` : "";
+  const envOmit = env ? ` | "env"` : "";
+  const envContextField = env ? `
+    /** Validated, typed environment declared by \`defineEnv\` in \`lunora/env.ts\` — parsed & coercion-aware config values (\`ctx.env.STRIPE_KEY\`); a missing or invalid value throws at read time. */
+    readonly env: LunoraEnv;` : "";
   const server = `${GENERATED_HEADER}import { createPolicyDsl, initLunora, v as vBase } from "${base.server}";
 import type {
     ActionBuilder,
@@ -927,11 +1086,11 @@ import type {
 } from "${base.server}";
 
 import type { DataModel, DatabaseReaderFacade, DatabaseWriterFacade, Doc, Id as IdOfTable, OrmReader, OrmWriter, Relations, TableName } from "./dataModel.js";
-${aiTypeImport}${paymentsTypeImport}${containersTypeImport}${workflowsTypeImport}${queuesTypeImport}${identityTypeImport}
+${aiTypeImport}${paymentsTypeImport}${containersTypeImport}${workflowsTypeImport}${queuesTypeImport}${identityTypeImport}${envTypeImport}
 export type { DataModel, Doc, Id, TableName } from "./dataModel.js";
 
 /** Storage buckets this schema declares (\`v.storage("name")\`), narrowing \`ctx.storage.bucket(name)\`. */
-export type StorageBucketName = ${storageBucketUnion};${envBlock}${workflowsTypeBlock}${queuesTypeBlock}${identityTypeBlock}
+export type StorageBucketName = ${storageBucketUnion};${envBlock}${workflowsTypeBlock}${queuesTypeBlock}${identityTypeBlock}${envTypeBlock}
 
 /**
  * Project-typed contexts. The base contexts from \`@lunora/server\` are
@@ -960,22 +1119,22 @@ type TypedTableQuery = (<T extends TableName>(table: T) => TableReader<Doc<T>>)
  */
 type TypedTableGet = <T extends TableName>(id: IdOfTable<T>) => Promise<Doc<T> | null>;
 
-export interface QueryCtx extends Omit<QueryCtxBase, "db" | "storage"${authOmit}> {
+export interface QueryCtx extends Omit<QueryCtxBase, "db" | "storage"${authOmit}${envOmit}> {
     readonly db: Omit<DatabaseReader, "query" | "get"> & DatabaseReaderFacade & { query: TypedTableQuery; get: TypedTableGet };
     readonly orm: OrmReader;
-    readonly storage: ReadOnlyStorage<StorageBucketName>;${accessContextField}${kvContextField}${flagsContextField}${analyticsContextField}${authContextField}
+    readonly storage: ReadOnlyStorage<StorageBucketName>;${accessContextField}${kvContextField}${flagsContextField}${analyticsContextField}${envContextField}${authContextField}
 }
 
-export interface MutationCtx extends Omit<MutationCtxBase, "db" | "storage"${workflowsOmit}${authOmit}> {
+export interface MutationCtx extends Omit<MutationCtxBase, "db" | "storage"${workflowsOmit}${authOmit}${envOmit}> {
     readonly db: Omit<DatabaseWriter, "query" | "get"> & DatabaseWriterFacade & { query: TypedTableQuery; get: TypedTableGet };
     readonly orm: OrmWriter;
-    readonly storage: ReadOnlyStorage<StorageBucketName>;${accessContextField}${kvContextField}${flagsContextField}${analyticsContextField}${workflowsContextField}${queuesContextField}${authContextField}
+    readonly storage: ReadOnlyStorage<StorageBucketName>;${accessContextField}${kvContextField}${flagsContextField}${analyticsContextField}${envContextField}${workflowsContextField}${queuesContextField}${authContextField}
 }
 
-export interface ActionCtx extends Omit<ActionCtxBase, "db" | "storage"${workflowsOmit}${authOmit}> {
+export interface ActionCtx extends Omit<ActionCtxBase, "db" | "storage"${workflowsOmit}${authOmit}${envOmit}> {
     readonly db: Omit<DatabaseWriter, "query" | "get"> & DatabaseWriterFacade & { query: TypedTableQuery; get: TypedTableGet };
     readonly orm: OrmWriter;
-    readonly storage: StorageBase<StorageBucketName>;${accessContextField}${aiActionField}${paymentsActionField}${containersActionField}${kvContextField}${flagsContextField}${hyperdriveActionField}${browserActionField}${imagesActionField}${analyticsContextField}${pipelinesActionField}${r2sqlActionField}${workflowsContextField}${queuesContextField}${authContextField}
+    readonly storage: StorageBase<StorageBucketName>;${accessContextField}${aiActionField}${paymentsActionField}${containersActionField}${kvContextField}${flagsContextField}${hyperdriveActionField}${browserActionField}${imagesActionField}${analyticsContextField}${pipelinesActionField}${r2sqlActionField}${envContextField}${workflowsContextField}${queuesContextField}${authContextField}
 }
 
 /**
@@ -1386,6 +1545,21 @@ const emitFlagsFragments = (hasFlags, flagsSpecifier) => {
     stub: ""
   };
 };
+const emitEnvFragments = (env) => {
+  if (!env) {
+    return EMPTY_HELPER_FRAGMENTS;
+  }
+  return {
+    build: `
+            const envConfig = lunoraEnvContract.${env.exportName}(env);
+`,
+    configField: "",
+    contextField: `
+                env: envConfig,`,
+    importLines: [`import * as lunoraEnvContract from "../env.js";`],
+    stub: ""
+  };
+};
 const emitAccessFragments = (hasAccessFacade) => {
   if (!hasAccessFacade) {
     return EMPTY_HELPER_FRAGMENTS;
@@ -1996,6 +2170,7 @@ const buildDoTypeImports = (hasVectors, hasWorkflows, hasQueues, hasFlags) => [
 const emitShard = ({
   advisories = [],
   containers = [],
+  env,
   flagKeys = [],
   hasAccessFacade = false,
   hasAi = false,
@@ -2027,6 +2202,7 @@ const emitShard = ({
   const kvFragments = emitKvFragments(hasKv);
   const flagsFragments = emitFlagsFragments(hasFlags, base.flags);
   const flagsOverrides = emitFlagsOverrides(flagKeys, hasFlags, base.flags);
+  const envFragments = emitEnvFragments(env);
   const analyticsFragments = emitAnalyticsFragments(hasAnalytics);
   const imagesFragments = emitImagesFragments(hasImages);
   const hyperdriveFragments = emitHyperdriveFragments(hasHyperdrive);
@@ -2181,6 +2357,7 @@ const LUNORA_RLS_READ_REGISTRY = buildRlsReadRegistry(Object.values(LUNORA_FUNCT
     ...accessFragments.importLines,
     ...kvFragments.importLines,
     ...flagsFragments.importLines,
+    ...envFragments.importLines,
     ...analyticsFragments.importLines,
     ...imagesFragments.importLines,
     ...hyperdriveFragments.importLines,
@@ -2476,8 +2653,8 @@ ${schema.tables.map(
   const secretsBuild = `
             const secrets = createSecrets(env);
 `;
-  const everyContextBuild = `${accessFragments.build}${kvFragments.build}${flagsFragments.build}${analyticsFragments.build}${secretsBuild}`;
-  const everyContextField = `${accessFragments.contextField}${kvFragments.contextField}${flagsFragments.contextField}${analyticsFragments.contextField}
+  const everyContextBuild = `${accessFragments.build}${kvFragments.build}${flagsFragments.build}${analyticsFragments.build}${envFragments.build}${secretsBuild}`;
+  const everyContextField = `${accessFragments.contextField}${kvFragments.contextField}${flagsFragments.contextField}${analyticsFragments.contextField}${envFragments.contextField}
                 secrets,`;
   const actionOnlyHasAny = hasImages || hasHyperdrive || hasBrowser || hasR2sql || hasPipelines;
   const actionOnlyBlock = actionOnlyHasAny ? `
@@ -3271,4 +3448,4 @@ const emitWranglerCronTriggers = (crons) => {
   return triggers;
 };
 
-export { GENERATED_HEADER, buildStorageColumns, emitApi, emitCollections, emitContainers, emitCrons, emitDataModel, emitDrizzleSchema, emitFunctions, emitQueues, emitSeed, emitServer, emitShard, emitVectors, emitWorkflows, emitWranglerCronTriggers };
+export { APP_METHOD_CAPABILITIES as A, CAPABILITIES as C, GENERATED_HEADER as G, emitCollections as a, emitContainers as b, emitCrons as c, emitDataModel as d, emitApi as e, emitDrizzleSchema as f, emitFunctions as g, emitServer as h, emitShard as i, emitVectors as j, emitWorkflows as k, emitWranglerCronTriggers as l, buildStorageColumns as m, emitQueues as n, emitSeed as o };

package/dist/packem_shared/{emitApp-BUCrHOeI.mjs → emitApp-nQ2oC-8G.mjs}

@@ -1,26 +1,9 @@
-import { GENERATED_HEADER } from './GENERATED_HEADER-f6nMvllu.mjs';
-
-const LONG_TAIL = [
-  ["hasAi", "ai", "ai", "Override the Workers AI binding backing `ctx.ai` (defaults to `env.AI`)."],
-  ["hasAnalytics", "analytics", "analytics", "Override the Analytics Engine dataset backing `ctx.analytics` (defaults to `env.ANALYTICS`)."],
-  ["hasBrowser", "browser", "browser", "Override the Browser Rendering binding backing `ctx.browser` (defaults to `env.BROWSER`)."],
-  [
-    "hasHyperdrive",
-    "hyperdrive",
-    "sql",
-    "Wire the Hyperdrive SQL client backing `ctx.sql` — build it with `createHyperdrive` + `fromPostgresJs`/`fromNodePg`/`fromMysql2`."
-  ],
-  ["hasImages", "images", "images", "Override the Images binding backing `ctx.images` (defaults to `env.IMAGES`)."],
-  ["hasKv", "kv", "kv", "Override the Workers KV binding backing `ctx.kv` (defaults to `env.KV`)."],
-  ["hasPayments", "payment", "payment", "Wire the payment options backing `ctx.payments`."],
-  [
-    "hasR2sql",
-    "r2sql",
-    "r2sql",
-    "Wire the R2 SQL client backing `ctx.r2sql` — build it with `createR2Sql({ accountId, apiToken, bucket })` (defaults to env `R2_SQL_TOKEN` / `R2_SQL_ACCOUNT_ID` / `R2_SQL_BUCKET`)."
-  ],
-  ["hasVectors", "vectors", "vectors", "Wire the Vectorize index map backing `ctx.vectors`."]
-];
+import { A as APP_METHOD_CAPABILITIES, G as GENERATED_HEADER } from './emit-CBwEvCXQ.mjs';
+
+const hasFlagKey = (key) => `has${key.charAt(0).toUpperCase()}${key.slice(1)}`;
+const LONG_TAIL = APP_METHOD_CAPABILITIES.map(
+  ({ appMethod, key }) => [hasFlagKey(key), appMethod.method, appMethod.configKey, appMethod.doc]
+);
 const hasAnyLongTail = (options) => LONG_TAIL.some(([flag]) => options[flag]);
 const buildIdentityImports = (identity) => identity ? [`import * as lunoraIdentityContract from "../identity.js";`] : [];
 const buildAccessImports = (hasAccess, hasAuth) => hasAccess ? [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/codegen",
-  "version": "1.0.0-alpha.31",
+  "version": "1.0.0-alpha.32",
   "description": "Code generator for Lunora: emits _generated/{api,server,dataModel}.ts from your schema",
   "keywords": [
     "cloudflare",
@@ -46,7 +46,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/advisor": "1.0.0-alpha.17",
+    "@lunora/advisor": "1.0.0-alpha.18",
     "@lunora/container": "1.0.0-alpha.6",
     "@lunora/errors": "1.0.0-alpha.1",
     "@lunora/queue": "1.0.0-alpha.4",