@telorun/analyzer 0.59.0 → 0.61.0

package/dist/validate-step-inputs.js

@@ -1,7 +1,8 @@
 import { resolveContract } from "./invocation-contract.js";
 import { checkSchemaCompatibility, navigateSchemaToExprPath, substituteCelFields, validateAgainstSchema, } from "./schema-compat.js";
 import { plainChainOf } from "@telorun/templating";
-import { valueTypeOf } from "@telorun/sdk";
+import { isLiveSlot, valueTypeOf } from "@telorun/sdk";
+import { manifestFragmentOf } from "./manifest-schemas.js";
 import { analyzerContractScope, containerOf, gatherPropertySchemas, missingRequired, resolveLocalRef, walkStepArray, } from "./analyzer.js";
 /**
  * Validate every step's `inputs:` against the invoked target's declared input
@@ -79,16 +80,27 @@ stepContext) {
             // that silence is exactly where a stream of the wrong element used to
             // flow. The comparison is covariant and gradual: an omitted argument is
             // *any* in both directions, so only a definite conflict is reported.
-            if (stepContext) {
+            // The roots a plain chain may name here, each paired with the schema it is
+            // navigated against. `steps.` is the step map (analyzer state, supplied by
+            // the caller). `inputs.` is the ENCLOSING kind's own declared inputType,
+            // which is how a value produced OUTSIDE this resource reaches a step at
+            // all: an HTTP route maps `request.body` into its handler's inputs, and the
+            // handler forwards `inputs.body` onward — the shape a live value most often
+            // arrives in, and the one covering only `steps.` missed entirely. A root
+            // this cannot resolve contributes nothing rather than guessing at a schema.
+            const roots = [];
+            if (stepContext)
+                roots.push(["steps.", stepContext]);
+            const ownContract = resolveContract("inputType", manifest, contractScope.resolveIn(manifest.kind, readingModule), contractScope);
+            if (ownContract)
+                roots.push(["inputs.", ownContract.schema]);
+            if (roots.length > 0) {
                 for (const [inputName, inputValue] of Object.entries(values)) {
                     const chain = plainChainOf(inputValue);
-                    // The step context is rooted at the STEP MAP, so a `steps.` prefix is
-                    // the namespace name and not a property of it. Only that namespace is
-                    // navigated: `inputs.` and a named binding resolve elsewhere, and
-                    // guessing at a root this does not hold would compare the wrong schema.
-                    if (!chain?.startsWith("steps."))
+                    const root = chain ? roots.find(([prefix]) => chain.startsWith(prefix)) : undefined;
+                    if (!chain || !root)
                         continue;
-                    const produced = navigateSchemaToExprPath(stepContext, chain.slice("steps.".length));
+                    const produced = navigateSchemaToExprPath(root[1], chain.slice(root[0].length));
                     const slotSchema = contract.schema.properties?.[inputName];
                     if (!produced || !slotSchema)
                         continue;
@@ -99,6 +111,27 @@ stepContext) {
                     // broad new Error-severity check hidden behind an argument-specific
                     // name. Both sides must declare a value type for the question to be
                     // about arguments at all.
+                    // A LIVE value is consumed by reading, so it exists exactly once —
+                    // that is what `live` says in the vocabulary, and re-attempting a
+                    // dispatch that already read it re-sends nothing. Reported here rather
+                    // than through a slot-specific annotation because both facts are
+                    // already declared: the value's liveness by its value type, and the
+                    // re-attempt by the retry policy. No kind is named.
+                    if (isLiveSlot(produced)) {
+                        const retry = declaredRetry(step, stepItemSchema, invokedManifest, invokedDef);
+                        if (retry !== undefined) {
+                            out.push({
+                                path: `${stepPath}.${inputsField}.${inputName}`,
+                                targetLabel: invokedName ?? invokedKind ?? "the invoked resource",
+                                message: `'${inputName}' is a live value, which is consumed by reading and so exists ` +
+                                    `once — but ${retry} re-attempts the dispatch, and a re-attempt would pass ` +
+                                    `nothing. Collect it to a value first, or chunk the work so each attempt ` +
+                                    `carries its own replayable piece.`,
+                                code: "LIVE_VALUE_RETRIED",
+                            });
+                            continue;
+                        }
+                    }
                     if (!valueTypeOf(produced) || !valueTypeOf(slotSchema))
                         continue;
                     const { compatible, issues } = checkSchemaCompatibility(produced, slotSchema, (ref) => defs.schemaForId(ref));
@@ -130,3 +163,61 @@ stepContext) {
     }
     return out;
 }
+/**
+ * Where a re-attempt is declared for this dispatch, described for a diagnostic,
+ * or undefined when none is.
+ *
+ * A field declares one when its schema was expanded from a shared retry fragment
+ * — the shape the author pointed at, rather than a marker they had to remember to
+ * write beside it. Which fragment also says WHERE the budget is, so the two
+ * spellings a kind may carry (a policy object, or the deprecated bare count) need
+ * no guessing between them and no rule about which one wins.
+ *
+ * Two sites are consulted because there are two real ones: the STEP's own policy
+ * — `retry` on the kernel-owned dispatch site — and the TARGET's, a field on an
+ * arbitrary kind, because `Http.Request` re-attempts inside its own `invoke()`
+ * where only it can tell a 429 from a 500. A live value is equally doomed by
+ * either. EVERY retry-bearing field at a site is checked, not the first, since
+ * `Http.Request` carries both spellings and property order must not decide which
+ * is seen.
+ *
+ * Only a STATICALLY KNOWN non-zero budget counts. An `attempts` written as CEL
+ * says nothing here, and guessing would report a conflict against a manifest that
+ * may never retry — the same posture the `use` case-map selector takes.
+ */
+function declaredRetry(step, stepItemSchema, invokedManifest, invokedDef) {
+    for (const [field, budget] of retryFields(stepItemSchema)) {
+        if (budget(step?.[field]) > 0)
+            return `the step's \`${field}\``;
+    }
+    for (const [field, budget] of retryFields(invokedDef?.schema)) {
+        if (budget(invokedManifest?.[field]) > 0)
+            return `the target's \`${field}\``;
+    }
+    return undefined;
+}
+/** How each shared retry fragment carries its budget. Keyed on fragment name —
+ *  the analyzer's own built-ins, never a module's kind — so a kind that adopts a
+ *  shape is covered without naming it here. */
+const RETRY_BUDGET = {
+    RetryPolicy: (value) => {
+        if (!value || typeof value !== "object")
+            return 0;
+        const attempts = value.attempts;
+        return typeof attempts === "number" ? attempts : 0;
+    },
+    RetryAttempts: (value) => (typeof value === "number" ? value : 0),
+};
+/** Every property of `schema` whose shape came from a retry fragment, paired with
+ *  the reader for that fragment's budget. */
+function retryFields(schema) {
+    if (!schema)
+        return [];
+    const out = [];
+    for (const [key, sub] of gatherPropertySchemas(schema)) {
+        const budget = RETRY_BUDGET[manifestFragmentOf(sub) ?? ""];
+        if (budget)
+            out.push([key, budget]);
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.59.0",
+  "version": "0.61.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",
@@ -43,13 +43,13 @@
     "jsonpath-plus": "^10.3.0",
     "packageurl-js": "^2.0.1",
     "yaml": "^2.8.3",
-    "@telorun/templating": "0.15.0"
+    "@telorun/templating": "0.16.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.74.0"
+    "@telorun/sdk": "0.75.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/analyzer.ts

@@ -51,6 +51,7 @@ import { REF_VALIDATION_SKIP_KINDS } from "./system-kinds.js";
 import { resolveRefSentinels } from "./resolve-ref-sentinels.js";
 import { resolveSchemaRefKinds, type RefConstraintIssue } from "./resolve-schema-ref-kinds.js";
 import { runZoneAnalysis, type ZoneExportCache } from "./resolve-zone-requirements.js";
+import { MANIFEST_SCHEMA_URI, ManifestRootSchema } from "./manifest-schemas.js";
 import { validateZoneSlotDeclarations, type ZoneSlotIssue } from "./validate-zone-slots.js";
 import {
   validateDynamicSelectors,
@@ -316,23 +317,50 @@ export function resolveLocalRef(
     const resolved = root.$defs?.[defName];
     if (resolved && typeof resolved === "object") return resolved as Record<string, any>;
   }
+  // A kernel-owned structural fragment (`telo://manifest#/$defs/InvokeStep`).
+  // Resolved HERE rather than by each walker: this is the one chokepoint every
+  // structural walk already goes through — the step-array walks, the call graph,
+  // the zone projection, the eval-path collector — so a composer that points at a
+  // shared shape stays legible to all of them at once. Nothing is inlined into
+  // the stored schema, which keeps validator-cache identity stable and matches
+  // what `resolveSchemaTypeRefs` does for a named user type.
+  if (typeof ref === "string" && ref.startsWith(BUILTIN_FRAGMENT_PREFIX)) {
+    const defName = ref.slice(BUILTIN_FRAGMENT_PREFIX.length);
+    const resolved = (ManifestRootSchema.$defs as Record<string, unknown>)[defName];
+    if (resolved && typeof resolved === "object") return resolved as Record<string, any>;
+  }
   return schema;
 }
 
+const BUILTIN_FRAGMENT_PREFIX = `${MANIFEST_SCHEMA_URI}#/$defs/`;
+
 /** Gather property schemas from a (possibly variant-bearing) object schema:
- *  top-level `properties` plus every `oneOf` / `anyOf` / `allOf` branch. */
-export function gatherPropertySchemas(schema: Record<string, any>): Array<[string, Record<string, any>]> {
+ *  top-level `properties` plus every `oneOf` / `anyOf` / `allOf` branch.
+ *
+ *  Each branch is resolved through {@link resolveLocalRef} first, so a branch
+ *  that points at a shared shape — a `oneOf` arm that IS the kernel's dispatch
+ *  site — contributes its properties like an inline one. Without that, pointing a
+ *  composer at a shared shape would silently empty every role-driven lookup that
+ *  reads this (the inputs slot, the retry policy, the eval paths), which is a
+ *  failure with no diagnostic attached to it. */
+export function gatherPropertySchemas(
+  schema: Record<string, any>,
+  root?: Record<string, any>,
+): Array<[string, Record<string, any>]> {
   const out: Array<[string, Record<string, any>]> = [];
-  if (schema.properties && typeof schema.properties === "object") {
-    for (const [k, v] of Object.entries(schema.properties as Record<string, any>)) {
+  const base = resolveLocalRef(schema, root ?? schema) ?? schema;
+  if (base.properties && typeof base.properties === "object") {
+    for (const [k, v] of Object.entries(base.properties as Record<string, any>)) {
       out.push([k, v as Record<string, any>]);
     }
   }
   for (const variantKey of ["oneOf", "anyOf", "allOf"] as const) {
-    const arr = schema[variantKey];
+    const arr = base[variantKey];
     if (!Array.isArray(arr)) continue;
-    for (const variant of arr) {
-      if (variant && typeof variant === "object" && variant.properties) {
+    for (const raw of arr) {
+      if (!raw || typeof raw !== "object") continue;
+      const variant = resolveLocalRef(raw as Record<string, any>, root ?? schema) ?? raw;
+      if (variant.properties) {
         for (const [k, v] of Object.entries(variant.properties as Record<string, any>)) {
           out.push([k, v as Record<string, any>]);
         }
@@ -2012,9 +2040,12 @@ export class StaticAnalyzer {
                 severity: DiagnosticSeverity.Error,
                 code: issue.code ?? "CONTRACT_INPUTS_MISMATCH",
                 source: SOURCE,
-                message: issue.code
-                  ? `${m.kind}/${stepName}: inputs at '${issue.path}' flow into ${issue.targetLabel} with disagreeing type arguments: ${issue.message}`
-                  : `${m.kind}/${stepName}: inputs at '${issue.path}' do not satisfy ${issue.targetLabel}'s declared inputType: ${issue.message}`,
+                message:
+                  issue.code === "LIVE_VALUE_RETRIED"
+                    ? `${m.kind}/${stepName}: at '${issue.path}', ${issue.message}`
+                    : issue.code
+                      ? `${m.kind}/${stepName}: inputs at '${issue.path}' flow into ${issue.targetLabel} with disagreeing type arguments: ${issue.message}`
+                      : `${m.kind}/${stepName}: inputs at '${issue.path}' do not satisfy ${issue.targetLabel}'s declared inputType: ${issue.message}`,
                 data: {
                   resource: { kind: m.kind, name: stepName ?? "" },
                   filePath: stepFile,

package/src/artifact-layer-index.ts

@@ -29,8 +29,10 @@
  */
 
 import {
+  LAYER_ROLES,
   isLayerRole,
   normalizeSelector,
+  roleCarriesSelector,
   selectorKey,
   selectorMatches,
   type ArtifactSelector,
@@ -46,7 +48,7 @@ const CONTENT_DIGEST = /^sha256-[A-Za-z0-9_-]{43}$/;
 
 export interface ArtifactLayer {
   role: LayerRole;
-  /** Present on `controller` layers only. */
+  /** Present on the code-bearing roles (`controller`, `library`) only. */
   selector?: ArtifactSelector;
   /** OCI blob digest — addresses the layer and verifies the transfer. */
   blob: string;
@@ -97,25 +99,35 @@ export function parseLayerIndex(value: unknown, describe = "layers"): ArtifactLa
       throw new LayerIndexError(`${where}: expected an object.`);
     }
     const entry = raw as Record<string, unknown>;
-    if (!isLayerRole(entry.role)) {
+    if (typeof entry.role !== "string" || entry.role === "") {
       throw new LayerIndexError(
-        `${where}: role must be one of 'controller', 'assets', 'common'; got ` +
-          `${entry.role === undefined ? "nothing" : `'${String(entry.role)}'`}.`,
+        `${where}: role is required and must be one of ${LAYER_ROLES.map((r) => `'${r}'`).join(", ")}; ` +
+          `got ${entry.role === undefined ? "nothing" : `'${String(entry.role)}'`}.`,
       );
     }
+    // A role this runtime does not know is SKIPPED, never rejected. Roles are
+    // added over time, and a runtime that cannot name one cannot need it — while
+    // throwing would make the whole manifest unreadable, so a module gaining a
+    // layer for a newer runtime would stop loading on an older one entirely
+    // rather than merely lacking that layer. The error stays for a structurally
+    // invalid entry, which is a malformed index rather than a newer one.
+    if (!isLayerRole(entry.role)) return;
     const role = entry.role;
 
     let selector: ArtifactSelector | undefined;
-    if (role === "controller") {
+    if (roleCarriesSelector(role)) {
       if (entry.selector === undefined) {
-        throw new LayerIndexError(`${where}: a controller layer must declare a selector.`);
+        throw new LayerIndexError(`${where}: a ${role} layer must declare a selector.`);
       }
       selector = normalizeSelector(entry.selector, where);
-      const key = selectorKey(selector);
+      // Scoped by role: a module's `js` controller layer and its `js` library
+      // layer are different layers with the same selector, and only a collision
+      // *within* one role means two layers claim one address.
+      const key = `${role}\0${selectorKey(selector)}`;
       if (seenSelectors.has(key)) {
         throw new LayerIndexError(
-          `${where}: a second controller layer claims the selector ${key}. ` +
-            `Each selector addresses exactly one layer.`,
+          `${where}: a second ${role} layer claims the selector ${selectorKey(selector)}. ` +
+            `Each selector addresses exactly one layer of a role.`,
         );
       }
       seenSelectors.add(key);
@@ -145,18 +157,39 @@ export function parseLayerIndex(value: unknown, describe = "layers"): ArtifactLa
 /** The singleton layer for a role, or undefined when the artifact has none. */
 export function singletonLayer(
   layers: readonly ArtifactLayer[],
-  role: Exclude<LayerRole, "controller">,
+  role: Exclude<LayerRole, "controller" | "library">,
 ): ArtifactLayer | undefined {
   return layers.find((l) => l.role === role);
 }
 
-/** Every controller layer matching `target`, in declaration order. Used by
- *  `telo install` to warm a cache for one platform. */
-export function matchControllerLayers(
+/** The layer of one code role carrying exactly `selector`, or undefined.
+ *
+ *  By exact key rather than by re-matching a host: the candidate being resolved
+ *  already *is* one selector, and it is by construction the key of the layer
+ *  that carries it. */
+export function codeLayerFor(
+  layers: readonly ArtifactLayer[],
+  role: Extract<LayerRole, "controller" | "library">,
+  selector: ArtifactSelector,
+): ArtifactLayer | undefined {
+  const key = selectorKey(selector);
+  return layers.find(
+    (l) => l.role === role && l.selector !== undefined && selectorKey(l.selector) === key,
+  );
+}
+
+/** Every code layer — controller and library alike — matching `target`, in
+ *  declaration order. Used by `telo install` to warm a cache for one platform:
+ *  a library layer is as much a prerequisite of an offline run as the controller
+ *  layer that imports it. */
+export function matchCodeLayers(
   layers: readonly ArtifactLayer[],
   target: PlatformTarget,
 ): ArtifactLayer[] {
   return layers.filter(
-    (l) => l.role === "controller" && l.selector !== undefined && selectorMatches(l.selector, target),
+    (l) =>
+      (l.role === "controller" || l.role === "library") &&
+      l.selector !== undefined &&
+      selectorMatches(l.selector, target),
   );
 }

package/src/artifact-selector.ts

@@ -25,16 +25,27 @@
  * published into OCI descriptors.
  */
 
-/** The role a layer plays in a module artifact. `controller` layers carry a
- *  selector; `assets` and `common` are singletons and carry none. */
-export type LayerRole = "controller" | "assets" | "common";
+/** The role a layer plays in a module artifact. `controller` and `library` layers
+ *  carry a selector; `assets` and `common` are singletons and carry none. */
+export type LayerRole = "controller" | "library" | "assets" | "common";
 
-export const LAYER_ROLES: readonly LayerRole[] = ["controller", "assets", "common"];
+export const LAYER_ROLES: readonly LayerRole[] = ["controller", "library", "assets", "common"];
 
 export function isLayerRole(value: unknown): value is LayerRole {
   return typeof value === "string" && (LAYER_ROLES as readonly string[]).includes(value);
 }
 
+/** The roles that hold executable code, and are therefore per format rather than
+ *  singletons. A `library` layer is per selector for the same reason a
+ *  `controller` layer is: a module's JS entry point and its future Rust one are
+ *  different files, and a consumer resolves the one its own runtime can import.
+ *  A singleton would be wrong the moment a second runtime ships. */
+export const CODE_LAYER_ROLES: readonly LayerRole[] = ["controller", "library"];
+
+export function roleCarriesSelector(role: LayerRole): boolean {
+  return (CODE_LAYER_ROLES as readonly string[]).includes(role);
+}
+
 /** The platform axes, in canonical order. Not a closed vocabulary of *values* —
  *  new architectures appear without a Telo release — only of axis names. */
 export const PLATFORM_AXES = ["os", "arch", "libc"] as const;

package/src/builtins.ts

@@ -1,3 +1,4 @@
+import { manifestFragment } from "./manifest-schemas.js";
 import type { ResourceDefinition } from "@telorun/sdk";
 import { OBSERVED_STATE_SCHEMA } from "./validate-observed-state.js";
 
@@ -32,6 +33,33 @@ const ASSETS_FILES_SCHEMA = {
   items: { type: "string" },
 };
 
+/** `exports.code` — the entry point a sibling module's controller bundle resolves
+ *  this library's bare specifier to, one per format.
+ *
+ *  Data rather than a package URL: `controllers:` needs a PURL because it can name
+ *  an ecosystem fetch (`pkg:npm`, `pkg:cargo`), while this always names a file the
+ *  module already ships, so the type/namespace segments would be constant noise —
+ *  and a query string is one opaque box to the visual editor. `format` plus the
+ *  platform axes build the same `ArtifactSelector` a controller candidate does.
+ *  Semantics and diagnostics live in `analyzer/nodejs/src/module-library.ts`. */
+const LIBRARY_CANDIDATES_SCHEMA = {
+  type: "array",
+  items: {
+    type: "object",
+    required: ["specifier", "format", "path"],
+    properties: {
+      specifier: { type: "string" },
+      format: { type: "string" },
+      path: { type: "string" },
+      source: { type: "string" },
+      os: { type: "string" },
+      arch: { type: "string" },
+      libc: { type: "string" },
+    },
+    additionalProperties: false,
+  },
+};
+
 /** The published layer index, written by `telo publish` (never hand-authored).
  *  One entry per layer except the manifest layer, which cannot list its own hash
  *  inside itself and is pinned by the importer's `#sha256-...` instead. Shape and
@@ -43,7 +71,7 @@ const LAYER_INDEX_SCHEMA = {
     type: "object",
     required: ["role", "blob", "integrity"],
     properties: {
-      role: { type: "string", enum: ["controller", "assets", "common"] },
+      role: { type: "string", enum: ["controller", "library", "assets", "common"] },
       selector: {
         type: "object",
         required: ["format"],
@@ -620,48 +648,21 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
                 },
                 additionalProperties: false,
               },
-              // Inline flat invoke step: invoke an Invocable / Runnable on boot
-              // with an optional `name` (for steps.<name>.result plumbing),
-              // `when` guard, and `inputs`. Discriminated by the `invoke` key.
-              // Control flow (if/while/switch/try) is not available here —
-              // reach for Run.Sequence. `invoke` is ref-only: a `!ref` that
-              // resolves to the `{ kind, name }` shape below. Requiring `name`
-              // rejects an inline `{ kind }` definition (no name) at analysis
-              // instead of failing at boot with an undefined resource name. The
-              // Invocable/Runnable kind set mirrors Run.Sequence invoke steps.
-              {
-                type: "object",
-                required: ["invoke"],
-                properties: {
-                  name: { type: "string" },
-                  invoke: {
-                    "x-telo-topology-role": "invoke",
-                    "x-telo-ref": {
-                      kind: "Telo.Executable",
-                      use: "call",
-                      inputs: "/inputs",
-                    },
-                    type: "object",
-                    required: ["kind", "name"],
-                    properties: {
-                      kind: { type: "string" },
-                      name: { type: "string" },
-                    },
-                    additionalProperties: true,
-                  },
-                  inputs: {
-                    // Same annotation Run.Sequence steps carry: it is what makes
-                    // a boot target's inputs visible to the call-site contract
-                    // check and to the wiring rule. Without it the kernel would
-                    // validate these at dispatch and nothing before it.
-                    "x-telo-topology-role": "inputs",
-                    type: "object",
-                    additionalProperties: true,
-                  },
-                  when: { type: "string" },
-                },
-                additionalProperties: false,
-              },
+              // Inline flat invoke step, discriminated by the `invoke` key —
+              // THE dispatch site, shared with every `Run` step array rather
+              // than restated here. Restating it is what made `retry:` a schema
+              // error at boot while working one line away in a sequence: not a
+              // decision about boot, just a copy that never grew the field.
+              // Control flow (if/while/switch/try) is still not available here —
+              // reach for Run.Sequence.
+              // An expanded, stamped COPY. `builtins.ts` is not a manifest, so it
+              // never passes through the loader's expansion — embedding the
+              // fragment object itself would leave the nested `retry` as an
+              // unresolved `$ref` with no `x-telo-fragment` stamp, which is
+              // exactly what made LIVE_VALUE_RETRIED silently skip every boot
+              // target. A copy, because this is a module-level singleton and
+              // `resolveSchemaRefKinds` rewrites the `x-telo-ref` inside it.
+              manifestFragment("InvokeStep"),
             ],
           },
         },
@@ -872,6 +873,7 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
               type: "array",
               items: { type: "string", not: { enum: ["variables", "secrets"] } },
             },
+            code: LIBRARY_CANDIDATES_SCHEMA,
           },
           additionalProperties: true,
         },

package/src/cel-environment.ts

@@ -1,5 +1,6 @@
 import { Environment } from "@marcbachmann/cel-js";
 import type { ResourceManifest } from "@telorun/sdk";
+import { authoredModuleMetadata, moduleMetadataSchema } from "./module-metadata-scope.js";
 import { jsonSchemaToCelType, VALUE_BRAND_BASE } from "./schema-compat.js";
 
 /** Transport protocol on a `ports` entry → the nominal CEL brand its resolved
@@ -89,6 +90,32 @@ export function buildTypedCelEnvironment(
     env.registerVariable("secrets", "map");
     env.registerVariable("resources", "map");
 
+    // `module` — the declaring module's own `metadata`, so a manifest reads its
+    // version instead of restating it. A resource forwarded from an imported
+    // library reads THAT library's metadata, stamped as
+    // `metadata.moduleGlobals.module`.
+    //
+    // Falls back to an OPEN map, never to `manifest.metadata`: for a resource
+    // doc that is the RESOURCE's metadata (`{name: <resource name>}`), and
+    // closing `module` over it would turn a `module.version` that resolves
+    // perfectly well at runtime into a hard error the author cannot act on. A
+    // static check that is wrong in the rejecting direction is the worse
+    // polarity.
+    const moduleSchema = moduleMetadataSchema(
+      ((manifest.metadata as Record<string, any> | undefined)?.moduleGlobals?.module as
+        | Record<string, unknown>
+        | undefined) ?? (rootModuleManifest?.metadata as Record<string, unknown> | undefined),
+    );
+    if (moduleSchema) {
+      const schema: Record<string, string> = {};
+      for (const [key, property] of Object.entries(moduleSchema.properties as Record<string, any>)) {
+        schema[key] = jsonSchemaToCelType(property);
+      }
+      (env as any).registerVariable({ name: "module", schema });
+    } else {
+      env.registerVariable("module", "map");
+    }
+
     if (extraContextSchema?.properties) {
       for (const [name, propSchema] of Object.entries(
         extraContextSchema.properties as Record<string, any>,
@@ -159,5 +186,15 @@ export function buildImportInputCelEnvironment(
   for (const name of ["resources", "ports"]) {
     (env as any).registerVariable({ name, schema: {} });
   }
+  // `module` IS part of it: the importer's own identity is config, and passing
+  // its version down to a child is the case the binding exists for.
+  const metadata = authoredModuleMetadata(mod?.metadata as Record<string, unknown> | undefined);
+  if (Object.keys(metadata).length > 0) {
+    const schema: Record<string, string> = {};
+    for (const key of Object.keys(metadata)) schema[key] = "dyn";
+    (env as any).registerVariable({ name: "module", schema });
+  } else {
+    env.registerVariable("module", "map");
+  }
   return env;
 }

package/src/flatten-for-analyzer.ts

@@ -100,6 +100,10 @@ export interface ModuleGlobals {
   variables?: Record<string, unknown>;
   secrets?: Record<string, unknown>;
   ports?: Record<string, unknown>;
+  /** The declaring module's own `metadata` — what `module.<field>` reads. Its
+   *  values, not a schema, because the fields are literals in the manifest and
+   *  the module a resource belongs to is fixed at analysis time. */
+  module?: Record<string, unknown>;
 }
 
 /** Read the schema-map blocks off a module doc, or `undefined` when it declares
@@ -120,6 +124,14 @@ function readModuleGlobals(libDoc: ResourceManifest | undefined): ModuleGlobals
     const block = doc[key];
     if (block && typeof block === "object" && !Array.isArray(block)) globals[key] = block;
   }
+  // `module` is the declaring module's own identity, so it travels with a
+  // forwarded manifest for the same reason the config blocks do: a library's
+  // `module.version` is the LIBRARY's, and typing it from the consumer's entry
+  // doc would report the app's version to the library that asked.
+  const metadata = doc.metadata;
+  if (metadata && typeof metadata === "object" && !Array.isArray(metadata)) {
+    globals.module = metadata as Record<string, unknown>;
+  }
   return Object.keys(globals).length > 0 ? globals : undefined;
 }
 

package/src/index.ts

@@ -222,12 +222,14 @@ export {
 } from "./sources/manifest-cache.js";
 export type { ManifestCacheCoords } from "./sources/manifest-cache.js";
 export {
+  CODE_LAYER_ROLES,
   LAYER_ROLES,
   PLATFORM_AXES,
   ArtifactSelectorError,
   describeSelector,
   isLayerRole,
   normalizeSelector,
+  roleCarriesSelector,
   selectorFromQualifiers,
   selectorKey,
   selectorMatches,
@@ -240,9 +242,16 @@ export type {
 } from "./artifact-selector.js";
 export { collectModuleFileClaims } from "./module-file-claims.js";
 export type { ModuleFileClaim } from "./module-file-claims.js";
+export { readLibraryCandidates } from "./module-library.js";
+export type {
+  LibraryCandidate,
+  LibraryCandidateProblem,
+  LibraryCandidates,
+} from "./module-library.js";
 export {
   LayerIndexError,
-  matchControllerLayers,
+  codeLayerFor,
+  matchCodeLayers,
   parseLayerIndex,
   singletonLayer,
 } from "./artifact-layer-index.js";
@@ -270,4 +279,12 @@ export type {
     PositionIndex,
     Range
 } from "./types.js";
-
+export * from "./manifest-schemas.js";
+// The release model — module identity, fragments, the ledger, the edge graph and
+// version planning. Pure data in, plan out, so the editor and the CLI release
+// from one model.
+export {
+  DERIVED_METADATA_FIELDS,
+  authoredModuleMetadata,
+} from "./module-metadata-scope.js";
+export * from "./release/index.js";