@telorun/analyzer 0.59.0 → 0.60.0

package/dist/release/workspace-config.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `telo-workspace.yaml` — the release anchor.
+ *
+ * Every path the release system names — a module key, a ledger entry, a
+ * fragment's `modules:` — is relative to this file's directory. That is the
+ * whole of its job: **its location is the anchor**, and its one field names the
+ * subtrees that may hold modules, which is not derivable (a whole-tree scan
+ * would read every example and every cached `.telo/manifests` copy as a released
+ * module).
+ *
+ * The file is **optional and read only by `telo release`**. Nothing else — not
+ * `run`, `check`, `publish`, `install`, `upgrade`, `migrate`, `module`, and not
+ * the kernel — looks for it, so a single-manifest repo, a bare `examples/`
+ * directory and a third-party module checkout keep working with nothing added.
+ * Any field added later must be true of the whole tree, not derivable from it,
+ * and harmless by its absence.
+ *
+ * Parsing lives here, in the browser-safe half, because the editor answers
+ * "what does changing this library bump?" from the same model. Finding the file
+ * on disk is the CLI's half — this side takes text.
+ */
+export declare const WORKSPACE_FILENAME = "telo-workspace.yaml";
+export interface WorkspaceConfig {
+    /**
+     * Gitignore-style patterns, workspace-relative, naming the subtrees that may
+     * hold modules (`modules/*`, `apps/*`). A pattern names a place to look, never
+     * a module: what makes a directory a module is its `telo.yaml`.
+     */
+    readonly modules: readonly string[];
+}
+export declare class WorkspaceConfigError extends Error {
+}
+/**
+ * Parse the marker file's text.
+ *
+ * Strict about its one field, because there is nothing here to be lenient with:
+ * an empty or absent `modules:` names no subtree, so discovery would find no
+ * module and every gate would silently pass over a whole repo.
+ */
+export declare function parseWorkspaceConfig(text: string, where: string): WorkspaceConfig;
+//# sourceMappingURL=workspace-config.d.ts.map

package/dist/release/workspace-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-config.d.ts","sourceRoot":"","sources":["../../src/release/workspace-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,eAAO,MAAM,kBAAkB,wBAAwB,CAAC;AAExD,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,qBAAa,oBAAqB,SAAQ,KAAK;CAAG;AAElD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,eAAe,CAoCjF"}

package/dist/release/workspace-config.js

@@ -0,0 +1,60 @@
+/**
+ * `telo-workspace.yaml` — the release anchor.
+ *
+ * Every path the release system names — a module key, a ledger entry, a
+ * fragment's `modules:` — is relative to this file's directory. That is the
+ * whole of its job: **its location is the anchor**, and its one field names the
+ * subtrees that may hold modules, which is not derivable (a whole-tree scan
+ * would read every example and every cached `.telo/manifests` copy as a released
+ * module).
+ *
+ * The file is **optional and read only by `telo release`**. Nothing else — not
+ * `run`, `check`, `publish`, `install`, `upgrade`, `migrate`, `module`, and not
+ * the kernel — looks for it, so a single-manifest repo, a bare `examples/`
+ * directory and a third-party module checkout keep working with nothing added.
+ * Any field added later must be true of the whole tree, not derivable from it,
+ * and harmless by its absence.
+ *
+ * Parsing lives here, in the browser-safe half, because the editor answers
+ * "what does changing this library bump?" from the same model. Finding the file
+ * on disk is the CLI's half — this side takes text.
+ */
+import { parseDocument } from "yaml";
+export const WORKSPACE_FILENAME = "telo-workspace.yaml";
+export class WorkspaceConfigError extends Error {
+}
+/**
+ * Parse the marker file's text.
+ *
+ * Strict about its one field, because there is nothing here to be lenient with:
+ * an empty or absent `modules:` names no subtree, so discovery would find no
+ * module and every gate would silently pass over a whole repo.
+ */
+export function parseWorkspaceConfig(text, where) {
+    let value;
+    try {
+        value = parseDocument(text).toJSON();
+    }
+    catch (err) {
+        throw new WorkspaceConfigError(`${where} is not valid YAML: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new WorkspaceConfigError(`${where} must be a YAML mapping.`);
+    }
+    const record = value;
+    for (const key of Object.keys(record)) {
+        if (key !== "modules") {
+            throw new WorkspaceConfigError(`${where}: unknown field '${key}'. The workspace marker carries only 'modules:' — ` +
+                `the subtrees that may hold modules.`);
+        }
+    }
+    const modules = record.modules;
+    if (!Array.isArray(modules) || modules.some((entry) => typeof entry !== "string")) {
+        throw new WorkspaceConfigError(`${where}: 'modules' must be a list of path patterns, e.g. [modules/*, apps/*].`);
+    }
+    if (modules.length === 0) {
+        throw new WorkspaceConfigError(`${where}: 'modules' is empty, so no directory can ever be discovered as a module. ` +
+            `List the subtrees that hold them, e.g. [modules/*, apps/*].`);
+    }
+    return { modules: modules };
+}

package/dist/schema-compat.js

@@ -1,7 +1,8 @@
 import AjvModule from "ajv";
 import addFormats from "ajv-formats";
-import { isRefSentinel, isTaggedSentinel, ManifestRootSchema, producedTypeOf, } from "@telorun/templating";
+import { isRefSentinel, isTaggedSentinel, producedTypeOf, } from "@telorun/templating";
 import { celBaseOfValueType, celTypeOfValueType, readValueTypeSlot, valueBrandBases, valueTypeOf, valueTypePlaceholder, } from "@telorun/sdk";
+import { ManifestRootSchema } from "./manifest-schemas.js";
 import { registerTeloKeywords } from "./value-type-keyword.js";
 const Ajv = AjvModule.default ?? AjvModule;
 /** Creates a configured AJV instance (allErrors, strict: false, with formats).

package/dist/validate-step-inputs.d.ts

@@ -6,7 +6,7 @@ export interface StepInputIssue {
     message: string;
     /** Set when the issue is a type-argument disagreement rather than a contract
      *  shape violation — the two read differently and deserve their own code. */
-    code?: "CEL_TYPE_ARGUMENT_MISMATCH";
+    code?: "CEL_TYPE_ARGUMENT_MISMATCH" | "LIVE_VALUE_RETRIED";
 }
 /**
  * Validate every step's `inputs:` against the invoked target's declared input

package/dist/validate-step-inputs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-step-inputs.d.ts","sourceRoot":"","sources":["../src/validate-step-inputs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAoBnE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB;iFAC6E;IAC7E,IAAI,CAAC,EAAE,4BAA4B,CAAC;CACrC;AAGD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC7B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC9B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,EACnC,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,YAAY;AACpB;;mEAEmE;AACnE,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAChC,cAAc,EAAE,CAiHlB"}
+{"version":3,"file":"validate-step-inputs.d.ts","sourceRoot":"","sources":["../src/validate-step-inputs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAqBnE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB;iFAC6E;IAC7E,IAAI,CAAC,EAAE,4BAA4B,GAAG,oBAAoB,CAAC;CAC5D;AAGD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC7B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC9B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,EACnC,IAAI,EAAE,kBAAkB,EACxB,OAAO,EAAE,aAAa,EACtB,MAAM,EAAE,YAAY;AACpB;;mEAEmE;AACnE,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAChC,cAAc,EAAE,CAsJlB"}

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.60.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/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";
 
@@ -620,48 +621,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"),
             ],
           },
         },

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

@@ -270,4 +270,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";

package/src/kernel-globals.ts

@@ -1,4 +1,5 @@
 import type { ResourceManifest } from "@telorun/sdk";
+import { moduleMetadataSchema } from "./module-metadata-scope.js";
 import { residualEntrySchemaMap } from "./residual-schema.js";
 import { applyObservedStateNode } from "./validate-observed-state.js";
 
@@ -13,7 +14,13 @@ import { applyObservedStateNode } from "./validate-observed-state.js";
  * by declaring a typed `variables:`/`secrets:` entry with an `env:` binding
  * and referencing `variables.X` / `secrets.X`.
  */
-export const KERNEL_GLOBAL_NAMES = ["variables", "secrets", "resources", "ports"] as const;
+export const KERNEL_GLOBAL_NAMES = [
+  "variables",
+  "secrets",
+  "resources",
+  "ports",
+  "module",
+] as const;
 
 const SYSTEM_KINDS = new Set([
   "Telo.Definition",
@@ -90,6 +97,7 @@ interface ModuleGlobals {
   variables?: Record<string, unknown>;
   secrets?: Record<string, unknown>;
   ports?: Record<string, unknown>;
+  module?: Record<string, unknown>;
 }
 
 function globalsSchema(
@@ -103,10 +111,24 @@ function globalsSchema(
       secrets: buildSchemaMapSchema(doc?.secrets as Record<string, any> | undefined),
       resources: resourcesSchema,
       ports: buildPortsSchema(doc?.ports as Record<string, any> | undefined),
+      module: buildModuleSchema(doc),
     },
   };
 }
 
+/** The `module` namespace. Derived by `moduleMetadataSchema`, the same call the
+ *  CEL environment types from, so the two cannot disagree about which fields
+ *  exist or whether the namespace is closed. */
+function buildModuleSchema(doc: ModuleGlobals | Record<string, any> | undefined): Record<string, any> {
+  return (
+    moduleMetadataSchema(
+      ((doc as ModuleGlobals | undefined)?.module ?? (doc as any)?.metadata) as
+        | Record<string, unknown>
+        | undefined,
+    ) ?? { type: "object", additionalProperties: true }
+  );
+}
+
 /** Every non-system resource name in the set, plus the scope-declared ones. */
 function buildResourcesSchema(
   manifests: ResourceManifest[],