@telorun/analyzer 0.63.0 → 0.64.0

package/dist/cel-scope-query.d.ts

@@ -0,0 +1,109 @@
+/**
+ * **Ask what a CEL site sees, from outside the analysis pass.**
+ *
+ * The pass resolves a scope per expression as it walks. An IDE has no walk: it
+ * has a cursor, and needs the same answer for one address — often for an
+ * expression the last analysis never saw, because the user is typing it. So the
+ * query is driven by (manifest, path) rather than by a visitor event, and the
+ * `x-telo-context` match is recomputed here exactly as the visitor computes it
+ * (`extractContextsFromSchema` + `pathMatchesScope`, the same two functions).
+ *
+ * The scope RULE itself is not re-implemented — {@link CelScopeResolver} is the
+ * one that answers, here and in the pass. What this module adds is the way in.
+ */
+import type { ResourceManifest } from "@telorun/sdk";
+import type { Environment } from "@marcbachmann/cel-js";
+import { AliasResolver } from "./alias-resolver.js";
+import { type CelScope } from "./cel-scope.js";
+import { DefinitionRegistry } from "./definition-registry.js";
+/** Where a CEL context binding was declared: the manifest that declares it,
+ *  by identity, plus the concrete path within it. Identity rather than the
+ *  object because a host locates a manifest in its own loaded files, which is
+ *  what carries the source ranges. */
+export interface ContextDeclarationSite {
+    kind: string;
+    name: string;
+    path: string;
+}
+/** The analyzer state a query resolves against — what an `AnalysisRegistry`
+ *  already holds, plus the manifest set the caller analyzed. */
+export interface CelScopeQueryContext {
+    defs: DefinitionRegistry;
+    aliases: AliasResolver;
+    aliasesByModule: Map<string, AliasResolver>;
+}
+/**
+ * A reusable scope query over one manifest set.
+ *
+ * Built once per analysis rather than per keystroke: the observed-state index
+ * and the kernel globals are a function of the whole set, and rebuilding them
+ * for every cursor move would put a full-set walk on the hover path.
+ */
+export declare class CelScopeQuery {
+    private readonly manifests;
+    private readonly resolver;
+    /** The resource the resolver is currently entered on — `enterResource` is the
+     *  per-resource half of the rule, so re-entering per query is only needed when
+     *  the cursor moves to a different resource. */
+    private entered;
+    /** Resolved scopes, keyed by resource and path. A context-matched site builds
+     *  a fresh typed environment by design (a clone plus a re-registration of
+     *  every variable), which is affordable once per site in a batch pass and not
+     *  once per site per KEYSTROKE — which is what a whole-file colourizer asks
+     *  for. The lifetime is this query's, which is the analysis's. */
+    private readonly scopeCache;
+    constructor(manifests: ResourceManifest[], ctx: CelScopeQueryContext, celEnv?: Environment);
+    private readonly ctx;
+    /** The manifest a cursor's document addresses — {@link findManifest}, the one
+     *  implementation `ManifestAnalysis` also answers from. */
+    resourceFor(kind: string | undefined, name: string | undefined): ResourceManifest | undefined;
+    /**
+     * What CEL at `path` in `resource` is typed against.
+     *
+     * `path` is the CONCRETE path, indices and all (`routes[0].handler.url`) —
+     * an `x-telo-context` region, an error-bearing branch and a step's identity
+     * are each addressed per item, so an index-erased path resolves the wrong
+     * scope or none.
+     */
+    scopeAt(resource: ResourceManifest, path: string): CelScope;
+    /**
+     * Where a CEL context binding was DECLARED — the manifest node the
+     * `x-telo-context-*` annotation derived it from.
+     *
+     * The mirror of {@link scopeAt}: that one resolves the annotation into a
+     * schema and the provenance is gone by the time it returns, while
+     * go-to-declaration wants the path and not the schema. Re-walking the
+     * annotation is what keeps `CelScope` free of an origin field every type
+     * consumer would have to ignore.
+     *
+     * Generic over the annotation, so `request.query` lands on the route's own
+     * `request.schema.query`, `self.<field>` on the definition's `schema`, and
+     * `result.<field>` on the INVOKED resource's `outputType` — one walk, no
+     * transport and no resource kind named here.
+     *
+     * Every candidate path is checked against the manifest before it is returned,
+     * so a binding the author never declared (a context annotation's static
+     * fallback properties) resolves to nothing rather than to a guessed node.
+     */
+    contextDeclarationSite(resource: ResourceManifest, sitePath: string, parts: string[]): ContextDeclarationSite | undefined;
+    /** The manifest and path an annotated context property is derived from, and
+     *  whether that node holds a property MAP (names directly) or a JSON Schema. */
+    private originOf;
+    /**
+     * Where the step named `stepName` is declared in `resource`, as a concrete
+     * path (`steps[2]`), or undefined when the resource declares no step body or
+     * holds no such step.
+     *
+     * For go-to-declaration on `steps.<name>.result`, which is the one CEL scope
+     * whose members ARE written somewhere in the manifest but are reached through
+     * no reference slot. Driven by the kind's own step-body annotation and the
+     * shared nesting walk, so a step inside a `try:` inside a `catch:` is found
+     * and no resource kind is named here.
+     */
+    stepDeclarationPath(resource: ResourceManifest, stepName: string): string | undefined;
+    private definitionFor;
+    /** The `x-telo-context` region this path falls in, matched exactly as the
+     *  manifest visitor matches it for an expression it walked onto. */
+    private matchContext;
+}
+//# sourceMappingURL=cel-scope-query.d.ts.map

package/dist/cel-scope-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cel-scope-query.d.ts","sourceRoot":"","sources":["../src/cel-scope-query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAsB,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAqB,MAAM,qBAAqB,CAAC;AAEvE,OAAO,EAAoB,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAiB9D;;;sCAGsC;AACtC,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAoBD;gEACgE;AAChE,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,kBAAkB,CAAC;IACzB,OAAO,EAAE,aAAa,CAAC;IACvB,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CAC7C;AAED;;;;;;GAMG;AACH,qBAAa,aAAa;IActB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAb5B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmB;IAC5C;;oDAEgD;IAChD,OAAO,CAAC,OAAO,CAA+B;IAC9C;;;;sEAIkE;IAClE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsD;gBAG9D,SAAS,EAAE,gBAAgB,EAAE,EAC9C,GAAG,EAAE,oBAAoB,EACzB,MAAM,CAAC,EAAE,WAAW;IAgCtB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAuB;IAE3C;+DAC2D;IAC3D,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,gBAAgB,GAAG,SAAS;IAI7F;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ;IAe3D;;;;;;;;;;;;;;;;;;OAkBG;IACH,sBAAsB,CACpB,QAAQ,EAAE,gBAAgB,EAC1B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EAAE,GACd,sBAAsB,GAAG,SAAS;IAqCrC;oFACgF;IAChF,OAAO,CAAC,QAAQ;IAgEhB;;;;;;;;;;OAUG;IACH,mBAAmB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAqBrF,OAAO,CAAC,aAAa;IAMrB;wEACoE;IACpE,OAAO,CAAC,YAAY;CAarB"}

package/dist/cel-scope-query.js

@@ -0,0 +1,270 @@
+import { buildCelEnvironment } from "./cel-environment.js";
+import { CelScopeResolver } from "./cel-scope.js";
+import { buildKernelGlobalsIndex } from "./kernel-globals.js";
+import { isModuleKind } from "./module-kinds.js";
+import { navigateConcretePath } from "./manifest-path.js";
+import { findManifest } from "./find-manifest.js";
+import { resolveLocalRef, walkStepArray } from "./schema-walk.js";
+import { readStepSlot } from "./step-slot.js";
+import { buildObservedStateIndex, buildObservedStateResourcesSchema, } from "./validate-observed-state.js";
+import { extractContextsFromSchema, getManifestItem, pathMatchesScope, } from "./validate-cel-context.js";
+/** Join a concrete path segment, tolerating an empty base (the manifest root). */
+function joinPath(base, segment) {
+    return base ? `${base}.${segment}` : segment;
+}
+/** The concrete path of the array ITEM an `x-telo-context` scope matched — the
+ *  path half of `getManifestItem`, which returns only the value. Empty when the
+ *  scope is not per-item. */
+function manifestItemPath(exprPath, scope) {
+    if (!scope)
+        return "";
+    const stripped = scope.startsWith("$.") ? scope.slice(2) : scope;
+    const wildcard = stripped.indexOf("[*]");
+    if (wildcard === -1)
+        return "";
+    const arrayProp = stripped.slice(0, wildcard);
+    const match = exprPath.match(new RegExp(`^${arrayProp}\\[(\\d+)\\]`));
+    return match ? `${arrayProp}[${match[1]}]` : "";
+}
+/**
+ * A reusable scope query over one manifest set.
+ *
+ * Built once per analysis rather than per keystroke: the observed-state index
+ * and the kernel globals are a function of the whole set, and rebuilding them
+ * for every cursor move would put a full-set walk on the hover path.
+ */
+export class CelScopeQuery {
+    manifests;
+    resolver;
+    /** The resource the resolver is currently entered on — `enterResource` is the
+     *  per-resource half of the rule, so re-entering per query is only needed when
+     *  the cursor moves to a different resource. */
+    entered;
+    /** Resolved scopes, keyed by resource and path. A context-matched site builds
+     *  a fresh typed environment by design (a clone plus a re-registration of
+     *  every variable), which is affordable once per site in a batch pass and not
+     *  once per site per KEYSTROKE — which is what a whole-file colourizer asks
+     *  for. The lifetime is this query's, which is the analysis's. */
+    scopeCache = new Map();
+    constructor(manifests, ctx, celEnv) {
+        this.manifests = manifests;
+        const { defs, aliases, aliasesByModule } = ctx;
+        const rootModules = new Set();
+        for (const m of manifests) {
+            if (isModuleKind(m.kind) && m.metadata?.name)
+                rootModules.add(m.metadata.name);
+        }
+        const scopes = { aliasesByModule, rootModules };
+        const observedState = buildObservedStateIndex(manifests, defs, aliases, scopes);
+        const reportsObservedState = [...observedState.values()].some((r) => r.status);
+        this.resolver = new CelScopeResolver({
+            celEnv: celEnv ?? buildCelEnvironment(),
+            defs,
+            aliases,
+            scopes,
+            allManifests: manifests,
+            kernelGlobals: buildKernelGlobalsIndex(manifests, observedState),
+            moduleManifest: manifests.find((mm) => mm.kind === "Telo.Application") ??
+                manifests.find((mm) => mm.kind === "Telo.Library"),
+            observedStateContext: reportsObservedState
+                ? {
+                    type: "object",
+                    additionalProperties: true,
+                    properties: { resources: buildObservedStateResourcesSchema(observedState, true) },
+                }
+                : null,
+        });
+        this.ctx = ctx;
+    }
+    ctx;
+    /** The manifest a cursor's document addresses — {@link findManifest}, the one
+     *  implementation `ManifestAnalysis` also answers from. */
+    resourceFor(kind, name) {
+        return findManifest(this.manifests, kind, name);
+    }
+    /**
+     * What CEL at `path` in `resource` is typed against.
+     *
+     * `path` is the CONCRETE path, indices and all (`routes[0].handler.url`) —
+     * an `x-telo-context` region, an error-bearing branch and a step's identity
+     * are each addressed per item, so an index-erased path resolves the wrong
+     * scope or none.
+     */
+    scopeAt(resource, path) {
+        let byPath = this.scopeCache.get(resource);
+        if (!byPath)
+            this.scopeCache.set(resource, (byPath = new Map()));
+        const cached = byPath.get(path);
+        if (cached)
+            return cached;
+        if (this.entered !== resource) {
+            this.resolver.enterResource(resource, this.definitionFor(resource));
+            this.entered = resource;
+        }
+        const { contextSchema, matchedScope } = this.matchContext(resource, path);
+        const scope = this.resolver.scopeFor({ source: resource, path, contextSchema, matchedScope });
+        byPath.set(path, scope);
+        return scope;
+    }
+    /**
+     * Where a CEL context binding was DECLARED — the manifest node the
+     * `x-telo-context-*` annotation derived it from.
+     *
+     * The mirror of {@link scopeAt}: that one resolves the annotation into a
+     * schema and the provenance is gone by the time it returns, while
+     * go-to-declaration wants the path and not the schema. Re-walking the
+     * annotation is what keeps `CelScope` free of an origin field every type
+     * consumer would have to ignore.
+     *
+     * Generic over the annotation, so `request.query` lands on the route's own
+     * `request.schema.query`, `self.<field>` on the definition's `schema`, and
+     * `result.<field>` on the INVOKED resource's `outputType` — one walk, no
+     * transport and no resource kind named here.
+     *
+     * Every candidate path is checked against the manifest before it is returned,
+     * so a binding the author never declared (a context annotation's static
+     * fallback properties) resolves to nothing rather than to a guessed node.
+     */
+    contextDeclarationSite(resource, sitePath, parts) {
+        if (parts.length < 2)
+            return undefined;
+        const { contextSchema, matchedScope } = this.matchContext(resource, sitePath);
+        const annotated = contextSchema?.properties?.[parts[0]];
+        if (!annotated)
+            return undefined;
+        const origin = this.originOf(annotated, resource, sitePath, matchedScope);
+        if (!origin)
+            return undefined;
+        // The ORIGIN decides the shape rather than positional fallthrough. A
+        // property-map origin holds the names themselves, so its first hop is direct
+        // and ONLY direct — trying `properties` there would let an author's own
+        // `properties:` key win over the name they wrote. Every deeper hop, and
+        // every hop of a JSON-Schema origin, goes through `properties`, with the
+        // inline `{ kind, schema }` wrapper as the one alternative a type field is
+        // routinely written as.
+        let base = origin.path;
+        for (let i = 1; i < parts.length; i++) {
+            const candidates = i === 1 && origin.propertyMap
+                ? [joinPath(base, parts[i])]
+                : [
+                    joinPath(joinPath(base, "properties"), parts[i]),
+                    joinPath(joinPath(joinPath(base, "schema"), "properties"), parts[i]),
+                ];
+            const hit = candidates.find((candidate) => navigateConcretePath(origin.manifest, candidate) !== undefined);
+            if (!hit)
+                return undefined;
+            base = hit;
+        }
+        const metadata = origin.manifest.metadata;
+        if (!origin.manifest.kind || !metadata?.name)
+            return undefined;
+        return { kind: origin.manifest.kind, name: metadata.name, path: base };
+    }
+    /** The manifest and path an annotated context property is derived from, and
+     *  whether that node holds a property MAP (names directly) or a JSON Schema. */
+    originOf(annotated, resource, sitePath, matchedScope) {
+        const root = resource;
+        // Per-scope: the annotation navigates the enclosing ARRAY ITEM, so the path
+        // it yields is relative to that item rather than to the resource.
+        const from = annotated["x-telo-context-from"];
+        if (typeof from === "string") {
+            const itemPath = manifestItemPath(sitePath, matchedScope);
+            return { manifest: root, path: joinPath(itemPath, from.split("/").join(".")), propertyMap: true };
+        }
+        const fromRoot = annotated["x-telo-context-from-root"];
+        if (typeof fromRoot === "string") {
+            return { manifest: root, path: fromRoot.split("/").join("."), propertyMap: false };
+        }
+        // Cross-manifest: the binding is declared by whatever this slot REFERENCES,
+        // which is the node a reader wants when a result's members do not resolve.
+        const refFrom = annotated["x-telo-context-ref-from"];
+        if (typeof refFrom === "string") {
+            const slash = refFrom.indexOf("/");
+            if (slash === -1)
+                return undefined;
+            const item = matchedScope
+                ? getManifestItem(sitePath, matchedScope, root)
+                : root;
+            const ref = item[refFrom.slice(0, slash)];
+            if (!ref?.kind || !ref.name)
+                return undefined;
+            const target = this.manifests.find((m) => m.kind === ref.kind && m.metadata?.name === ref.name);
+            if (!target)
+                return undefined;
+            return { manifest: target, path: refFrom.slice(slash + 1).split("/").join("."), propertyMap: false };
+        }
+        // A kind's own declaration: the target is the `Telo.Definition` document,
+        // which is an ordinary manifest in the set.
+        const fromRefKind = annotated["x-telo-context-from-ref-kind"];
+        const first = Array.isArray(fromRefKind) ? fromRefKind[0] : fromRefKind;
+        if (typeof first === "string") {
+            const hash = first.indexOf("#");
+            if (hash <= 0)
+                return undefined;
+            const kindValue = navigateConcretePath(root, first.slice(0, hash).split("/").join("."));
+            if (typeof kindValue !== "string")
+                return undefined;
+            const canonical = this.ctx.aliases.resolveKind(kindValue) ?? kindValue;
+            const suffix = canonical.slice(canonical.indexOf(".") + 1);
+            const target = this.manifests.find((m) => (m.kind === "Telo.Definition" || m.kind === "Telo.Abstract") &&
+                m.metadata?.name === suffix);
+            if (!target)
+                return undefined;
+            return { manifest: target, path: first.slice(hash + 1), propertyMap: false };
+        }
+        // `x-telo-context-element-from` / `-collection-from` type a binding from an
+        // EXPRESSION, so there is no declaration to navigate to.
+        return undefined;
+    }
+    /**
+     * Where the step named `stepName` is declared in `resource`, as a concrete
+     * path (`steps[2]`), or undefined when the resource declares no step body or
+     * holds no such step.
+     *
+     * For go-to-declaration on `steps.<name>.result`, which is the one CEL scope
+     * whose members ARE written somewhere in the manifest but are reached through
+     * no reference slot. Driven by the kind's own step-body annotation and the
+     * shared nesting walk, so a step inside a `try:` inside a `catch:` is found
+     * and no resource kind is named here.
+     */
+    stepDeclarationPath(resource, stepName) {
+        const schema = this.definitionFor(resource)?.schema;
+        const props = schema?.properties;
+        if (!schema || !props)
+            return undefined;
+        for (const [fieldName, fieldSchema] of Object.entries(props)) {
+            if (!readStepSlot(fieldSchema))
+                continue;
+            const steps = resource[fieldName];
+            if (!Array.isArray(steps))
+                continue;
+            const itemSchema = resolveLocalRef(fieldSchema.items, schema);
+            let found;
+            walkStepArray(steps, itemSchema, schema, fieldName, (step, stepPath) => {
+                if (found === undefined && step.name === stepName)
+                    found = stepPath;
+            });
+            if (found)
+                return found;
+        }
+        return undefined;
+    }
+    definitionFor(resource) {
+        const { defs, aliases } = this.ctx;
+        const canonical = aliases.resolveKind(resource.kind);
+        return defs.resolve(resource.kind) ?? (canonical ? defs.resolve(canonical) : undefined);
+    }
+    /** The `x-telo-context` region this path falls in, matched exactly as the
+     *  manifest visitor matches it for an expression it walked onto. */
+    matchContext(resource, path) {
+        const schema = this.definitionFor(resource)?.schema;
+        if (!schema)
+            return {};
+        for (const ctx of extractContextsFromSchema(schema)) {
+            if (pathMatchesScope(path, ctx.scope)) {
+                return { contextSchema: ctx.schema, matchedScope: ctx.scope };
+            }
+        }
+        return {};
+    }
+}

package/dist/cel-scope.d.ts

@@ -0,0 +1,166 @@
+/**
+ * **What is in scope for CEL at one expression site.**
+ *
+ * A CEL expression is typed against an environment and a resolved context
+ * schema that depend on WHERE it sits: the kind's step body contributes
+ * `steps.<name>.result`, an error-bearing branch contributes `error`, a
+ * `x-telo-bindings-from` field contributes its named bindings, an
+ * `x-telo-context` region contributes its own scope resolved against the
+ * enclosing array item, and the kernel globals are merged in per declaring
+ * module. That assembly used to live inline in the analysis pass, built for one
+ * `engine.analyze` call and discarded — so nothing outside the pass could ask
+ * what a cursor sees.
+ *
+ * It is a QUERY here, and the pass is one of its callers. The other is the IDE:
+ * completion, hover and signature help must offer exactly the names
+ * `telo check` accepts, and two implementations of an open, growing scope rule
+ * cannot be held in agreement by tests.
+ *
+ * Nothing here reports a diagnostic. The pass keeps every check it ever had;
+ * what moved is the answer both halves need first.
+ */
+import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
+import type { Environment } from "@marcbachmann/cel-js";
+import { AliasResolver, type ModuleScopes } from "./alias-resolver.js";
+import { DefinitionRegistry } from "./definition-registry.js";
+import { type KernelGlobalsIndex } from "./kernel-globals.js";
+/** 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 declare function manifestRootForResolver(m: Record<string, any>, defs: DefinitionRegistry, aliases: AliasResolver, allManifests: Record<string, any>[], scopes: ModuleScopes): Record<string, any>;
+/**
+ * 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 declare function buildStepContextSchema(manifest: Record<string, any>, defSchema: Record<string, any>, allManifests: Record<string, any>[], defs: DefinitionRegistry, aliases: AliasResolver, scopes: ModuleScopes): Record<string, any> | undefined;
+export declare function collectErrorContextScopes(defSchema: Record<string, any> | undefined): Map<string, Record<string, any>>;
+/**
+ * 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 declare function errorContextForPath(path: string, scopes: Map<string, Record<string, any>>): Record<string, any> | undefined;
+/** 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 declare function withBindingNames(contextSchema: Record<string, any>, resource: Record<string, any>): Record<string, any>;
+/**
+ * What one CEL expression is typed against.
+ *
+ * Both halves, never a flattened name list: the environment answers "what
+ * names exist and what type does this expression have", the context schema
+ * answers "what shape does that name carry" — which is what a hover tooltip and
+ * a member completion are made of, and what a name list throws away.
+ */
+export interface CelScope {
+    /** The environment typed for this expression's path. */
+    env: Environment;
+    /** The resolved `x-telo-context` schema merged with the kernel globals, or
+     *  null when no context applied (the environment alone types the site). */
+    contextSchema: Record<string, any> | null;
+}
+/** The analyzer state a scope is resolved against — everything a manifest set
+ *  contributes, gathered once per analysis. */
+export interface CelScopeInputs {
+    /** The base (untyped) CEL environment. */
+    celEnv: Environment;
+    defs: DefinitionRegistry;
+    aliases: AliasResolver;
+    scopes: ModuleScopes;
+    allManifests: ResourceManifest[];
+    kernelGlobals: KernelGlobalsIndex;
+    /** The module doc carrying the Application-only `ports` namespace. */
+    moduleManifest?: ResourceManifest;
+    /** The observed-state-only context, used where no `x-telo-context` matched. */
+    observedStateContext: Record<string, any> | null;
+}
+/** One CEL site, as the manifest visitor reports it. Structural on purpose —
+ *  the resolver takes the fields it reads, not the visitor's event type, so a
+ *  caller that located a site some other way (a cursor in an editor buffer) can
+ *  ask the same question. */
+export interface CelSiteRef {
+    source: ResourceManifest;
+    path: string;
+    contextSchema?: Record<string, any>;
+    matchedScope?: string;
+}
+/**
+ * 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 declare class CelScopeResolver {
+    private readonly inputs;
+    private readonly typedEnvByManifest;
+    /** Per-resource state, replaced at each `enterResource`. */
+    private stepContext;
+    private invocationContext;
+    private errorScopes;
+    constructor(inputs: CelScopeInputs);
+    /** 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(): Record<string, any> | undefined;
+    /** The error-bearing regions the current resource's kind declares. */
+    get errorContextScopes(): ReadonlyMap<string, Record<string, any>>;
+    /** 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(): Record<string, any> | undefined;
+    /** Establish the per-resource half of the scope. */
+    enterResource(m: ResourceManifest, definition: ResourceDefinition | undefined): void;
+    /**
+     * 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: CelSiteRef): CelScope;
+    /** 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. */
+    private resolveContextFor;
+}
+//# sourceMappingURL=cel-scope.d.ts.map

package/dist/cel-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cel-scope.d.ts","sourceRoot":"","sources":["../src/cel-scope.ts"],"names":[],"mappings":"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"}