@telorun/analyzer 0.58.0 → 0.60.0

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

@@ -62,12 +62,19 @@ export {
 export type { ContractDirection, DefResolver } from "./extends-resolution.js";
 export {
   defaultBearingPaths,
+  declaredScalarPaths,
   PERMISSIVE_CONTRACT,
   resolveContract,
   resolveContractSchema,
   withLiveValuesSkipped,
 } from "./invocation-contract.js";
-export type { ContractOrigin, ContractScope, ResolvedContract } from "./invocation-contract.js";
+export type {
+  ContractOrigin,
+  ContractScope,
+  DeclaredScalarForm,
+  DeclaredScalarPath,
+  ResolvedContract,
+} from "./invocation-contract.js";
 export {
   hasIntermediateWildcard,
   parseRedactionPath,
@@ -136,7 +143,7 @@ export { validateDynamicSelectors, validateRefSlotDeclarations } from "./validat
 export type { RefSlotIssue } from "./validate-ref-slots.js";
 export { validateValueTypeSlots } from "./validate-value-type-slots.js";
 export type { ValueTypeSlotIssue } from "./validate-value-type-slots.js";
-export { checkSchemaCompatibility } from "./schema-compat.js";
+export { checkSchemaCompatibility, selectUnionBranch } from "./schema-compat.js";
 export type { CompatibilityResult } from "./schema-compat.js";
 export { visitManifest } from "./manifest-visitor.js";
 export type {
@@ -263,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/invocation-contract.ts

@@ -1,4 +1,4 @@
-import { isLiveSlot, type ResourceDefinition } from "@telorun/sdk";
+import { isLiveSlot, type ResourceDefinition, valueTypeOf } from "@telorun/sdk";
 import {
   type ContractDirection,
   contractDeclarer,
@@ -268,3 +268,94 @@ export function defaultBearingPaths(
   walk(schema, [], []);
   return out;
 }
+
+/** The scalar form a declared node's value takes at runtime. `int64` and
+ *  `double` are the two JSON scalars whose runtime representation is NOT decided
+ *  by the value that arrives: a CEL integer is a BigInt and a CEL double a JS
+ *  number, and both are `typeof "number" | "bigint"` away from what a declaration
+ *  says they are. Everything else — string, boolean, object, array, and every
+ *  `instance` value type — is already its own representation, so it is not
+ *  listed and never rewritten. */
+export type DeclaredScalarForm = "int64" | "double";
+
+export interface DeclaredScalarPath {
+  readonly path: string[];
+  readonly form: DeclaredScalarForm;
+}
+
+/** Every path in `schema` whose declared type fixes a scalar representation —
+ *  the leaves a value must carry in that form for the contract to be TRUE, not
+ *  merely to pass.
+ *
+ *  A declared shape says what the value IS, the same service a JSON Schema gives
+ *  an HTTP response serializer. Telo's CEL layer takes it literally:
+ *  `jsonSchemaToCelType` maps `integer` to CEL `int` and `number` to `double`,
+ *  and a CEL int IS a BigInt — so a controller handing back a plain JS number at
+ *  an `integer` slot makes the declaration a lie that surfaces nowhere until an
+ *  expression composes it, as `result.n + 1` type-checking statically and then
+ *  dying at dispatch with `no such overload: dyn<double> + int`.
+ *
+ *  A VALUE TYPE is read through the same rule rather than beside it: a `json`
+ *  representation refines a JSON type and contributes its `base` (so
+ *  `Telo.TcpPort` is an `int64` slot), while an `instance` representation
+ *  REPLACES the JSON layer — a byte buffer and a stream handle are already their
+ *  own representation, nothing converts to them, and the walk stops there rather
+ *  than descending into a value that is not a plain container.
+ *
+ *  Bounded by the schema's declarations rather than by the size of the payload,
+ *  exactly as {@link defaultBearingPaths} is: a contract declaring no such
+ *  scalar walks nothing at dispatch. A union counts when it names exactly one of
+ *  the two — `["integer", "null"]` is still the integer branch, while
+ *  `["integer", "number"]` fixes nothing and is left alone. */
+export function declaredScalarPaths(
+  schema: Record<string, any>,
+  resolveRef?: (ref: string) => Record<string, any> | undefined,
+): DeclaredScalarPath[] {
+  const out: DeclaredScalarPath[] = [];
+
+  const walk = (node: unknown, path: string[], chain: readonly object[]): void => {
+    if (!node || typeof node !== "object") return;
+    let s = node as Record<string, any>;
+    if (chain.includes(s)) return;
+    if (resolveRef && typeof s.$ref === "string") {
+      const target = resolveRef(s.$ref);
+      if (!target || chain.includes(target)) return;
+      s = { ...target, ...s, $ref: undefined };
+    }
+    const here = [...chain, node as object];
+
+    const entry = valueTypeOf(s);
+    // An `instance` representation replaces the JSON layer: it is its own
+    // representation, so there is nothing to normalize to and nothing below it
+    // that is a plain container to walk.
+    if (entry && entry.representation === "instance") return;
+
+    const form = scalarFormOf(entry && entry.base !== undefined ? entry.base : s.type);
+    if (form && path.length > 0) out.push({ path, form });
+
+    const properties = s.properties as Record<string, any> | undefined;
+    if (properties) {
+      for (const [key, child] of Object.entries(properties)) walk(child, [...path, key], here);
+    }
+    for (const branch of ["allOf", "anyOf", "oneOf"] as const) {
+      const list = s[branch];
+      if (Array.isArray(list)) for (const child of list) walk(child, path, here);
+    }
+    if (s.items) walk(s.items, [...path, "[]"], here);
+  };
+
+  walk(schema, [], []);
+  return out;
+}
+
+function scalarFormOf(declared: unknown): DeclaredScalarForm | undefined {
+  if (declared === "integer") return "int64";
+  if (declared === "number") return "double";
+  if (!Array.isArray(declared)) return undefined;
+  const integer = declared.includes("integer");
+  const number = declared.includes("number");
+  // A union naming both fixes nothing — either representation satisfies it, so
+  // rewriting one into the other would be a choice the declaration never made.
+  if (integer === number) return undefined;
+  return integer ? "int64" : "double";
+}

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[],