@telorun/analyzer 0.65.0 → 0.67.0

package/src/ref-slot.ts

@@ -97,6 +97,19 @@ export interface RefSlot {
   /** `x-telo-inline: true` on the slot or any `anyOf` branch — accepts an inline
    *  `{kind, ...config}` definition, not only a `!ref`. */
   inline: boolean;
+  /** The slot's VALUE branches — `anyOf` / `oneOf` alternatives that carry no
+   *  `x-telo-ref`, present only when the reference constraint is itself a
+   *  *branch* rather than the node's own annotation.
+   *
+   *  That narrowing is the whole point. A node-level `x-telo-ref` with branches
+   *  beneath it (an Application `targets` entry) uses those branches to describe
+   *  the POST-RESOLUTION structural forms a reference takes — a bare string
+   *  there is the removed string-reference spelling, and admitting it as a value
+   *  would retire `INVALID_REFERENCE_FORM` exactly where it still applies. A
+   *  branch-level constraint says something different: this slot holds either a
+   *  value of one shape or a reference, and a scalar is then a value, not a
+   *  malformed reference. */
+  valueBranches: Record<string, any>[];
 }
 
 /** Every use a slot can take, flattening a case map. The conservative reading
@@ -173,6 +186,28 @@ function annotationNodes(node: Record<string, any> | undefined): Record<string,
   return out;
 }
 
+/** The branches of a value-or-reference union — see {@link RefSlot.valueBranches}.
+ *  Empty unless the node delegates its reference constraint to a branch. */
+function valueBranchesOf(node: Record<string, any> | undefined): Record<string, any>[] {
+  if (!node || typeof node !== "object") return [];
+  if (node["x-telo-ref"] !== undefined) return [];
+  const out: Record<string, any>[] = [];
+  for (const key of ["anyOf", "oneOf"] as const) {
+    const branches = node[key];
+    if (!Array.isArray(branches)) continue;
+    const carriesRef = branches.some(
+      (b) => b && typeof b === "object" && b["x-telo-ref"] !== undefined,
+    );
+    if (!carriesRef) continue;
+    for (const branch of branches) {
+      if (!branch || typeof branch !== "object") continue;
+      if (branch["x-telo-ref"] !== undefined) continue;
+      out.push(branch as Record<string, any>);
+    }
+  }
+  return out;
+}
+
 /**
  * Reads a schema node as a reference slot, or `undefined` when it declares none.
  *
@@ -210,6 +245,7 @@ export function readRefSlot(node: Record<string, any> | undefined): RefSlot | un
     kinds,
     uses: [...uses],
     inline: node?.["x-telo-inline"] === true || nodes.some((n) => n["x-telo-inline"] === true),
+    valueBranches: valueBranchesOf(node),
   };
   if (useCases) slot.useCases = useCases;
   if (inputs !== undefined) slot.inputs = inputs;

package/src/reference-field-map.ts

@@ -19,6 +19,10 @@ export interface RefFieldEntry {
   inputs?: string;
   /** True when the field path traversed through at least one array (path contains "[]"). */
   isArray: boolean;
+  /** The slot's non-reference branches, when the reference constraint is a
+   *  branch of a union — see {@link RefSlot.valueBranches}. A value satisfying
+   *  one of these is a value, not a malformed reference. */
+  valueBranches?: Record<string, any>[];
   /** x-telo-context schema declared on this ref slot, if any. Describes the CEL invocation
    *  context available to resources placed in this slot. */
   context?: Record<string, any>;
@@ -62,6 +66,43 @@ export function isRefEntry(entry: FieldMapEntry): entry is RefFieldEntry {
   return "refs" in entry;
 }
 
+/** The half of a definition registry this question needs — structural, so the
+ *  field map keeps depending on nothing. */
+export interface ValueBranchValidator {
+  schemaCompileError(schema: Record<string, any>): string | undefined;
+  validateWithRefs(data: unknown, schema: Record<string, any>): string[];
+}
+
+/**
+ * True when a value at a ref slot satisfies one of the slot's VALUE branches —
+ * a storage class beside a `!ref`, so it is a value and not a malformed
+ * reference.
+ *
+ * One implementation, because BOTH reference passes have to narrow the same way:
+ * `validateReferenceForms` would otherwise call it a removed string reference,
+ * and `validateReferences` a reference missing `kind` and `name`. Two copies of
+ * the rule would eventually disagree about which of the two reported a value.
+ *
+ * A branch AJV cannot COMPILE is not a branch the value satisfies.
+ * `validateWithRefs` returns no issues for one — it swallows the compile failure
+ * by design, so one bad schema does not abort the pass — and reading that as
+ * "no issues, therefore a value" would switch the reference-form rule off for
+ * the slot silently. The uncompilable schema is reported on its own definition
+ * by `schemaCompileError`.
+ */
+export function satisfiesValueBranch(
+  value: unknown,
+  branches: readonly Record<string, any>[] | undefined,
+  registry: ValueBranchValidator,
+): boolean {
+  if (!branches?.length) return false;
+  return branches.some(
+    (branch) =>
+      registry.schemaCompileError(branch) === undefined &&
+      registry.validateWithRefs(value, branch).length === 0,
+  );
+}
+
 export function isScopeEntry(entry: FieldMapEntry): entry is ScopeFieldEntry {
   return "scope" in entry;
 }
@@ -234,6 +275,7 @@ function traverseNode(
     };
     if (slot.useCases) entry.useCases = slot.useCases;
     if (slot.inputs !== undefined) entry.inputs = slot.inputs;
+    if (slot.valueBranches.length > 0) entry.valueBranches = slot.valueBranches;
     if (node["x-telo-context"]) entry.context = node["x-telo-context"] as Record<string, any>;
     if (slot.inline) entry.inline = true;
     map.set(path, entry);

package/src/referrer-rule.ts

@@ -37,6 +37,23 @@ export interface ReferrerRule {
    * relation the rule is about, so a kind should write it.
    */
   readonly referrer?: string;
+  /**
+   * JSON Pointer to a collection OF THE REFERRER to resolve — the binding that
+   * lets a rule state a relation between SIBLING declarations, which neither a
+   * resource rule (one resource) nor a plain referrer rule (a pair joined by one
+   * reference) can reach.
+   *
+   * Declaring it binds `peers` (the collection's OTHER entries) and `entry` (my
+   * own), and makes the rule evaluate once per entry rather than once per
+   * referrer: a rule reading `entry` is about the entry, and a resource listed
+   * twice has two entries to answer for.
+   *
+   * Entries bind AS WRITTEN with the references *inside them* resolved one level
+   * — `p` is the declaration where the entry is a bare `!ref`, `p.mount` is the
+   * declaration with `p.prefix` beside it where it is not. Nothing is guessed
+   * from the item schema and there is no second pointer to write.
+   */
+  readonly peers?: string;
   /** CEL source. TRUE when the rule holds. */
   readonly condition: string;
   /** The rule's own name, carried in `data.rule`. Never a diagnostic code —
@@ -68,15 +85,17 @@ export function readReferrerRules(schema: unknown): ReferrerRule[] {
   raw.forEach((entry, index) => {
     if (!isObject(entry)) return;
     const condition = celSourceOf(entry.condition);
-    const { code, message, referrer } = entry;
+    const { code, message, referrer, peers } = entry;
     if (!condition || typeof code !== "string" || typeof message !== "string") return;
     if (code.length === 0 || message.length === 0) return;
     if (referrer !== undefined && typeof referrer !== "string") return;
+    if (peers !== undefined && typeof peers !== "string") return;
     if (entry.severity !== undefined && entry.severity !== "warning" && entry.severity !== "error") {
       return;
     }
     rules.push({
       ...(referrer === undefined ? {} : { referrer }),
+      ...(peers === undefined ? {} : { peers }),
       condition,
       code,
       message,

package/src/release/index.ts

@@ -2,7 +2,7 @@
  * The release model: module identity, fragments, the ledger, the edge graph,
  * level propagation and version planning.
  *
- * Browser-safe by construction — pure data in, plan out — so the telo editor can
+ * Browser-safe by construction — pure data in, plan out — so telo studio can
  * answer "what does changing this library bump?" from the same model the CLI
  * releases from. Everything Node-shaped (finding the workspace, running the
  * controller builder, building payloads, reading git, writing files) is

package/src/resolve-ref-sentinels.ts

@@ -193,7 +193,18 @@ export function resolveRefSentinels(
 
   for (const r of resources) {
     if (isForeign(r)) continue;
-    if (!r.metadata?.name || !r.kind || SYSTEM_KINDS.has(r.kind)) continue;
+    if (!r.metadata?.name || !r.kind) continue;
+    // A `Telo.Import` is import-time metadata, not a resource instance — except
+    // for its `resources:` block, which supplies the instances the target
+    // library declared it needs. Those are `!ref`s to the importer's OWN
+    // resources and resolve exactly like any other reference; nothing else on
+    // the document is a reference slot, so only that subtree is walked.
+    if (r.kind === "Telo.Import") {
+      const supplied = (r as Record<string, unknown>).resources;
+      if (supplied) (r as Record<string, unknown>).resources = walk(supplied);
+      continue;
+    }
+    if (SYSTEM_KINDS.has(r.kind)) continue;
     walk(r as Record<string, unknown>);
   }
 }

package/src/resource-input.ts

@@ -0,0 +1,132 @@
+import type { ResourceManifest } from "@telorun/sdk";
+
+/**
+ * The `resources:` block on a `Telo.Library` — the instances a library requires
+ * from whoever imports it, beside the scalar `variables:` / `secrets:` blocks.
+ * Instances used to flow up only (`exports.resources`); this is the inward half.
+ *
+ * THE SINGLE READER of the block, in both halves (the analyzer's passes and the
+ * kernel's import controller), on the `ref-slot.ts` precedent: a boundary whose
+ * shape two runtimes must agree about is read in one place, so the next shape
+ * change is a one-file edit rather than four surfaces recognising a block by
+ * pattern-matching it.
+ *
+ * Browser-safe — no I/O, no Node built-ins.
+ */
+
+/** One declared input. */
+export interface ResourceInput {
+  /** The entry key. Inside the library the instance is named exactly as a
+   *  locally declared resource: `!ref <name>` at a ref slot, `resources.<name>`
+   *  in CEL. */
+  name: string;
+  /** The alias-qualified kind constraint, as written in the DECLARING library's
+   *  own scope (`Sql.Connection`, `Self.Store`, `Telo.LogSink`). There is no
+   *  `use:` here: the boundary is a dependency edge for init order whatever the
+   *  library does with the instance, and the flattened application analysis
+   *  drops the library doc, so an app-level claim about internal call sites is
+   *  one nothing could check. */
+  kind: string;
+  description?: string;
+}
+
+/** Marker stamped on a synthesized kind-only declaration (see
+ *  {@link injectedDeclarations}). Read through {@link isInjectedDeclaration} —
+ *  never by testing the field. */
+const INJECTED = "xTeloInjected";
+
+/** Read a module document's `resources:` block. Returns `[]` for an
+ *  `Telo.Application` (which has no such block), for a library that declares
+ *  none, and for a malformed entry — the document's own schema validation
+ *  reports the shape against the precise `resources.<name>` path. */
+export function readResourceInputs(moduleDoc: unknown): ResourceInput[] {
+  const raw = (moduleDoc as { resources?: unknown } | undefined)?.resources;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return [];
+  const out: ResourceInput[] = [];
+  for (const [name, value] of Object.entries(raw as Record<string, unknown>)) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+    const kind = (value as { kind?: unknown }).kind;
+    if (typeof kind !== "string" || kind.length === 0) continue;
+    const description = (value as { description?: unknown }).description;
+    out.push({
+      name,
+      kind,
+      ...(typeof description === "string" ? { description } : {}),
+    });
+  }
+  return out;
+}
+
+/** The values an import supplies for a target library's declared inputs, keyed
+ *  by entry name. Read off a `Telo.Import` (authored or desugared from an
+ *  `imports:` entry). Values are `!ref` sentinels before Phase 2.5 and
+ *  `{kind, name}` after it — this reader does not interpret them. */
+export function readSuppliedResources(importDoc: unknown): Record<string, unknown> {
+  const raw = (importDoc as { resources?: unknown } | undefined)?.resources;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+  return raw as Record<string, unknown>;
+}
+
+/** True when `manifest` is a synthesized kind-only declaration standing in for a
+ *  library's `resources:` entry rather than a resource the author declared. */
+export function isInjectedDeclaration(manifest: ResourceManifest | undefined): boolean {
+  return (manifest?.metadata as Record<string, unknown> | undefined)?.[INJECTED] === true;
+}
+
+/**
+ * Synthesize a kind-only declaration per `resources:` entry, in the declaring
+ * library's own scope.
+ *
+ * That model has to exist because a library's internals are validated in the
+ * library's own pass — the flattened application analysis drops the library doc
+ * — so with nothing behind `connection`, `!ref connection` would have nothing to
+ * resolve against.
+ *
+ * Kind-only is enough because it is already what a ref slot gets: a reading
+ * types its `status:` half from the kind, closed so a typo below it is
+ * `CEL_UNKNOWN_FIELD`, and leaves the flat half open, since no manifest declares
+ * what `snapshot()` returned. So `!ref connection` at a ref slot and
+ * `resources.connection.<field>` in CEL answer exactly as they do for a locally
+ * declared resource.
+ *
+ * The declaration is a stand-in, never an instantiation: the per-resource
+ * validation loop skips it (its kind is routinely an abstract, and its config is
+ * the importer's to supply), and the kernel's import controller filters it out
+ * of the manifests it registers, binding the borrowed instance under the name
+ * instead.
+ */
+export function injectedDeclarations(
+  moduleDoc: ResourceManifest,
+  ownModule: string | undefined,
+): ResourceManifest[] {
+  const inputs = readResourceInputs(moduleDoc);
+  if (inputs.length === 0) return [];
+  const meta = moduleDoc.metadata as
+    | { source?: string; sourceLine?: number }
+    | undefined;
+  return inputs.map((input) => ({
+    kind: input.kind,
+    metadata: {
+      name: input.name,
+      ...(ownModule ? { module: ownModule } : {}),
+      source: meta?.source ?? "",
+      sourceLine: meta?.sourceLine ?? 0,
+      [INJECTED]: true,
+    },
+  })) as unknown as ResourceManifest[];
+}
+
+/** How many times a library is instantiated in one application. `isolated` —
+ *  the default, and what every published module was written against — gives
+ *  each import declaration its own child scope with its own instances;
+ *  `shared` makes the library a singleton every import resolves to. */
+export type LibraryLifecycle = "isolated" | "shared";
+
+/** Read a module document's `lifecycle:`. `Telo.Application` has a field of the
+ *  same name with a different default and no reader; this is the LIBRARY
+ *  question only, so it answers `isolated` for anything else. */
+export function readLibraryLifecycle(moduleDoc: unknown): LibraryLifecycle {
+  const doc = moduleDoc as { kind?: unknown; lifecycle?: unknown } | undefined;
+  if (doc?.kind !== "Telo.Library") return "isolated";
+  return doc.lifecycle === "shared" ? "shared" : "isolated";
+}

package/src/resource-rule.ts

@@ -21,6 +21,7 @@
  *
  * Browser-safe: no Node built-ins.
  */
+import { CEL_ENGINE, isRefSentinel, isTaggedSentinel } from "@telorun/templating";
 
 export const RESOURCE_RULES_ANNOTATION = "x-telo-resource-rules";
 
@@ -58,9 +59,42 @@ function isObject(value: unknown): value is Record<string, unknown> {
  *  Both markers are tested because they are not always both present: a
  *  registered definition's schema reaches the analyzer with `call` and
  *  `__compiled` dropped, keeping only `__tagged` + `source`. Testing one would
- *  make a rule readable on some paths and invisible on others. */
+ *  make a rule readable on some paths and invisible on others.
+ *
+ *  A tagged sentinel of ANOTHER engine is not one. `__tagged` marks every tag
+ *  the loader parses — `!ref` above all — so testing it alone read a reference
+ *  as an expression: a column whose `type:` holds a `!ref` skipped every rule
+ *  that touched `self.columns`, and said "the value holds a CEL expression" about
+ *  a manifest containing none. A reference names a declaration and is a
+ *  perfectly comparable value; what a rule cannot compare is a value COMPUTED at
+ *  create time, which is what this predicate exists to find. */
 function isCelNode(value: unknown): value is { source?: unknown } {
-  return isObject(value) && (value.__compiled === true || value.__tagged === true);
+  if (!isObject(value)) return false;
+  if (value.__compiled === true) return true;
+  return value.__tagged === true && value.engine === CEL_ENGINE;
+}
+
+/** The engine of a non-CEL tagged sentinel — a `!ref`, an `!include-*` — or
+ *  `undefined`. A reference is comparable and never blocks a rule; the other
+ *  tags hold a value only known once the resource is created, so they do, and
+ *  the diagnostic has to name the tag rather than claim CEL. */
+export function deferredTagOf(value: unknown): string | undefined {
+  if (!isTaggedSentinel(value) || isRefSentinel(value)) return undefined;
+  return value.engine === CEL_ENGINE ? undefined : value.engine;
+}
+
+/**
+ * True when a condition was written with the `!cel` tag.
+ *
+ * The readers stay lenient and take a bare string — a rule still runs either
+ * way. What an untagged condition loses is everything outside evaluation: to the
+ * editor's colouring, completion and hover it is a plain string, so a rule author
+ * writes CEL with no help and gets none of the checks a `!cel` scalar gets.
+ * Losing that silently is exactly what a strict half exists to move earlier, so
+ * the tag is reported by the strict halves and never enforced by the readers.
+ */
+export function isTaggedCondition(value: unknown): boolean {
+  return isCelNode(value);
 }
 
 /** A precompiled `!cel` node keeps its author-written text on `source`; a plain
@@ -179,17 +213,45 @@ export function resolveRuleSubjects(
   return undefined;
 }
 
+/** The first leaf a rule cannot compare, and what it is. `what` is a noun
+ *  phrase the diagnostic quotes verbatim, because "a CEL expression" printed
+ *  over an `!include-bytes` embed sends its author looking for an expression
+ *  that is not there. */
+export interface DynamicLeaf {
+  readonly path: string;
+  readonly what: string;
+}
+
+/** Classify ONE node, without descending. Exported because a caller that draws
+ *  its own bound on how far to look (`peer-binding`'s top-level-scalar scan)
+ *  must classify by the same rule as the recursive walk, or a `!ref` is a
+ *  reference to one of them and an expression to the other. */
+export function dynamicNode(value: unknown, path: string): DynamicLeaf | undefined {
+  const at = path || "(value)";
+  if (isCelNode(value)) return { path: at, what: "a CEL expression" };
+  const tag = deferredTagOf(value);
+  return tag ? { path: at, what: `an !${tag} embed` } : undefined;
+}
+
 /**
- * Path of the first CEL leaf inside a value, or `undefined` when every leaf is
- * literal. A rule reading an expression would be evaluating a placeholder, so
- * the subject is skipped — and the skip is reported, never silent.
+ * The first leaf inside a value whose contents are not known until the resource
+ * is created, or `undefined` when every leaf is literal. A rule reading one
+ * would be comparing against a placeholder, so the subject is skipped — and the
+ * skip is reported, never silent.
+ *
+ * A `!ref` is NOT one of them. It is a tagged sentinel like `!cel`, and testing
+ * `__tagged` alone read every reference as an expression: a column whose `type:`
+ * holds a `!ref` switched off every rule touching `self.columns` and reported a
+ * CEL expression in a manifest containing none. A reference names a declaration
+ * — a value a rule compares perfectly well, and the one peer rules are built on.
  *
  * Stops at nested inline `{ kind }` declarations for the reason every other walk
  * does: that CEL belongs to the nested kind, evaluated in its own scope.
  */
-export function findDynamicLeaf(value: unknown, base = ""): string | undefined {
+export function findDynamicLeaf(value: unknown, base = ""): DynamicLeaf | undefined {
   if (isObject(value)) {
-    if (isCelNode(value)) return base || "(value)";
+    const own = dynamicNode(value, base);
+    if (own) return own;
     if (typeof value.kind === "string" && base !== "") return undefined;
     for (const [key, child] of Object.entries(value)) {
       const found = findDynamicLeaf(child, base === "" ? key : `${base}.${key}`);

package/src/rule-condition.ts

@@ -32,6 +32,21 @@ import {
  */
 export const RULE_BUDGET_MS = 50;
 
+/**
+ * The one message for an untagged `condition:`, shared by every rule family so
+ * all of them say the same thing about the same defect.
+ *
+ * The readers stay lenient and a bare string still runs. What it loses is
+ * everything outside evaluation — to the editor's colouring, completion and
+ * hover an untagged condition is a plain string, so its author writes CEL with
+ * no help and none of the checks a `!cel` scalar gets. Losing that silently is
+ * the failure a strict half exists to move earlier.
+ */
+export const UNTAGGED_CONDITION =
+  "Write 'condition' with the !cel tag. The reader is lenient and a bare string still " +
+  "runs, but untagged the expression is not CEL to the editor's colouring, completion " +
+  "or hover, so a rule silently stops being CEL to every surface but this one.";
+
 const HOST_BACKED = new Set(CEL_FUNCTIONS.filter((f) => f.hostBacked).map((f) => f.name));
 const NON_DETERMINISTIC = new Set(
   CEL_FUNCTIONS.filter((f) => !f.deterministic).map((f) => f.name),