@telorun/analyzer 0.61.0 → 0.62.1

package/src/requires-block.ts

@@ -0,0 +1,253 @@
+/**
+ * The single reader of a module doc's `requires:` block — the version ranges of
+ * runtime a module declares itself verified against. The load gate, the CLI's
+ * publish preflight and `upgrade`'s candidate filter all recognise the block
+ * here and nowhere else, the one-accessor rule `ref-slot.ts` and `zone-slot.ts`
+ * established. Browser-safe: no Node built-ins, so the editor reaches the
+ * identical rule the kernel does.
+ *
+ * ```yaml
+ * requires:
+ *   telo: ">=0.80.0"
+ *   host:
+ *     node: ">=20.0.0"
+ * ```
+ *
+ * **Two tiers, and the split is not cosmetic.** `telo` names the *manifest
+ * surface generation* a runtime implements — one scale shared by every kernel,
+ * Node, Rust or Go, independent of each kernel's own release identity — and it
+ * is the one axis verified by EXECUTION, by running the CLI at each edge of the
+ * declared range. Host axes cannot be edge-verified by any CI; they are asserted
+ * by the author and compared against the version the running host reports
+ * ({@link HostVersions}). A flat map would imply one semantics for both.
+ *
+ * Nesting is also what disambiguates the names: `nodejs` and `rust` are already
+ * *kernel labels* in this repo (`LABEL_TO_PURL_TYPE`, an `imports:` entry's
+ * `runtime:`), so a top-level `node:` reads as the Node kernel rather than the
+ * Node.js runtime — and no word escapes that, because the host runtime and the
+ * kernel implementation genuinely share a name. Under `host:` position carries
+ * the disambiguation and no word has to.
+ *
+ * **Ordering is normative: `telo` is checked before `host`, and before any
+ * unknown-axis complaint.** A module using an axis introduced in telo 0.85 also
+ * declares telo `>=0.85`, so an older runtime fails on the telo axis first and
+ * never has to decide what an axis it has never heard of means. That is what
+ * makes the block safely extensible; consumers get the order from
+ * {@link evaluateRequires} rather than re-deriving it.
+ */
+
+import { parseModuleVersion } from "./module-version-order.js";
+import {
+  isUnsatisfiable,
+  parseVersionRange,
+  rangeAccepts,
+  type VersionRange,
+} from "./version-range.js";
+
+/**
+ * Host axes this analyzer knows.
+ *
+ * **An axis is in this list only when something checks it.** A declared
+ * requirement nothing compares is worse than no requirement at all: it validates,
+ * it reads as protection, and it silently protects nobody — the exact failure
+ * class this whole mechanism exists to remove, reintroduced inside it. So `rustc`
+ * is deliberately absent until the slice that builds controller crates can
+ * compare it; adding it there is a one-line change here plus a supplier in
+ * {@link HostVersions}, and until then an author writing it is told it is not a
+ * known axis rather than quietly reassured.
+ *
+ * Extending the set is a telo release, which is exactly why a module using a new
+ * axis must also raise its `telo` bound — and why `telo` is checked first.
+ */
+export const KNOWN_HOST_AXES = ["node"] as const;
+export type HostAxis = (typeof KNOWN_HOST_AXES)[number];
+
+/** Top-level keys of the block. `host` is a container, `telo` a range. */
+const KNOWN_AXES = ["telo", "host"] as const;
+
+export interface RequiresBlock {
+  /** The surface generation range, when declared. */
+  telo?: VersionRange;
+  /** Declared host axes, keyed by axis name. Empty when `host:` is absent. */
+  host: Partial<Record<HostAxis, VersionRange>>;
+}
+
+export interface RequiresIssue {
+  /** Dotted path within the doc, e.g. `requires.telo` or `requires.host.node`. */
+  path: string;
+  message: string;
+  /** The spelling to use instead, when there is an unambiguous one. */
+  hint?: string;
+  /** True for an unrecognized axis, which consumers suppress while the `telo`
+   *  requirement itself is unmet — an older runtime not knowing a newer axis is
+   *  a consequence of the version skew, not a second defect to report. */
+  unknownAxis?: boolean;
+}
+
+export interface ReadRequiresResult {
+  /** Present whenever the doc carries a `requires:` key at all, even a malformed
+   *  one — so a consumer can tell "declared nothing" from "declared badly". */
+  declared: boolean;
+  block: RequiresBlock;
+  issues: RequiresIssue[];
+}
+
+const EMPTY: RequiresBlock = { host: {} };
+
+/**
+ * Read and parse the block off a module doc. Never throws. A malformed entry
+ * yields an issue AND is omitted from the block, so a consumer enforcing the
+ * block never silently treats garbage as a satisfied requirement — the issue is
+ * what makes the manifest fail, exactly as a malformed zone annotation does.
+ */
+export function readRequires(doc: Record<string, unknown> | undefined): ReadRequiresResult {
+  const raw = doc?.requires;
+  if (raw === undefined) return { declared: false, block: EMPTY, issues: [] };
+
+  const issues: RequiresIssue[] = [];
+  const block: RequiresBlock = { host: {} };
+
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    issues.push({
+      path: "requires",
+      message: `'requires' must be a mapping of axes, got ${describe(raw)}.`,
+    });
+    return { declared: true, block, issues };
+  }
+
+  const entries = raw as Record<string, unknown>;
+
+  for (const key of Object.keys(entries)) {
+    if (!(KNOWN_AXES as readonly string[]).includes(key)) {
+      issues.push({
+        path: `requires.${key}`,
+        message:
+          `'requires.${key}' is not a known axis. This runtime knows ` +
+          `${KNOWN_AXES.map((a) => `'${a}'`).join(" and ")}; host requirements go under 'host'.`,
+        unknownAxis: true,
+      });
+    }
+  }
+
+  if (entries.telo !== undefined) {
+    const range = parseRangeAt(entries.telo, "requires.telo", issues);
+    if (range) block.telo = range;
+  }
+
+  if (entries.host !== undefined) {
+    const host = entries.host;
+    if (host === null || typeof host !== "object" || Array.isArray(host)) {
+      issues.push({
+        path: "requires.host",
+        message: `'requires.host' must be a mapping of host axes, got ${describe(host)}.`,
+      });
+    } else {
+      for (const [axis, value] of Object.entries(host as Record<string, unknown>)) {
+        if (!(KNOWN_HOST_AXES as readonly string[]).includes(axis)) {
+          issues.push({
+            path: `requires.host.${axis}`,
+            message:
+              `'requires.host.${axis}' is not a known host axis. This runtime knows ` +
+              `${KNOWN_HOST_AXES.map((a) => `'${a}'`).join(", ")}.`,
+            unknownAxis: true,
+          });
+          continue;
+        }
+        const range = parseRangeAt(value, `requires.host.${axis}`, issues);
+        if (range) block.host[axis as HostAxis] = range;
+      }
+    }
+  }
+
+  return { declared: true, block, issues };
+}
+
+function parseRangeAt(
+  value: unknown,
+  path: string,
+  issues: RequiresIssue[],
+): VersionRange | undefined {
+  const result = parseVersionRange(value);
+  if (!result.ok) {
+    issues.push({ path, message: `'${path}': ${result.error.message}.`, hint: result.error.hint });
+    return undefined;
+  }
+  if (isUnsatisfiable(result.range)) {
+    issues.push({
+      path,
+      message: `'${path}': '${result.range.raw}' admits no version — its bounds exclude each other.`,
+    });
+    return undefined;
+  }
+  return result.range;
+}
+
+/** What a runtime concluded about a module's declared requirements. */
+export type RequiresVerdict =
+  | { satisfied: true }
+  /** An axis whose declared range excludes the version this runtime reported. */
+  | {
+      satisfied: false;
+      axis: "telo" | HostAxis;
+      declared: VersionRange;
+      running: string;
+    };
+
+/** The versions a host can speak for. Absent entries are not checked — the
+ *  editor has no host to report, and an axis nothing supplies is skipped rather
+ *  than guessed. Every axis in {@link KNOWN_HOST_AXES} has a supplier; an axis
+ *  with none does not belong in the vocabulary (see the note there). */
+export interface HostVersions {
+  node?: string;
+}
+
+/**
+ * Evaluate a module's declared requirements against the runtime performing the
+ * analysis.
+ *
+ * `telo` is checked FIRST and short-circuits: a module using a host axis
+ * introduced in a later telo also declares that telo, so an older runtime must
+ * report the version skew rather than a host axis it may not even know. Absent
+ * declarations are satisfied — the bootstrap rule, permanent for everything
+ * published before the mechanism existed.
+ *
+ * **A version this cannot PARSE is satisfied, on every axis.** A runtime that
+ * cannot name its own version must not start rejecting modules on the strength
+ * of a number it could not read — the refusal-to-guess `module-version-order.ts`
+ * makes, pointed in the safe direction. The test is a parse, not a shape: `0.76`
+ * and `2024.1` look like versions and are not three-part ones, so a cheaper
+ * check (a leading digit, say) would fail them CLOSED and gate every module in
+ * the graph on a number nothing could compare. `AnalysisOptions.teloVersion` is
+ * hand-written by definition, so that is exactly where such a value arrives.
+ */
+export function evaluateRequires(
+  block: RequiresBlock,
+  running: string | undefined,
+  host: HostVersions = {},
+): RequiresVerdict {
+  const telo = check("telo", block.telo, running);
+  if (telo) return telo;
+  for (const axis of KNOWN_HOST_AXES) {
+    const verdict = check(axis, block.host[axis], host[axis]);
+    if (verdict) return verdict;
+  }
+  return { satisfied: true };
+}
+
+/** One axis, or `undefined` when it is satisfied / undeclared / unreportable. */
+function check(
+  axis: "telo" | HostAxis,
+  declared: VersionRange | undefined,
+  running: string | undefined,
+): RequiresVerdict | undefined {
+  if (!declared || !running) return undefined;
+  if (!parseModuleVersion(running)) return undefined;
+  if (rangeAccepts(declared, running)) return undefined;
+  return { satisfied: false, axis, declared, running };
+}
+
+function describe(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "an array";
+  return typeof value;
+}

package/src/schema-keywords.ts

@@ -0,0 +1,359 @@
+/**
+ * The JSON Schema vocabulary an author writes inside a manifest, as data.
+ *
+ * WHY THIS EXISTS. A schema-valued slot used to be declared `type: object` and
+ * nothing more, so every surface that reads a kind schema — completion, hover,
+ * the editor's field walk, AJV — knew only "some object". Autocompletion was
+ * dead from the first key, and a typo (`requred:`, `type: 5`) was carried all
+ * the way to a runtime validation failure that named the wrong thing.
+ *
+ * ONE SOURCE, TWO SURFACES. The maps below are the whole vocabulary; the
+ * fragments in `manifest-schemas.ts` are built FROM them, and completion reads
+ * them directly. A second hand-written list is exactly how the IDE's suggestions
+ * and the validator's rules would drift apart.
+ *
+ * WHY THE ANNOTATIONS ARE NOT IN THE VALIDATING FRAGMENT. `x-telo-*` keys are
+ * offered by completion but deliberately never appear as literal property names
+ * in the schema that gets hoisted into a manifest. Several passes walk a
+ * definition's schema testing every object for an annotation KEY
+ * (`resolveSchemaRefKinds`, `validate-ref-slots`, `validate-zone-slots`), and a
+ * `properties` map holding a key spelled `x-telo-ref` reads to them as an
+ * annotated node — inventing diagnostics about a slot the author never wrote.
+ * So the hoisted body stays open (`additionalProperties: true`, which admits
+ * every annotation) and the annotation vocabulary stays here, on the analyzer
+ * side of the boundary, where no manifest walk can reach it.
+ *
+ * Browser-safe: no Node built-ins.
+ */
+
+import { X_TELO_TYPE } from "@telorun/sdk";
+import { ANNOTATION_KEYWORDS } from "./value-type-keyword.js";
+
+/** A keyword entry: the JSON Schema its VALUE must satisfy, carrying the title
+ *  and description completion and hover show. */
+export type SchemaKeywords = Record<string, Record<string, unknown>>;
+
+/** A JSON type name, as `type:` accepts it — one, or a list (`[string, "null"]`,
+ *  the spelling `CEL_NULLABLE_ACCESS` guards). */
+const TYPE_NAME = {
+  type: "string",
+  enum: ["object", "array", "string", "number", "integer", "boolean", "null"],
+};
+
+/**
+ * The draft-07 keywords, as a property map for a fragment named `self`.
+ *
+ * Parameterized by the fragment name because a schema's nested positions hold
+ * schemas of the SAME flavour: a property of a kind schema may carry
+ * annotations, a property of a data schema may not. Both recurse into
+ * themselves, and the document-local pointer is what the hoisting in
+ * `expandManifestFragments` makes resolvable.
+ */
+export function jsonSchemaKeywords(self: string): SchemaKeywords {
+  const schema = { $ref: `#/$defs/${self}` };
+  const schemaList = { type: "array", items: schema };
+
+  return {
+    // Shape
+    type: {
+      title: "Type",
+      description: "The JSON type this value must have, or a list of accepted types.",
+      anyOf: [TYPE_NAME, { type: "array", items: TYPE_NAME }],
+    },
+    properties: {
+      title: "Properties",
+      description: "Schema per named property of an object.",
+      type: "object",
+      additionalProperties: schema,
+    },
+    required: {
+      title: "Required",
+      description: "Property names that must be present.",
+      type: "array",
+      items: { type: "string" },
+    },
+    additionalProperties: {
+      title: "Additional properties",
+      description:
+        "`false` rejects any property not named above — which is what makes a typo an error rather than an ignored field.",
+      anyOf: [{ type: "boolean" }, schema],
+    },
+    patternProperties: {
+      title: "Pattern properties",
+      description: "Schema per regular expression matching a property name.",
+      type: "object",
+      additionalProperties: schema,
+    },
+    propertyNames: {
+      title: "Property names",
+      description: "Schema every property NAME must satisfy.",
+      ...schema,
+    },
+    items: {
+      title: "Items",
+      description: "Schema for each element of an array.",
+      anyOf: [schema, schemaList],
+    },
+    additionalItems: {
+      title: "Additional items",
+      description: "Schema for elements past a positional `items` list.",
+      anyOf: [{ type: "boolean" }, schema],
+    },
+    contains: {
+      title: "Contains",
+      description: "At least one element must satisfy this schema.",
+      ...schema,
+    },
+
+    // Composition
+    allOf: { title: "All of", description: "Every branch must match.", ...schemaList },
+    anyOf: { title: "Any of", description: "At least one branch must match.", ...schemaList },
+    oneOf: {
+      title: "One of",
+      description:
+        "Exactly one branch must match. Prefer `anyOf` when a branch declares a value type — a consumer that does not know the keyword reads the branch as matching everything, and only `anyOf` degrades gracefully.",
+      ...schemaList,
+    },
+    not: { title: "Not", description: "The value must NOT match this schema.", ...schema },
+    if: { title: "If", description: "Condition selecting `then` / `else`.", ...schema },
+    then: { title: "Then", description: "Applied when `if` matches.", ...schema },
+    else: { title: "Else", description: "Applied when `if` does not match.", ...schema },
+
+    // Values
+    enum: { title: "Enum", description: "The complete set of accepted values.", type: "array" },
+    const: { title: "Const", description: "The single accepted value." },
+    default: {
+      title: "Default",
+      description:
+        "Filled in when the value is absent. On an invocation contract this is applied at dispatch, so a caller may omit the field.",
+    },
+    examples: { title: "Examples", description: "Sample values, for documentation.", type: "array" },
+
+    // Numbers
+    minimum: { title: "Minimum", type: "number" },
+    maximum: { title: "Maximum", type: "number" },
+    exclusiveMinimum: { title: "Exclusive minimum", type: "number" },
+    exclusiveMaximum: { title: "Exclusive maximum", type: "number" },
+    multipleOf: { title: "Multiple of", type: "number", exclusiveMinimum: 0 },
+
+    // Strings
+    minLength: { title: "Min length", type: "integer", minimum: 0 },
+    maxLength: { title: "Max length", type: "integer", minimum: 0 },
+    pattern: { title: "Pattern", description: "Regular expression the string must match.", type: "string" },
+    format: {
+      title: "Format",
+      description: "Named string format (`date-time`, `uri`, `email`, …).",
+      type: "string",
+    },
+    contentMediaType: {
+      title: "Content media type",
+      description:
+        "Media type of the string's content (`application/javascript`). Drives the editor's code-widget language.",
+      type: "string",
+    },
+    contentEncoding: { title: "Content encoding", type: "string" },
+
+    // Arrays
+    minItems: { title: "Min items", type: "integer", minimum: 0 },
+    maxItems: { title: "Max items", type: "integer", minimum: 0 },
+    uniqueItems: { title: "Unique items", type: "boolean" },
+
+    // Objects
+    minProperties: { title: "Min properties", type: "integer", minimum: 0 },
+    maxProperties: { title: "Max properties", type: "integer", minimum: 0 },
+    dependencies: {
+      title: "Dependencies",
+      description: "Per property, the other properties it requires — or a schema to apply.",
+      type: "object",
+      additionalProperties: { anyOf: [{ type: "array", items: { type: "string" } }, schema] },
+    },
+
+    // Documentation and structure
+    title: { title: "Title", description: "Human-readable label for this value.", type: "string" },
+    description: {
+      title: "Description",
+      description: "What this value is, for the author reading the manifest.",
+      type: "string",
+    },
+    deprecated: { title: "Deprecated", type: "boolean" },
+    readOnly: { title: "Read only", type: "boolean" },
+    writeOnly: { title: "Write only", type: "boolean" },
+    $ref: {
+      title: "Reference",
+      description:
+        "Pointer to another schema: `#/$defs/<Name>` for one declared below, `telo:<module>/<Type>` for a named type a module declared.",
+      type: "string",
+    },
+    $defs: {
+      title: "Definitions",
+      description: "Named sub-schemas, private to this schema, referenced with `#/$defs/<Name>`.",
+      type: "object",
+      additionalProperties: schema,
+    },
+    definitions: {
+      title: "Definitions (draft-07)",
+      description: "Older spelling of `$defs`.",
+      type: "object",
+      additionalProperties: schema,
+    },
+    $comment: { title: "Comment", type: "string" },
+    $id: { title: "Id", type: "string" },
+    $schema: { title: "Schema dialect", type: "string" },
+  };
+}
+
+/**
+ * The `x-telo-*` annotation vocabulary — completion and hover only.
+ *
+ * TOTAL over {@link ANNOTATION_KEYWORDS} plus `x-telo-type`, which is what makes
+ * it a description of the existing list rather than a second copy of it: adding
+ * an annotation without a completion entry is a compile error here, and the
+ * first draft of this map — hand-written — had already silently dropped four
+ * annotations that live stdlib manifests use.
+ *
+ * Values are intentionally loose. What an annotation MEANS is checked by the
+ * pass that owns it (`validate-ref-slots`, `validate-zone-slots`,
+ * `validate-value-type-slots`), which reports in that annotation's own
+ * vocabulary; restating the shape here would give one mistake two diagnostics
+ * that disagree about what is wrong.
+ *
+ * A KNOWN BLIND SPOT, and not an oversight: several annotations
+ * (`x-telo-context`, `x-telo-error-context`, `x-telo-step-context`) hold JSON
+ * Schema themselves, and cannot be typed by the fragment this file feeds. A
+ * literal `x-telo-*` key inside a hoisted `properties` map reads to the
+ * annotation walkers as an annotated node, so the vocabulary has to stay out of
+ * anything that enters a manifest — which leaves an annotation's VALUE with
+ * neither validation nor completion. Closing it needs the walkers to distinguish
+ * a schema describing an annotation from an annotation, which nothing does yet.
+ */
+export const TELO_SCHEMA_ANNOTATIONS: Record<
+  (typeof ANNOTATION_KEYWORDS)[number] | typeof X_TELO_TYPE,
+  Record<string, unknown>
+> = {
+  "x-telo-eval": {
+    title: "Evaluation mode",
+    description:
+      "When `${{ }}` / `!cel` in this field is evaluated: `compile` at load, `runtime` per invocation. A CEL-bearing field MUST declare one, or the expression is read as a literal.",
+    type: "string",
+    enum: ["compile", "runtime"],
+  },
+  "x-telo-ref": {
+    title: "Reference slot",
+    description:
+      "This field holds a `!ref` to a resource — plus what the declaring resource DOES with it (`use`), which is what every topology analysis reads.",
+    anyOf: [{ type: "string" }, { type: "object" }],
+  },
+  "x-telo-type": {
+    title: "Value type",
+    description:
+      "What the value IS beyond JSON's types: `Telo.Bytes`, `Telo.Stream`, `Telo.TcpPort`, … Optionally parameterized (`{ name: Telo.Stream, of: Telo.Bytes }`).",
+    anyOf: [{ type: "string" }, { type: "object" }],
+  },
+  "x-telo-scope": {
+    title: "Execution scope",
+    description:
+      "JSON Pointer to a region whose `!ref`s resolve against this field's inline resources, created on entry and torn down on exit.",
+    anyOf: [{ type: "string" }, { type: "array", items: { type: "string" } }],
+  },
+  "x-telo-context": {
+    title: "CEL context",
+    description: "The CEL variables in scope inside this field, as a JSON Schema. Analyzer-only.",
+    type: "object",
+  },
+  "x-telo-error-context": {
+    title: "Error context",
+    description: "Schema of the `error` CEL variable inside this field, at any nesting depth.",
+    type: "object",
+  },
+  "x-telo-step-context": {
+    title: "Step context",
+    description:
+      "On a step array: how to build typed `steps.<name>.result` from each item's invoked resource.",
+    type: "object",
+  },
+  "x-telo-schema-from": {
+    title: "Schema from",
+    description: "Derive this field's validation schema from a sibling ref's definition schema.",
+    type: "string",
+  },
+  "x-telo-value-schema-from": {
+    title: "Value schema from",
+    description:
+      "The value here must satisfy the type declared at the named field — checked for EVERY such slot, not only the branch a given input selects.",
+    type: "string",
+  },
+  "x-telo-bindings-from": {
+    title: "Bindings from",
+    description: "Merge the names declared in the named field's map into this field's CEL scope.",
+    type: "string",
+  },
+  "x-telo-context-from": {
+    title: "Context from",
+    description: "Merge the navigated value as a property map into this context node.",
+    type: "string",
+  },
+  "x-telo-context-from-root": {
+    title: "Context from root",
+    description: "Replace this context node's schema with the value navigated from the manifest root.",
+    type: "string",
+  },
+  "x-telo-context-from-ref-kind": {
+    title: "Context from ref kind",
+    description: "Type this node from a referenced kind's declared `inputType` / `outputType`.",
+    type: "string",
+  },
+  "x-telo-context-ref-from": {
+    title: "Context ref from",
+    description: "Type this node from the named manifest's field, falling back to its kind's.",
+    type: "string",
+  },
+  "x-telo-context-element-from": {
+    title: "Context element from",
+    description: "Type this binding from the ELEMENT of a sibling collection expression.",
+    type: "string",
+  },
+  "x-telo-context-collection-from": {
+    title: "Context collection from",
+    description:
+      "Type this binding from a sibling collection expression itself. Withheld when the collection is live — re-exposing a cursor being drained is what no member-access rule catches.",
+    type: "string",
+  },
+  "x-telo-provides-zone": {
+    title: "Provides zone",
+    description:
+      "This resource opens an execution zone; the annotated value is the CORRELATION KEY, never the zone (a zone is identified by the kind that provides it).",
+    anyOf: [{ type: "boolean" }, { type: "string" }],
+  },
+  "x-telo-requires-zone": {
+    title: "Requires zone",
+    description:
+      "This resource must be reached through the named providing kind's body, optionally correlated through an ordered pointer list.",
+    anyOf: [{ type: "string" }, { type: "object" }],
+  },
+  "x-telo-widget": {
+    title: "Editor widget",
+    description: "Render this field with a richer control — `code` gives a Monaco editor.",
+    type: "string",
+    enum: ["code"],
+  },
+  "x-telo-topology-role": {
+    title: "Topology role",
+    description: "Names this field's part in the kind's topology, for the editor's graph view.",
+    type: "string",
+  },
+  "x-telo-inline": {
+    title: "Inline",
+    description: "Renders this field's value inline in the editor rather than behind an accordion.",
+    type: "boolean",
+  },
+  "x-telo-outcome-list": {
+    title: "Outcome list",
+    description: "Marks an array of conditional response-rendering entries (`returns:`).",
+    anyOf: [{ type: "boolean" }, { type: "string" }],
+  },
+  "x-telo-catches-for": {
+    title: "Catches for",
+    description: "Names the field whose failures this branch list handles.",
+    type: "string",
+  },
+};

package/src/schema-region.ts

@@ -20,7 +20,18 @@
  * Browser-safe: no Node built-ins.
  */
 
-/** The kernel's schema-valued manifest keys. */
+/**
+ * The kernel's schema-valued manifest keys.
+ *
+ * TWO CONTAINMENT RULES READ THIS SET, and they are not the same rule. This
+ * file's own {@link isInSchemaRegion} asks "is this node inside a schema" and
+ * answers by ANCESTRY, for the reason argued above. `expandManifestFragments`
+ * asks a different question — "which node will a validator compile, so a
+ * `#/$defs/…` pointer written below it resolves" — and answers by the TOP-LEVEL
+ * key alone, because that is the object handed to AJV; a nested occurrence is a
+ * slot describing a field named `schema`, not a compile root. Neither rule is a
+ * weaker version of the other, so do not "fix" one to match.
+ */
 export const SCHEMA_REGION_KEYS: readonly string[] = [
   "schema",
   "status",

package/src/telo-version.ts

@@ -0,0 +1,9 @@
+// GENERATED by scripts/generate-telo-version.mjs — do not edit.
+//
+// The manifest SURFACE GENERATION this build implements, read from the linked
+// cli/kernel/sdk version. Distinct from this package's own npm version: that is
+// its release identity, this is the scale a module's `requires.telo` range is
+// written against, and every kernel in every language reports the same scale.
+
+/** The surface generation this analyzer implements. */
+export const TELO_SURFACE_VERSION = "0.78.0";

package/src/types.ts

@@ -1,3 +1,5 @@
+import type { HostVersions } from "./requires-block.js";
+
 import type { ZoneModuleDocuments } from "./zone-module-documents.js";
 /** Matches LSP DiagnosticSeverity values exactly.
  *  https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#diagnosticSeverity */
@@ -156,6 +158,36 @@ export interface AnalysisOptions {
    *  (on-disk stamp) attests that the manifests passed a real analyze
    *  pass at the same analyzer / kernel version. */
   skipValidation?: boolean;
+  /** The manifest SURFACE GENERATION the runtime performing this analysis
+   *  implements, against which every module's `requires.telo` range is checked.
+   *
+   *  Defaults to this build's own (`TELO_SURFACE_VERSION`), which is the right
+   *  answer for the kernel, the CLI and the editor alike. In a browser no kernel
+   *  is running, so the only well-posed question is whether the runtime *doing
+   *  the analysis* can read the module — and that is exactly the case where the
+   *  diagnostic is needed, since an editor too old to parse a construct
+   *  otherwise produces vocabulary errors it cannot explain.
+   *
+   *  The kernel deliberately does NOT override with its own package version.
+   *  The constant is generated from the linked kernel version, so the two are
+   *  the same number by construction; where they can drift — a kernel resolving
+   *  an older analyzer than it was released with — the analyzer is the half that
+   *  PARSES, and claiming a generation higher than the bundled parser implements
+   *  would be a claim the stack cannot honour.
+   *
+   *  So this exists for checking against a DIFFERENT target than oneself: a CI
+   *  matrix, or an editor setting naming the version a team deploys on.
+   *
+   *  Defaulted rather than optional-and-silent on purpose: there is no "caller
+   *  forgot to pass it, check silently skipped" path. */
+  teloVersion?: string;
+  /** Versions of the HOST the analysis is being performed for, against which a
+   *  module's `requires.host.*` ranges are checked.
+   *
+   *  Absent in a browser, where there is no host to speak for, and an axis with
+   *  no supplied version is skipped rather than guessed. The kernel and the CLI
+   *  supply it because they are the host. */
+  hostVersions?: HostVersions;
 }
 
 /** Pre-seeded state for incremental analysis. Passed to StaticAnalyzer.analyze() so it does