@telorun/analyzer 0.63.0 → 0.65.0

package/dist/cel-scope.js

@@ -0,0 +1,377 @@
+import { bindingContextProperties, bindingPathChain, BINDINGS_ANNOTATION, schemaAtChain, } from "./cel-bindings.js";
+import { buildImportInputCelEnvironment, buildTypedCelEnvironment } from "./cel-environment.js";
+import { effectiveAuthorSchema } from "./extends-resolution.js";
+import { analyzerContractScope, PERMISSIVE_CONTRACT, resolveContract, } from "./invocation-contract.js";
+import { mergeKernelGlobalsIntoContext, } from "./kernel-globals.js";
+import { resolveLocalRef, walkStepArray } from "./schema-walk.js";
+import { readStepSlot } from "./step-slot.js";
+import { getManifestItem, resolveContextAnnotations, resolveTypeFieldToSchema, } from "./validate-cel-context.js";
+/** Build a closed JSON Schema for the `self` CEL variable available inside a
+ *  `Telo.Definition` template body. Mirrors the runtime template controller's
+ *  `const self = { ...resource, name: resource.metadata.name };` — every
+ *  property the user declared in `schema:` plus synthetic `name` / `kind` and
+ *  the metadata sub-object (kept open since metadata legitimately carries
+ *  arbitrary user-added fields). */
+function buildSelfSchema(definition, defs, aliases) {
+    // The author-facing schema resolves inheritance: with `base:` the child's own
+    // schema (the parent's config is internal); without it, `merge(parent, own)`.
+    const userSchema = (defs
+        ? effectiveAuthorSchema(definition, (k) => defs.resolve(aliases?.resolveKind(k) ?? k) ?? defs.resolve(k))
+        : (definition.schema ?? {}));
+    const userProps = (userSchema.properties ?? {});
+    const userRequired = Array.isArray(userSchema.required) ? userSchema.required : [];
+    return {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+            ...userProps,
+            name: { type: "string" },
+            kind: { type: "string" },
+            metadata: {
+                type: "object",
+                additionalProperties: true,
+                properties: { name: { type: "string" } },
+            },
+        },
+        required: [...userRequired, "name", "kind"],
+    };
+}
+/** Build the JSON Schema for the `inputs` CEL variable available inside an
+ *  invocable template body — the shared contract resolver applied to the
+ *  definition itself, so a body is typed against the exact signature callers are
+ *  checked against and dispatch enforces. Walks the whole `extends` chain rather
+ *  than one hop, so a definition two levels below the declaration still gets
+ *  typed inputs. Undefined when nothing in the chain declares a contract —
+ *  the caller signals opaque `map<string, dyn>` upstream. */
+function lookupTemplateInputsSchema(definition, defs, aliases, allManifests, scopes) {
+    return resolveContract("inputType", undefined, definition, analyzerContractScope(defs, aliases, scopes, allManifests))?.schema;
+}
+/** Returns a "resolver-facing" view of the manifest where the fields used as
+ *  navigation roots by Telo.Definition's `x-telo-context-from-root` annotations
+ *  have been pre-augmented:
+ *    - `schema`     → augmented `self` schema (synthetic `name`/`kind`/metadata).
+ *    - `inputType`  → resolved through the shared contract resolver, so
+ *                     `x-telo-context-from-root: inputType` substitutes the
+ *                     real signature. Without it the annotation would replace
+ *                     the node verbatim with the inline `{kind, schema}` wrapper
+ *                     the standard library writes everywhere, typing `inputs` as
+ *                     `{kind, schema}` instead of the declared properties.
+ *
+ *  For non-definition manifests the original object is returned. */
+export function manifestRootForResolver(m, defs, aliases, allManifests, scopes) {
+    if (m.kind !== "Telo.Definition")
+        return m;
+    const inputs = lookupTemplateInputsSchema(m, defs, aliases, allManifests, scopes);
+    return {
+        ...m,
+        schema: buildSelfSchema(m, defs, aliases),
+        ...(inputs ? { inputType: inputs } : {}),
+    };
+}
+/**
+ * Build a `steps` context schema for a kind's step body.
+ * Walks each step in the manifest array, resolves the invoked resource's output
+ * contract, and builds `steps.<name>.result` context entries.
+ *
+ * Resolution is the shared {@link resolveContract} — the invoked resource
+ * manifest's own declaration, then the kind's, resolved to the nearest
+ * declaration along `extends`, then permissive. Sharing it with the kernel is
+ * what stops `telo check` from typing `steps.X.result` against one contract
+ * while dispatch validates against another.
+ *
+ * The kind layer is what makes `x-telo-stream` properties on definitions
+ * actually govern step-result chain validation — without it, the validator falls
+ * back to permissive and the stream-opacity rule never fires.
+ *
+ * Recursion into nested step arrays is annotation-driven via
+ * `x-telo-topology-role`. The analyzer recognises three role values:
+ *   - `branch`     — value is an array of steps (e.g. then / else / do / catch).
+ *   - `branch-list`— value is an array of objects each carrying further roled
+ *                    sub-properties (e.g. elseif: [{ if, then }]).
+ *   - `case-map`   — value is an object whose values are step arrays (e.g. cases).
+ * No specific Run.Sequence field name is hardcoded; any kind that uses
+ * a step body and tags its branch fields with these roles works.
+ */
+export function buildStepContextSchema(manifest, defSchema, allManifests, defs, aliases, scopes) {
+    const props = defSchema.properties;
+    if (!props)
+        return undefined;
+    const contractScope = analyzerContractScope(defs, aliases, scopes, allManifests);
+    const readingModule = manifest.metadata?.module;
+    for (const [fieldName, fieldSchema] of Object.entries(props)) {
+        const stepCtx = readStepSlot(fieldSchema);
+        if (!stepCtx)
+            continue;
+        const invokeField = stepCtx.invoke;
+        const outputTypeField = stepCtx.outputType;
+        // Optional: the field a step uses to produce a result without dispatching.
+        // Only a kind that declares one has pure steps at all.
+        const valueField = stepCtx.value;
+        if (!invokeField || !outputTypeField)
+            continue;
+        const steps = manifest[fieldName];
+        if (!Array.isArray(steps))
+            continue;
+        const stepItemSchema = resolveLocalRef(fieldSchema.items, defSchema);
+        // The instance's own input contract, for typing a pure step that just
+        // forwards one of its values.
+        const ownInputs = resolveTypeFieldToSchema(manifest.inputType, allManifests);
+        const stepProperties = {};
+        walkStepArray(steps, stepItemSchema, defSchema, fieldName, (s) => {
+            const name = s.name;
+            const invoke = s[invokeField];
+            // Only invoke steps register a `steps.<name>.result` entry — control-flow
+            // wrappers (try/if/while/switch/throw) don't produce a result and must
+            // not shadow real entries with a permissive `additionalProperties: true`,
+            // or unknown step references slip through chain validation.
+            if (typeof name !== "string")
+                return;
+            if (!invoke || typeof invoke !== "object") {
+                // A pure step dispatches nothing, so there is no contract to resolve.
+                // Where its expression is a plain chain into something already typed —
+                // an earlier step's result, or the kind's own inputs — that type carries
+                // through; anything else (arithmetic, a call, a comprehension) stays
+                // permissive rather than guessed. Same rule as a named binding's.
+                if (valueField && valueField in s) {
+                    const scopeRoot = {
+                        properties: {
+                            steps: { type: "object", properties: { ...stepProperties } },
+                            ...(ownInputs ? { inputs: ownInputs } : {}),
+                        },
+                    };
+                    const chained = schemaAtChain(bindingPathChain(s[valueField]), scopeRoot);
+                    stepProperties[name] = {
+                        type: "object",
+                        properties: { result: chained ?? PERMISSIVE_CONTRACT },
+                    };
+                }
+                return;
+            }
+            const invokedKind = invoke.kind;
+            const invokedName = invoke.name;
+            // A named `!ref` carries the target's own manifest (which may narrow the
+            // contract for this one instance); an inline `{ kind, ... }` step IS the
+            // manifest. Either way the kind layer resolves through `extends`.
+            const invokedManifest = invokedName
+                ? allManifests.find((m) => m.metadata?.name === invokedName && (!invokedKind || m.kind === invokedKind))
+                : invoke;
+            const invokedDef = invokedKind
+                ? contractScope.resolveIn(invokedKind, readingModule)
+                : undefined;
+            const outputSchema = resolveContract(outputTypeField, invokedManifest, invokedDef, contractScope)?.schema;
+            stepProperties[name] = {
+                type: "object",
+                properties: {
+                    result: outputSchema ?? PERMISSIVE_CONTRACT,
+                },
+            };
+        });
+        if (Object.keys(stepProperties).length > 0) {
+            return {
+                type: "object",
+                properties: stepProperties,
+            };
+        }
+    }
+    return undefined;
+}
+export function collectErrorContextScopes(defSchema) {
+    const out = new Map();
+    if (!defSchema || typeof defSchema !== "object")
+        return out;
+    const seen = new Set();
+    const walk = (schema) => {
+        if (!schema || typeof schema !== "object" || seen.has(schema))
+            return;
+        seen.add(schema);
+        const props = schema.properties;
+        if (props) {
+            for (const [fieldName, fieldSchema] of Object.entries(props)) {
+                if (fieldSchema && typeof fieldSchema === "object") {
+                    const errCtx = fieldSchema["x-telo-error-context"];
+                    if (errCtx && typeof errCtx === "object" && !out.has(fieldName)) {
+                        out.set(fieldName, errCtx);
+                    }
+                }
+                walk(resolveLocalRef(fieldSchema, defSchema));
+            }
+        }
+        if (schema.items)
+            walk(resolveLocalRef(schema.items, defSchema));
+        for (const key of ["oneOf", "anyOf", "allOf"]) {
+            const arr = schema[key];
+            if (Array.isArray(arr))
+                for (const sub of arr)
+                    walk(resolveLocalRef(sub, defSchema));
+        }
+        if (schema.$defs && typeof schema.$defs === "object") {
+            for (const sub of Object.values(schema.$defs)) {
+                walk(sub);
+            }
+        }
+    };
+    walk(defSchema);
+    return out;
+}
+/**
+ * Return the error-context schema for a CEL `path` when the path lies within
+ * (any depth under) one of the error-bearing fields, else undefined. A path is
+ * "within" field `f` when it contains a segment `f[<index>]`. When multiple
+ * error-bearing fields match (e.g. a `finally` nested inside a `catch`), the
+ * deepest — the one whose segment appears latest in the path — wins, so the
+ * innermost branch's schema governs.
+ */
+export function errorContextForPath(path, scopes) {
+    let best;
+    for (const [fieldName, schema] of scopes) {
+        const escaped = fieldName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        for (const match of path.matchAll(new RegExp(`(^|\\.)${escaped}\\[\\d+\\]`, "g"))) {
+            if (best === undefined || match.index > best.index) {
+                best = { index: match.index, schema };
+            }
+        }
+    }
+    return best?.schema;
+}
+/** Add a kind's named bindings to a resolved context, when the context declares
+ *  a bindings region. They go UNDER the context's own properties: a scope
+ *  variable wins over a same-named binding at runtime, so static typing has to
+ *  agree (the collision itself is `BINDING_NAME_RESERVED`). */
+export function withBindingNames(contextSchema, resource) {
+    const field = contextSchema[BINDINGS_ANNOTATION];
+    if (typeof field !== "string")
+        return contextSchema;
+    const bindings = resource[field];
+    if (bindings === null || typeof bindings !== "object" || Array.isArray(bindings)) {
+        return contextSchema;
+    }
+    return {
+        ...contextSchema,
+        properties: {
+            ...bindingContextProperties(bindings, contextSchema),
+            ...(contextSchema.properties ?? {}),
+        },
+    };
+}
+/**
+ * The CEL scope rule, applied per resource and then per expression.
+ *
+ * Stateful across a resource because the per-resource half — the step context,
+ * the error-bearing regions, the invocation context — is derived from the kind's
+ * schema once and read by every expression in that resource. `enterResource`
+ * establishes it; `scopeFor` answers for one path.
+ */
+export class CelScopeResolver {
+    inputs;
+    typedEnvByManifest = new Map();
+    /** Per-resource state, replaced at each `enterResource`. */
+    stepContext;
+    invocationContext;
+    errorScopes = new Map();
+    constructor(inputs) {
+        this.inputs = inputs;
+    }
+    /** The `steps` context schema for the current resource, or undefined when its
+     *  kind declares no step body. Exposed because the step-inputs check needs the
+     *  same schema this resource's expressions are typed against — recomputing it
+     *  there is how the two would come to disagree. */
+    get stepContextSchema() {
+        return this.stepContext;
+    }
+    /** The error-bearing regions the current resource's kind declares. */
+    get errorContextScopes() {
+        return this.errorScopes;
+    }
+    /** The resource-wide invocation context, when this resource is an inline
+     *  declaration that carries one. Read by the "CEL in a non-eval field" check:
+     *  such a resource's CEL is evaluated by the enclosing kind, not by an
+     *  `x-telo-eval` annotation of its own. */
+    get invocationContextSchema() {
+        return this.invocationContext;
+    }
+    /** Establish the per-resource half of the scope. */
+    enterResource(m, definition) {
+        const { allManifests, defs, aliases, scopes } = this.inputs;
+        this.invocationContext = m.metadata?.xTeloInvocationContext;
+        this.stepContext = definition?.schema
+            ? buildStepContextSchema(m, definition.schema, allManifests, defs, aliases, scopes)
+            : undefined;
+        this.errorScopes = collectErrorContextScopes(definition?.schema);
+    }
+    /**
+     * What the expression at `site` is typed against.
+     *
+     * The environment is cached per manifest when no context applied, which is
+     * most expressions: it then depends only on the manifest, so rebuilding it per
+     * expression is pure waste — a clone plus a re-registration of every variable,
+     * on every keystroke in the IDE. A matched context makes it path-specific (its
+     * schema is resolved against the enclosing array item), so those build fresh
+     * rather than risk one item's types leaking into another's.
+     */
+    scopeFor(site) {
+        const m = site.source;
+        const contextSchema = this.resolveContextFor(site);
+        const { celEnv, allManifests, moduleManifest, } = this.inputs;
+        const cached = contextSchema === null ? this.typedEnvByManifest.get(m) : undefined;
+        const env = cached ??
+            // A `Telo.Import`'s variables/secrets are a config-only contract evaluated
+            // in the IMPORTING module's scope, so they type from the owning module doc
+            // and drop `resources`/`env`, making a reference to either an error.
+            (m.kind === "Telo.Import"
+                ? buildImportInputCelEnvironment(celEnv, allManifests.find((mm) => (mm.kind === "Telo.Application" || mm.kind === "Telo.Library") &&
+                    mm.metadata?.name ===
+                        m.metadata?.module))
+                : buildTypedCelEnvironment(celEnv, m, contextSchema ?? undefined, moduleManifest));
+        if (contextSchema === null && !cached)
+            this.typedEnvByManifest.set(m, env);
+        return { env, contextSchema };
+    }
+    /** The context schema in force at `site`: the matched `x-telo-context` (or the
+     *  resource-wide invocation context), plus the step and error regions this
+     *  path falls in, resolved and merged with the kernel globals. */
+    resolveContextFor(site) {
+        const { path } = site;
+        const m = site.source;
+        let matched = site.contextSchema ?? this.invocationContext;
+        if (this.stepContext) {
+            const base = matched ?? { type: "object", properties: {}, additionalProperties: true };
+            matched = {
+                ...base,
+                properties: { ...(base.properties ?? {}), steps: this.stepContext },
+            };
+        }
+        // `error` is only in scope inside an error-bearing branch (e.g. a
+        // `catch:` / `finally:`), so it's merged per-path, not resource-wide.
+        const errorSchema = this.errorScopes.size > 0 ? errorContextForPath(path, this.errorScopes) : undefined;
+        if (errorSchema) {
+            const base = matched ?? { type: "object", properties: {}, additionalProperties: true };
+            matched = {
+                ...base,
+                properties: { ...(base.properties ?? {}), error: errorSchema },
+            };
+        }
+        if (!matched) {
+            // No `x-telo-context` matched, so nothing was chain-validated here before.
+            // Validate the observed-state segment alone rather than merging the kernel
+            // globals, whose closed `variables` / `ports` nodes would newly reject
+            // reads that pass today.
+            return this.inputs.observedStateContext;
+        }
+        const { defs, aliases, scopes, allManifests, kernelGlobals } = this.inputs;
+        const manifestItem = site.matchedScope
+            ? getManifestItem(path, site.matchedScope, m)
+            : m;
+        const rootForResolver = manifestRootForResolver(m, defs, aliases, allManifests, scopes);
+        const resolved = resolveContextAnnotations(matched, manifestItem, {
+            manifestRoot: rootForResolver,
+            defs,
+            aliases,
+            allManifests: allManifests,
+        });
+        return mergeKernelGlobalsIntoContext(withBindingNames(resolved, m), 
+        // Typed in the module that DECLARED this resource — for a manifest
+        // forwarded from an imported library, that is its `moduleGlobals` stamp,
+        // not the consuming application's block.
+        kernelGlobals.forResource(m));
+    }
+}

package/dist/definition-registry.d.ts

@@ -1,7 +1,7 @@
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
 import type { AliasResolver } from "./alias-resolver.js";
 import { type ReferenceFieldMap } from "./reference-field-map.js";
-/** Pure kind → ResourceDefinition map. No controller loading, no lifecycle. */
+import { type SchemaIssue } from "./schema-error-report.js";
 export declare class DefinitionRegistry {
     constructor();
     /** Per-instance AJV for cross-module $ref resolution. Isolated so each registry
@@ -9,6 +9,7 @@ export declare class DefinitionRegistry {
      *  across analyze() calls and no unbounded growth across the process lifetime. */
     private readonly ajv;
     private readonly registeredSchemaIds;
+    private readonly compiledValidators;
     /** The subset of `registeredSchemaIds` claimed by a kind's schema. Kinds and
      *  named `Telo.Type`s share one `telo://<module>/<Name>` id space, so this is
      *  what lets a colliding type name be reported instead of silently dropped. */
@@ -77,12 +78,28 @@ export declare class DefinitionRegistry {
      *  sanctioned way to reuse one, so a comparator that cannot follow the
      *  reference judges two opaque nodes and learns nothing. */
     schemaForId(id: string): Record<string, any> | undefined;
-    /** Validates data against a schema using this registry's AJV instance, which has all
-     *  registered definition schemas loaded — enabling cross-module $ref resolution.
-     *  A compile failure returns `[]` here; it is surfaced loudly (once, on the
-     *  owning definition) by `schemaCompileError` via the analyzer's
-     *  definition-schema compile check, so resources are never silently skipped. */
+    /**
+     * Validates a resource's configuration against its kind's schema, with the
+     * offending field's path — what a `SCHEMA_VIOLATION` diagnostic is built from.
+     *
+     * On THIS registry's AJV, which is the point: it holds every registered
+     * definition schema and every named `Telo.Type`, so a kind whose schema
+     * references a shape declared elsewhere is checked rather than skipped. The
+     * module-level instance this used to run on had none of them registered, so
+     * such a schema failed to compile and the failure was swallowed — a resource
+     * could be arbitrarily wrong and `telo check` reported nothing, while the
+     * kernel (whose validator does resolve the reference) rejected it at boot.
+     * Two AJVs answering one question is what made that possible; there is now
+     * one, and it is the same one `schemaCompileError` reports through.
+     */
     validateWithRefs(data: unknown, schema: Record<string, any>): string[];
+    /** {@link validateWithRefs}, with the path each issue is anchored at. */
+    validateResourceConfig(data: unknown, schema: Record<string, any>): SchemaIssue[];
+    /** Memoized per schema OBJECT — the analyzer validates every resource of a
+     *  kind against the same one, and this runs at keystroke time in an editor.
+     *  A schema AJV refuses compiles to `undefined`; that is reported once,
+     *  anchored on the owning definition, by `schemaCompileError`. */
+    private compiledFor;
     /** Returns the AJV compile error for `schema`, or `undefined` when it compiles.
      *  Compiles on this registry's instance, which has every loaded module schema
      *  plus the manifest root registered, so local `#/$defs`, `telo://manifest`,
@@ -133,6 +150,21 @@ export declare class DefinitionRegistry {
      *  anchors depend on a sibling property at runtime and stay unexpanded; the
      *  analyzer's reference validation phase already flags the cases that matter. */
     expandedFieldMapForResource(resource: ResourceManifest, aliases: AliasResolver, aliasesByModule: Map<string, AliasResolver>): ReferenceFieldMap | undefined;
+    /**
+     * The schema an `x-telo-schema-from` slot derives its shape from.
+     *
+     * Only the STATIC form resolves: an anchor that is a dotted alias-qualified
+     * kind (`HttpDispatch.Request/$defs/Matcher`). The polymorphic forms — a
+     * relative anchor, or a single-segment absolute one — name a sibling property
+     * whose value is known per resource, so a definition-level lookup would be
+     * guessing at one instance's shape.
+     *
+     * Its own method because a schema-from slot is otherwise INVISIBLE to anything
+     * reading `properties`: the field map needs the nested ref slots, and an IDE
+     * needs the very same node to offer a key or describe one. Two resolutions of
+     * one annotation would eventually disagree about which anchors are static.
+     */
+    resolveSchemaFromNode(schemaFrom: string, ownerScope: AliasResolver): Record<string, any> | undefined;
     private resolveSchemaFromSubMap;
     /** Returns all definitions that transitively extend the given abstract kind.
      *  Follows the capability chain to any depth (equivalent to instanceof in OOP).

package/dist/definition-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"definition-registry.d.ts","sourceRoot":"","sources":["../src/definition-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,0BAA0B,CAAC;AAIlC,+EAA+E;AAC/E,qBAAa,kBAAkB;;IAK7B;;sFAEkF;IAClF,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;IACzD;;mFAE+E;IAC/E,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;IAEzD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAyC;IAC9D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwC;IAClE,mEAAmE;IACnE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA+B;IAC1D;;;;wEAIoE;IACpE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IAEzD,QAAQ,CAAC,UAAU,EAAE,kBAAkB,GAAG,IAAI;IAoC9C,OAAO,CAAC,aAAa;IASrB;;;;;;;;;;;;;2FAauF;IACvF,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAK1E;;;;;;;;;;gFAU4E;IAC5E,uBAAuB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO;IAQzE;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,YAAY;IASpB;uFACmF;IACnF,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIhC;;;gEAG4D;IAC5D,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS;IAMxD;;;;oFAIgF;IAChF,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,EAAE;IAWtE;;;;;;iCAM6B;IAC7B,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,GAAG,SAAS;IASnE;;;;4EAIwE;IACxE,OAAO,CAAC,iBAAiB;IAqBzB;;;;;;;;;;;;;;4BAcwB;IACxB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAShD,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAIrD;;;uCAGmC;IACnC,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS;IAWxD,gGAAgG;IAChG,kBAAkB,CAChB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;KAAE,GACvD,iBAAiB,GAAG,SAAS;IAOhC;;;;;;;;qFAQiF;IACjF,2BAA2B,CACzB,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,aAAa,EACtB,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAC1C,iBAAiB,GAAG,SAAS;IAkChC,OAAO,CAAC,uBAAuB;IA+B/B;;qEAEiE;IACjE,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,kBAAkB,EAAE;IAgBxD,KAAK,IAAI,MAAM,EAAE;CAGlB"}
+{"version":3,"file":"definition-registry.d.ts","sourceRoot":"","sources":["../src/definition-registry.ts"],"names":[],"mappings":"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"}

package/dist/definition-registry.js

@@ -1,9 +1,9 @@
 import { canonicalTypeSchemaId } from "@telorun/sdk";
 import { KERNEL_BUILTINS } from "./builtins.js";
 import { buildFieldMapAtPath, buildReferenceFieldMap, isSchemaFromEntry, } from "./reference-field-map.js";
-import { createAjv, formatSingleError, navigateJsonPointer } from "./schema-compat.js";
+import { createAjv, navigateJsonPointer } from "./schema-compat.js";
+import { formatSingleError, reduceSchemaErrors, schemaIssues, } from "./schema-error-report.js";
 import { effectiveAuthorSchema } from "./extends-resolution.js";
-/** Pure kind → ResourceDefinition map. No controller loading, no lifecycle. */
 export class DefinitionRegistry {
     constructor() {
         for (const def of KERNEL_BUILTINS)
@@ -14,6 +14,7 @@ export class DefinitionRegistry {
      *  across analyze() calls and no unbounded growth across the process lifetime. */
     ajv = createAjv();
     registeredSchemaIds = new Set();
+    compiledValidators = new WeakMap();
     /** The subset of `registeredSchemaIds` claimed by a kind's schema. Kinds and
      *  named `Telo.Type`s share one `telo://<module>/<Name>` id space, so this is
      *  what lets a colliding type name be reported instead of silently dropped. */
@@ -152,22 +153,49 @@ export class DefinitionRegistry {
         const schema = compiled?.schema;
         return schema && typeof schema === "object" ? schema : undefined;
     }
-    /** Validates data against a schema using this registry's AJV instance, which has all
-     *  registered definition schemas loaded — enabling cross-module $ref resolution.
-     *  A compile failure returns `[]` here; it is surfaced loudly (once, on the
-     *  owning definition) by `schemaCompileError` via the analyzer's
-     *  definition-schema compile check, so resources are never silently skipped. */
+    /**
+     * Validates a resource's configuration against its kind's schema, with the
+     * offending field's path — what a `SCHEMA_VIOLATION` diagnostic is built from.
+     *
+     * On THIS registry's AJV, which is the point: it holds every registered
+     * definition schema and every named `Telo.Type`, so a kind whose schema
+     * references a shape declared elsewhere is checked rather than skipped. The
+     * module-level instance this used to run on had none of them registered, so
+     * such a schema failed to compile and the failure was swallowed — a resource
+     * could be arbitrarily wrong and `telo check` reported nothing, while the
+     * kernel (whose validator does resolve the reference) rejected it at boot.
+     * Two AJVs answering one question is what made that possible; there is now
+     * one, and it is the same one `schemaCompileError` reports through.
+     */
     validateWithRefs(data, schema) {
-        let validate;
+        const validate = this.compiledFor(schema);
+        if (!validate || validate(data))
+            return [];
+        return reduceSchemaErrors(validate.errors).map(formatSingleError);
+    }
+    /** {@link validateWithRefs}, with the path each issue is anchored at. */
+    validateResourceConfig(data, schema) {
+        const validate = this.compiledFor(schema);
+        if (!validate || validate(data))
+            return [];
+        return schemaIssues(validate.errors);
+    }
+    /** Memoized per schema OBJECT — the analyzer validates every resource of a
+     *  kind against the same one, and this runs at keystroke time in an editor.
+     *  A schema AJV refuses compiles to `undefined`; that is reported once,
+     *  anchored on the owning definition, by `schemaCompileError`. */
+    compiledFor(schema) {
+        const cached = this.compiledValidators.get(schema);
+        if (cached)
+            return cached;
         try {
-            validate = this.ajv.compile(schema);
+            const validate = this.ajv.compile(schema);
+            this.compiledValidators.set(schema, validate);
+            return validate;
         }
         catch {
-            return [];
+            return undefined;
         }
-        if (validate(data))
-            return [];
-        return (validate.errors ?? []).map(formatSingleError);
     }
     /** Returns the AJV compile error for `schema`, or `undefined` when it compiles.
      *  Compiles on this registry's instance, which has every loaded module schema
@@ -299,28 +327,44 @@ export class DefinitionRegistry {
         }
         return expanded;
     }
-    resolveSchemaFromSubMap(schemaFrom, fieldPath, ownerScope) {
+    /**
+     * The schema an `x-telo-schema-from` slot derives its shape from.
+     *
+     * Only the STATIC form resolves: an anchor that is a dotted alias-qualified
+     * kind (`HttpDispatch.Request/$defs/Matcher`). The polymorphic forms — a
+     * relative anchor, or a single-segment absolute one — name a sibling property
+     * whose value is known per resource, so a definition-level lookup would be
+     * guessing at one instance's shape.
+     *
+     * Its own method because a schema-from slot is otherwise INVISIBLE to anything
+     * reading `properties`: the field map needs the nested ref slots, and an IDE
+     * needs the very same node to offer a key or describe one. Two resolutions of
+     * one annotation would eventually disagree about which anchors are static.
+     */
+    resolveSchemaFromNode(schemaFrom, ownerScope) {
         const isAbsolute = schemaFrom.startsWith("/");
         const expr = isAbsolute ? schemaFrom.slice(1) : schemaFrom;
         const slashIdx = expr.indexOf("/");
         if (slashIdx === -1)
-            return null;
+            return undefined;
         const anchorName = expr.slice(0, slashIdx);
         const jsonPointer = "/" + expr.slice(slashIdx + 1);
-        // Static form: absolute path whose anchor is a dotted alias (e.g.
-        // "HttpDispatch.Outcomes/$defs/Returns"). Polymorphic forms — relative
-        // anchors or single-segment absolute anchors — only resolve once we know a
-        // sibling property's value, which is per-resource.
         if (!anchorName.includes("."))
-            return null;
+            return undefined;
         const targetKind = ownerScope.resolveKind(anchorName);
         if (!targetKind)
-            return null;
+            return undefined;
         const targetDef = this.resolve(targetKind);
         if (!targetDef?.schema)
-            return null;
+            return undefined;
         const subSchema = navigateJsonPointer(targetDef.schema, jsonPointer);
         if (!subSchema || typeof subSchema !== "object")
+            return undefined;
+        return subSchema;
+    }
+    resolveSchemaFromSubMap(schemaFrom, fieldPath, ownerScope) {
+        const subSchema = this.resolveSchemaFromNode(schemaFrom, ownerScope);
+        if (!subSchema)
             return null;
         return buildFieldMapAtPath(subSchema, fieldPath);
     }

package/dist/find-manifest.d.ts

@@ -0,0 +1,10 @@
+import type { ResourceManifest } from "@telorun/sdk";
+/**
+ * The manifest a `(kind, name)` pair addresses.
+ *
+ * One implementation, because two consumers needed it and a manifest set is
+ * exactly the thing `ManifestAnalysis` exists to have one answer over. Undefined
+ * when the set holds no such resource — a document the author is still writing.
+ */
+export declare function findManifest(manifests: readonly ResourceManifest[], kind: string | undefined, name: string | undefined): ResourceManifest | undefined;
+//# sourceMappingURL=find-manifest.d.ts.map

package/dist/find-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-manifest.d.ts","sourceRoot":"","sources":["../src/find-manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,SAAS,gBAAgB,EAAE,EACtC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,IAAI,EAAE,MAAM,GAAG,SAAS,GACvB,gBAAgB,GAAG,SAAS,CAK9B"}

package/dist/find-manifest.js

@@ -0,0 +1,12 @@
+/**
+ * The manifest a `(kind, name)` pair addresses.
+ *
+ * One implementation, because two consumers needed it and a manifest set is
+ * exactly the thing `ManifestAnalysis` exists to have one answer over. Undefined
+ * when the set holds no such resource — a document the author is still writing.
+ */
+export function findManifest(manifests, kind, name) {
+    if (!kind || !name)
+        return undefined;
+    return manifests.find((m) => m.kind === kind && m.metadata?.name === name);
+}

package/dist/index.d.ts

@@ -60,8 +60,10 @@ 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, selectUnionBranch } from "./schema-compat.js";
-export type { CompatibilityResult } from "./schema-compat.js";
+export { checkSchemaCompatibility, resolveRefIn, selectUnionBranch } from "./schema-compat.js";
+export type { CompatibilityResult, ExternalSchemaResolver } from "./schema-compat.js";
+export { ajvErrorToPath, formatAjvErrors, formatSingleError, reduceSchemaErrors, schemaIssues, } from "./schema-error-report.js";
+export type { AjvErrorLike, SchemaIssue } from "./schema-error-report.js";
 export { visitManifest } from "./manifest-visitor.js";
 export type { CelSiteEvent, ManifestVisitor, RefSiteEvent, ResourceEnterEvent, ResourceExitEvent, ScopeBoundaryEvent, SchemaFromSiteEvent, VisitOptions, } from "./manifest-visitor.js";
 export { Loader } from "./manifest-loader.js";
@@ -108,6 +110,13 @@ export { documentToAst, parseToAst } from "./yaml-ast.js";
 export type { AstDocument, AstMap, AstNode, AstPair, AstScalar, AstSeq } from "./yaml-ast.js";
 export { CelParseError, buildCelSegments, wrapCelAst } from "./cel-ast.js";
 export type { CelNode, CelSegment } from "./cel-ast.js";
+export { CelScopeResolver } from "./cel-scope.js";
+export type { CelScope, CelScopeInputs, CelSiteRef } from "./cel-scope.js";
+export { CelScopeQuery } from "./cel-scope-query.js";
+export type { CelScopeQueryContext, ContextDeclarationSite } from "./cel-scope-query.js";
+export { navigateConcretePath } from "./manifest-path.js";
+export { ManifestAnalysis } from "./manifest-analysis.js";
+export type { ManifestRef } from "./manifest-analysis.js";
 export { DEFAULT_MANIFEST_FILENAME, DiagnosticSeverity, diagnosticFix } from "./types.js";
 export type { AnalysisDiagnostic, AnalysisOptions, DiagnosticData, DiagnosticFix, LoaderInitOptions, LoadOptions, ManifestSource, Position, PositionIndex, Range } from "./types.js";
 export * from "./manifest-schemas.js";