@telorun/analyzer 0.61.0 → 0.62.1

package/src/identifier-name.ts

@@ -0,0 +1,228 @@
+/**
+ * Naming rules for every author-written Telo identifier — resource instances,
+ * kinds, modules, import aliases, step names, config declarations and CEL
+ * bindings. The single reader, so no surface re-derives the vocabulary; the
+ * `ref-slot.ts` / `zone-slot.ts` precedent.
+ *
+ * **The rules exist because Telo has no lexer.** A name is a YAML scalar, so
+ * nothing rejects its shape where it is declared, and every consequence
+ * surfaces later at a CEL site that references it — or not at all. Probed
+ * against the engine the runtime actually uses (`@marcbachmann/cel-js`):
+ *
+ *     resources.my-server.url  →  EVALUATES, as `resources.my - server.url`
+ *     resources.in             →  ParseError: Expected IDENTIFIER, got IN
+ *     resources.2fa            →  ParseError
+ *     resources.for            →  parses fine
+ *
+ * The first line is the one that decides the design. When a bare name is in
+ * scope — which `x-telo-bindings-from` deliberately makes possible — a
+ * hyphenated resource name yields a wrong number with no diagnostic anywhere.
+ * That is a swallowed error in the reference grammar, not a style preference.
+ * The last line is why the reserved set here is the whole keyword list rather
+ * than the subset today's parser happens to reject in field position: which
+ * keywords tokenize there is a property of a dependency, and a name that
+ * breaks on a parser upgrade was never safe.
+ *
+ * **Three tiers, because they fail in three different ways.**
+ *
+ * 1. `INVALID_NAME` (error, every surface) — not a CEL-safe identifier, or a
+ *    CEL keyword. Below this line the name is unreferenceable or silently
+ *    mis-referenced. This subsumes the old dot-only rule, which was the
+ *    strictest special case of it: `!ref` splits on the first dot.
+ *
+ * 2. `INVALID_TYPE_NAME` (error) — a type-level name not starting uppercase.
+ *    An error rather than a warning because half the reference grammar already
+ *    rejects the alternative: `EXTENDS_ALIAS_PATTERN` in the kernel's manifest
+ *    schema hard-rejects `extends: foo.Bar`, while nothing rejects the
+ *    `metadata.name: foo` that produced it. A lowercase kind is a kind nobody
+ *    can extend, so this only moves an existing failure to where it is
+ *    fixable.
+ *
+ * 3. `NAME_CASE_CONVENTION` (warning) — a value-level name not starting
+ *    lowercase. Warn-only, Rust's `non_snake_case` posture: a name is
+ *    occasionally dictated from outside, and Telo has no `#[allow]`, so a hard
+ *    error would leave no escape.
+ *
+ * **The convention: case encodes what the name denotes.** PascalCase names a
+ * *type* — something writable in `kind:` / `extends:` / an `x-telo-ref` or type
+ * slot. camelCase names a *value* — something holding data at runtime, read
+ * through `resources.` / `steps.` / `variables.` in CEL. That is what
+ * distinguishes `kind: Console.WriteLine` from `!ref Console.writeLine`, two
+ * character-identical grammars otherwise, and the collision is not
+ * hypothetical: it is the sanctioned singleton pattern (declare
+ * `kind: Self.WriteLine`, export the instance, withhold the kind).
+ *
+ * **Only the first character is checked.** A full camelCase pattern would
+ * relitigate `httpApi` vs `httpAPI` and `OAuthClient` vs `OauthClient` with no
+ * benefit — the first character is what carries the type/value signal, and a
+ * stricter rule would fight legitimate names containing acronyms or digits
+ * while owning a judgement nobody asked this pass to make. An
+ * entirely-acronym type name (`SQL`, `AI`) passes unchanged.
+ *
+ * **No `DiagnosticFix`.** A fix is a whole-value replacement for ONE node,
+ * and a rename is only correct when every reference moves with it — offering
+ * one here would rewrite `metadata.name` and break every `!ref` and CEL read
+ * of it. Renaming belongs to a refactor that owns the reference graph.
+ *
+ * Browser-safe: pure string predicates, no I/O, no Node built-ins.
+ */
+
+import { DiagnosticSeverity } from "./types.js";
+
+/**
+ * CEL keywords. A name matching one is unreachable — `true` lexes as a
+ * literal, `in` as an operator — so it is reserved everywhere a name becomes a
+ * CEL identifier, which is every surface this file governs.
+ */
+export const CEL_RESERVED_WORDS: readonly string[] = [
+  "as",
+  "break",
+  "const",
+  "continue",
+  "else",
+  "false",
+  "for",
+  "function",
+  "if",
+  "import",
+  "in",
+  "let",
+  "loop",
+  "namespace",
+  "null",
+  "package",
+  "return",
+  "true",
+  "var",
+  "void",
+  "while",
+];
+
+const RESERVED = new Set(CEL_RESERVED_WORDS);
+
+/** What a CEL identifier may be — and therefore what a name that will be read
+ *  through `resources.` / `steps.` / `variables.` must be. */
+const CEL_IDENTIFIER_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * Which half of the convention a name falls under.
+ *
+ * `type` — a name writable in a `kind:` / `extends:` / type slot: a module, a
+ * kind, an import alias, or a resource whose capability is `Telo.Type` (a
+ * named shape has no runtime instance, so its name denotes a type even though
+ * it is declared as a resource).
+ *
+ * `value` — a name read through a CEL scope: a resource instance, a step, a
+ * `variables` / `secrets` / `ports` declaration, a CEL binding.
+ */
+export type NameLevel = "type" | "value";
+
+/** Document kinds whose `metadata.name` is type-level. Everything else
+ *  declaring a name is a resource instance, whose level is decided by its
+ *  kind's capability (see {@link NameLevel}). */
+export const TYPE_LEVEL_DOC_KINDS: ReadonlySet<string> = new Set([
+  "Telo.Application",
+  "Telo.Library",
+  "Telo.Definition",
+  "Telo.Abstract",
+  "Telo.Import",
+]);
+
+export interface NameViolation {
+  /** Which tier failed. Callers use it to suppress a tier another check
+   *  already reports better at that surface (the bindings site owns
+   *  `reserved`, where it can also say what is being shadowed). */
+  tier: "grammar" | "reserved" | "case";
+  code: "INVALID_NAME" | "INVALID_TYPE_NAME" | "NAME_CASE_CONVENTION";
+  severity: DiagnosticSeverity;
+  /** Complete sentence(s), subject included — so every surface words the same
+   *  rule the same way. */
+  message: string;
+}
+
+/**
+ * Check one author-written name.
+ *
+ * `surface` is the noun phrase naming what was declared ("resource name",
+ * "step name", "import alias"), used as the message's subject.
+ *
+ * Returns the first violation only: the tiers are ordered by how badly the
+ * name is broken, and telling an author their unparseable name is also
+ * miscased buries the part that matters.
+ */
+export function checkName(
+  name: string,
+  level: NameLevel,
+  surface: string,
+): NameViolation | undefined {
+  const subject = `${surface} '${name}'`;
+
+  if (!CEL_IDENTIFIER_RE.test(name)) {
+    return {
+      tier: "grammar",
+      code: "INVALID_NAME",
+      severity: DiagnosticSeverity.Error,
+      message: `${subject} must match /^[A-Za-z_][A-Za-z0-9_]*$/ — ${grammarReason(name, level)}`,
+    };
+  }
+
+  if (RESERVED.has(name)) {
+    return {
+      tier: "reserved",
+      code: "INVALID_NAME",
+      severity: DiagnosticSeverity.Error,
+      message: `${subject} is a CEL keyword, so no expression can reference it. Rename it.`,
+    };
+  }
+
+  const first = name[0]!;
+  if (level === "type" && !(first >= "A" && first <= "Z")) {
+    return {
+      tier: "case",
+      code: "INVALID_TYPE_NAME",
+      severity: DiagnosticSeverity.Error,
+      message:
+        `${subject} must start with an uppercase letter — it names a type, and the ` +
+        `alias-qualified grammar of 'kind:' / 'extends:' accepts only PascalCase.`,
+    };
+  }
+
+  if (level === "value" && !(first >= "a" && first <= "z")) {
+    return {
+      tier: "case",
+      code: "NAME_CASE_CONVENTION",
+      severity: DiagnosticSeverity.Warning,
+      message:
+        `${subject} should start with a lowercase letter — camelCase names a value (read ` +
+        `through a CEL scope), PascalCase names a type.`,
+    };
+  }
+
+  return undefined;
+}
+
+/**
+ * Why the character set is what it is — which differs by level, and saying so
+ * accurately matters more than one shared sentence. A value-level name becomes
+ * a CEL identifier. A type-level name never does: it is a kind prefix or
+ * suffix, so what constrains it is the alias-qualified `<Alias>.<Kind>` grammar
+ * (`EXTENDS_ALIAS_PATTERN` in the kernel's manifest schema), which accepts the
+ * same characters for its own reasons.
+ */
+function grammarReason(name: string, level: NameLevel): string {
+  if (level === "type") {
+    return name.includes(".")
+      ? `a '.' separates the two halves of every '<Alias>.<Kind>' reference, so a dotted name cannot appear in either.`
+      : `that is the character set the alias-qualified '<Alias>.<Kind>' grammar accepts on both sides.`;
+  }
+  if (name.includes("-")) {
+    return (
+      `it becomes a CEL identifier and CEL reads '-' as subtraction, so where a bare name is in ` +
+      `scope this evaluates as arithmetic instead of failing.`
+    );
+  }
+  if (name.includes(".")) {
+    return `in a '!ref' the first '.' separates the import alias from the name.`;
+  }
+  return `it becomes a CEL identifier, so as written it cannot be referenced.`;
+}

package/src/index.ts

@@ -33,6 +33,12 @@ export {
   resolveBindingOrder,
 } from "./cel-bindings.js";
 export type { BindingSites } from "./cel-bindings.js";
+export {
+  CEL_RESERVED_WORDS,
+  TYPE_LEVEL_DOC_KINDS,
+  checkName,
+} from "./identifier-name.js";
+export type { NameLevel, NameViolation } from "./identifier-name.js";
 export {
   applyObservedStateNode,
   buildObservedStateIndex,
@@ -116,6 +122,31 @@ export {
   renderFixReplacement,
 } from "./yaml-source-edit.js";
 export type { QuoteStyle, TextEdit } from "./yaml-source-edit.js";
+export { KNOWN_HOST_AXES, evaluateRequires, readRequires } from "./requires-block.js";
+export type {
+  HostAxis,
+  HostVersions,
+  ReadRequiresResult,
+  RequiresBlock,
+  RequiresIssue,
+  RequiresVerdict,
+} from "./requires-block.js";
+export { TELO_SURFACE_VERSION } from "./telo-version.js";
+export { validateRequires } from "./validate-requires.js";
+export type { ValidateRequiresOptions } from "./validate-requires.js";
+export {
+  isUnsatisfiable,
+  lowerBound,
+  parseVersionRange,
+  rangeAccepts,
+  upperBound,
+} from "./version-range.js";
+export type {
+  ComparatorOperator,
+  VersionComparator,
+  VersionRange,
+  VersionRangeResult,
+} from "./version-range.js";
 export {
   hasProvidesZone,
   hasRequiresZone,
@@ -280,6 +311,9 @@ export type {
     Range
 } from "./types.js";
 export * from "./manifest-schemas.js";
+// The JSON Schema vocabulary a manifest may write, as data — the source both the
+// validating fragments and the IDE's completion are built from.
+export * from "./schema-keywords.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.

package/src/manifest-schemas.ts

@@ -28,6 +28,9 @@
  * and `$ref`-ing it from module schemas. Browser-safe: no Node built-ins.
  */
 
+import { jsonSchemaKeywords } from "./schema-keywords.js";
+import { SCHEMA_REGION_KEYS } from "./schema-region.js";
+
 export const MANIFEST_SCHEMA_URI = "telo://manifest";
 
 /** `$ref` to a fragment in this set, as a module schema writes it. */
@@ -247,6 +250,94 @@ export const InvokeStepSchema = {
   },
 };
 
+/**
+ * A JSON Schema an author writes as a manifest VALUE — an `inputType:`, an
+ * `outputType:`, a `status:` block, an API route's `request.schema`.
+ *
+ * Declared so the surfaces that read a slot's schema learn what lives there. A
+ * slot spelled `type: object` told them "some object": completion offered
+ * nothing from the first key down, hover had nothing to show, and a misspelled
+ * keyword travelled to a runtime failure that named the wrong field.
+ *
+ * OPEN, deliberately (`additionalProperties: true`, `type` admitting the
+ * boolean form a nested `additionalProperties: false` takes). The keyword set
+ * below is draft-07's — the dialect AJV actually runs — and everything outside
+ * it, every `x-telo-*` annotation included, passes through untouched. Closing
+ * this would reject the next annotation the moment a module invented one, for a
+ * check nobody asked for; what it buys as it stands is the value of a keyword
+ * an author DID write (`required: "name"`, `type: 5`) being wrong at
+ * `telo check` rather than at dispatch.
+ *
+ * RECURSIVE, which is why it is not expanded in place like the fragments above
+ * it: a schema's properties hold schemas. `expandManifestFragments` rewrites a
+ * reference to this to the document-local `#/$defs/JsonSchema7` and hoists one
+ * copy to the enclosing schema's root, so the pointer resolves inside whatever
+ * AJV compiles, and the editor's local-only `$ref` resolver keeps working.
+ */
+export const JsonSchema7Schema = {
+  title: "JSON Schema",
+  description: "The shape of a value, as JSON Schema (draft-07).",
+  type: ["object", "boolean"],
+  properties: jsonSchemaKeywords(hoistedDefKey("JsonSchema7")),
+  additionalProperties: true,
+};
+
+/**
+ * The schema a KIND declares for its own configuration — a `Telo.Definition`'s
+ * `schema:` block.
+ *
+ * The same body as {@link JsonSchema7Schema}, under its own name because the
+ * name is the discriminator: a kind's schema is where the `x-telo-*` vocabulary
+ * belongs (`x-telo-eval`, `x-telo-ref`, `x-telo-scope`, …) and a plain data
+ * schema is where it does not. Completion reads the `x-telo-fragment` stamp to
+ * decide which vocabulary to offer, exactly as a retry-budget consumer reads
+ * which of `RetryPolicy` / `RetryAttempts` a slot pointed at.
+ *
+ * The annotations are NOT properties here — see `schema-keywords.ts` for why a
+ * literal `x-telo-*` key inside a hoisted `properties` map would read to the
+ * annotation walkers as a slot the author never wrote.
+ */
+export const KindSchemaSchema = {
+  title: "Kind schema",
+  description:
+    "The configuration a resource of this kind accepts, as JSON Schema plus the `x-telo-*` annotations that say how each field behaves.",
+  type: ["object", "boolean"],
+  properties: jsonSchemaKeywords(hoistedDefKey("KindSchema")),
+  additionalProperties: true,
+};
+
+/** The fragments that describe author-written JSON Schema, whichever vocabulary
+ *  they admit. They are also exactly the RECURSIVE ones — a schema is the only
+ *  shape in this set that contains itself — so a reference to one is localized
+ *  and hoisted rather than expanded in place ({@link localizeRecursiveFragment});
+ *  should a self-containing fragment that is not a schema ever land, the two
+ *  ideas split and this set stays the one about schemas. */
+const SCHEMA_FRAGMENTS = new Set(["JsonSchema7", "KindSchema"]);
+
+/** True when a slot's `x-telo-fragment` stamp says it holds author-written JSON
+ *  Schema — a kind's `schema:`, a `status:` block, a `Telo.JsonSchema`'s own
+ *  `schema`. The one accessor every consumer asks, so no surface re-spells the
+ *  set. */
+export function isSchemaFragment(name: string | undefined): boolean {
+  return name !== undefined && SCHEMA_FRAGMENTS.has(name);
+}
+
+/**
+ * The `$defs` key a hoisted fragment is written under, and the one its own
+ * self-reference points at.
+ *
+ * NAMESPACED so a collision is unrepresentable rather than diagnosable: `$defs`
+ * is the author's namespace, and a kind declaring its own `$defs: { KindSchema:
+ * … }` beside a slot pointing at the fragment would otherwise have its shape
+ * silently validate every such slot — a wrong-but-plausible validation, which is
+ * worse than a loud failure and impossible to see. With a reserved key the two
+ * coexist, and "already present" can only mean a previous hoist of the same
+ * fragment, which is what makes {@link hoistFragmentDef}'s skip provably safe.
+ */
+function hoistedDefKey(name: string): string {
+  return `telo:${name}`;
+}
+
 /** Recursively freeze, so the fragment set cannot be edited through any of the
  *  references handed out. `fragmentFor` clones precisely because downstream
  *  passes rewrite schemas in place — `resolveSchemaRefKinds` rewrites the very
@@ -271,6 +362,8 @@ export const ManifestRootSchema = {
     RetryPolicy: RetryPolicySchema,
     RetryAttempts: RetryAttemptsSchema,
     InvokeStep: InvokeStepSchema,
+    JsonSchema7: JsonSchema7Schema,
+    KindSchema: KindSchemaSchema,
   },
 };
 
@@ -285,6 +378,16 @@ export function manifestFragment(name: string): Record<string, unknown> {
   if (!fragment || typeof fragment !== "object") {
     throw new Error(`Unknown manifest fragment '${name}'`);
   }
+  if (SCHEMA_FRAGMENTS.has(name)) {
+    // A recursive fragment has no expanded form — that is the whole reason it is
+    // localized instead. Embedding one would hand the consumer a body whose
+    // `#/$defs` pointers resolve against nothing.
+    throw new Error(
+      `Manifest fragment '${name}' is recursive and cannot be embedded — ` +
+        `point a slot at it with $ref: "${manifestFragmentRef(name)}" and pass the ` +
+        `enclosing schema through withSchemaFragments().`,
+    );
+  }
   const copy = structuredClone(fragment) as Record<string, unknown>;
   expandManifestFragments(copy);
   copy[X_TELO_FRAGMENT] = name;
@@ -313,27 +416,143 @@ const FRAGMENT_PREFIX = `${MANIFEST_SCHEMA_URI}#/$defs/`;
  * loaded manifest see the same expanded shape.
  */
 export function expandManifestFragments(node: unknown, seen = new Set<object>()): void {
+  if (!node || typeof node !== "object") return;
+  walkFragments(node, seen, { hoistTarget: node as Record<string, unknown>, depth: 0 });
+}
+
+/** Where a hoisted recursive fragment's `$defs` entry goes, and how deep the
+ *  walk is — the two facts {@link walkFragments} carries down. */
+interface ExpandContext {
+  /** The nearest enclosing node AJV will compile as a schema: a document's
+   *  top-level schema-valued key, else the node expansion started from. */
+  readonly hoistTarget: Record<string, unknown>;
+  readonly depth: number;
+}
+
+/**
+ * Descend one key. A TOP-LEVEL schema-valued key (`schema:`, `inputType:`,
+ * `status:`, …) opens a new hoist target, because that node is what a validator
+ * compiles: a `#/$defs/…` pointer written below it resolves against IT, not
+ * against the document. Depth-anchored for the reason migrations anchor `under`
+ * at top-level keys — a slot DESCRIBING a field named `schema` is not itself a
+ * schema region, and treating it as one would scatter `$defs` blocks into the
+ * middle of a kind's property map.
+ */
+function childContext(ctx: ExpandContext, key: string, value: unknown): ExpandContext {
+  if (ctx.depth === 0 && SCHEMA_REGION_KEYS.includes(key) && isPlainObject(value)) {
+    return { hoistTarget: value, depth: 1 };
+  }
+  return { hoistTarget: ctx.hoistTarget, depth: ctx.depth + 1 };
+}
+
+function walkFragments(node: unknown, seen: Set<object>, ctx: ExpandContext): void {
   if (!node || typeof node !== "object") return;
   if (seen.has(node as object)) return;
   seen.add(node as object);
 
   if (Array.isArray(node)) {
     for (let i = 0; i < node.length; i++) {
-      const fragment = fragmentFor(node[i]);
-      if (fragment) node[i] = fragment;
-      else expandManifestFragments(node[i], seen);
+      const localized = localizeRecursiveFragment(node[i], ctx);
+      if (localized) node[i] = localized;
+      else {
+        const fragment = fragmentFor(node[i]);
+        if (fragment) node[i] = fragment;
+        else walkFragments(node[i], seen, { ...ctx, depth: ctx.depth + 1 });
+      }
     }
     return;
   }
 
   const obj = node as Record<string, unknown>;
   for (const [key, value] of Object.entries(obj)) {
+    const localized = localizeRecursiveFragment(value, ctx);
+    if (localized) {
+      obj[key] = localized;
+      continue;
+    }
     const fragment = fragmentFor(value);
     if (fragment) obj[key] = fragment;
-    else expandManifestFragments(value, seen);
+    else walkFragments(value, seen, childContext(ctx, key, value));
+  }
+}
+
+/**
+ * Rewrite a reference to a RECURSIVE fragment to the document-local pointer,
+ * hoisting one copy of the fragment into the enclosing schema's `$defs`.
+ *
+ * Localized rather than inlined because the shape contains itself: inlining
+ * cannot terminate, which is what the "closed, non-recursive set" caveat above
+ * says. Localized rather than left pointing at `telo://manifest` because two
+ * consumers cannot follow a foreign URI — the editor's resolver throws on any
+ * `$ref` that does not start with `#/`, and that throw takes the whole canvas
+ * down, exactly as gating fragment expansion once did.
+ *
+ * Siblings written beside the `$ref` are kept, but draft-07 makes `$ref`
+ * exclusive, so they reach the human surfaces (completion, hover, the editor)
+ * and not AJV. A slot adds a `title` / `description` that way; a slot narrowing
+ * the shape would be silently ignored and should declare its own schema.
+ */
+function localizeRecursiveFragment(
+  value: unknown,
+  ctx: ExpandContext,
+): Record<string, unknown> | undefined {
+  if (!isPlainObject(value)) return undefined;
+  const ref = value.$ref;
+  if (typeof ref !== "string" || !ref.startsWith(FRAGMENT_PREFIX)) return undefined;
+  const name = ref.slice(FRAGMENT_PREFIX.length);
+  if (!SCHEMA_FRAGMENTS.has(name)) return undefined;
+
+  hoistFragmentDef(ctx.hoistTarget, name);
+  return { ...value, $ref: `#/$defs/${hoistedDefKey(name)}`, [X_TELO_FRAGMENT]: name };
+}
+
+/** Add `name` (and anything it references in turn) to `target.$defs`, cloned —
+ *  the fragment set is frozen, and later passes rewrite schemas in place. */
+function hoistFragmentDef(target: Record<string, unknown>, name: string): void {
+  const defs = (target.$defs ??= {}) as Record<string, unknown>;
+  const pending = [name];
+  while (pending.length > 0) {
+    const next = pending.pop() as string;
+    const key = hoistedDefKey(next);
+    if (defs[key]) continue;
+    const fragment = (ManifestRootSchema.$defs as Record<string, unknown>)[next];
+    if (!fragment || typeof fragment !== "object") continue;
+    // Stamped on the hoisted body, not only on the slot that pointed at it: a
+    // schema nests, so the node a consumer resolves two levels down is the
+    // fragment reached through its own self-reference, with no slot in sight.
+    // That node is exactly where an annotation like `x-telo-eval` is written,
+    // so it is where the stamp has to be readable.
+    defs[key] = { ...(structuredClone(fragment) as object), [X_TELO_FRAGMENT]: next };
+    for (const nested of SCHEMA_FRAGMENTS) {
+      if (nested !== next && referencesLocalDef(defs[key], nested)) pending.push(nested);
+    }
   }
 }
 
+/** Does a hoisted fragment point at another one? Cheap and structural: the set
+ *  is small and a missed edge would leave an unresolvable pointer, which AJV
+ *  reports loudly rather than silently skipping. */
+function referencesLocalDef(node: unknown, name: string): boolean {
+  if (!node || typeof node !== "object") return false;
+  if (Array.isArray(node)) return node.some((item) => referencesLocalDef(item, name));
+  const obj = node as Record<string, unknown>;
+  if (obj.$ref === `#/$defs/${hoistedDefKey(name)}`) return true;
+  return Object.values(obj).some((value) => referencesLocalDef(value, name));
+}
+
+/**
+ * Expand fragments in a schema that never passes through the loader —
+ * `builtins.ts` is not a manifest, so its slots have to arrive already
+ * localized, with the hoisted `$defs` at the root of the schema AJV compiles.
+ *
+ * Returns the same object, expanded in place, for use as a declaration
+ * initializer.
+ */
+export function withSchemaFragments<T extends Record<string, unknown>>(schema: T): T {
+  expandManifestFragments(schema);
+  return schema;
+}
+
 /**
  * The fragment a node references, expanded and merged with whatever the node
  * declared beside the `$ref`, or undefined when it references none.

package/src/release/payload-digest.ts

@@ -29,9 +29,13 @@ export const MANIFEST_LAYER = "manifest";
  * Exactly one today, and for a structural reason rather than an omission: the
  * published `layers:` index lives *inside* `telo.yaml`, so it cannot carry that
  * file's own digest — the entry would have to be computed over bytes containing
- * it. Nor can the digest be recovered by hashing what the registry serves, since
- * the transport injects the index at push time and the published text is
- * therefore not the text the payload builder produced.
+ * it. `readPublishedDigests` reads that index, so it has no answer for this key.
+ *
+ * It is no longer *unknowable*, though, only absent from the index: the payload
+ * builder now writes the index, so its manifest is the published text and this
+ * digest is what hashing the served `telo.yaml` yields. Reconciling it would
+ * mean fetching the manifest per module rather than reading one index — worth
+ * doing, and a separate change from the one that made it possible.
  *
  * It stays in the ledger regardless, because it is the only thing that sees a
  * **manifest-only change**: a schema edit, a new kind, a description, a