@telorun/analyzer 0.62.0 → 0.63.0

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

@@ -1 +1 @@
-{"version":3,"file":"manifest-schemas.d.ts","sourceRoot":"","sources":["../src/manifest-schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAKH,eAAO,MAAM,mBAAmB,oBAAoB,CAAC;AAErD,sEAAsE;AACtE,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;yEA8ByE;AACzE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoB7B,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwD7B,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB;;;;;;CAM/B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8C5B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,iBAAiB;;;;;;CAM7B,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,gBAAgB;;;;;;CAO5B,CAAC;AAUF;;;WAGW;AACX,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAElE;AAiCD;0DAC0D;AAC1D,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAU9B,CAAC;AAIF;;;0EAG0E;AAC1E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAmBtE;AAID;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,cAAoB,GAAG,IAAI,CAGrF;AA0HD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAGnF;AA+DD;iEACiE;AACjE,eAAO,MAAM,eAAe,oBAAoB,CAAC;AAEjD;uDACuD;AACvD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAItE"}
+{"version":3,"file":"manifest-schemas.d.ts","sourceRoot":"","sources":["../src/manifest-schemas.ts"],"names":[],"mappings":"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"}

package/dist/manifest-schemas.js

@@ -235,6 +235,37 @@ export const InvokeStepSchema = {
         retry: {
             title: "Retry",
             $ref: `${MANIFEST_SCHEMA_URI}#/$defs/RetryPolicy`,
+            // A sibling of the shared policy rather than a member of it, the way
+            // `Http.Request.retry` adds `honorRetryAfter` — fragment expansion merges
+            // siblings, so the policy stays closed and each consumer's surface stays
+            // honest. `nonRetryable` matches an ERROR CODE, which is what a step's
+            // failures carry; an HTTP retry classifies on a response STATUS and has
+            // `retryOn` for it, so putting this on the shared shape would advertise a
+            // field there that nothing could read.
+            properties: {
+                nonRetryable: {
+                    title: "Non-retryable codes",
+                    description: "Error codes that end the loop immediately instead of consuming the budget. " +
+                        "The built-in exclusions are the ones decidable without judgement — a " +
+                        "cancellation, and the kernel's verdicts on the shape of the call; whether a " +
+                        "DOMAIN failure is worth re-attempting only the author knows, and without " +
+                        "this every terminal one is retried to exhaustion — for a non-idempotent " +
+                        "target, N extra attempts at a side effect.",
+                    type: "array",
+                    items: { type: "string" },
+                    default: [],
+                },
+            },
+        },
+        timeout: {
+            title: "Timeout",
+            description: "How long ONE attempt may take, in milliseconds; on elapse the dispatch is " +
+                "cancelled and the step fails ERR_STEP_TIMEOUT. Per attempt rather than for " +
+                "the whole retry loop, so what a single call is allowed to take does not " +
+                "depend on how slow the earlier attempts were. It belongs to the step rather " +
+                "than the target because the target does not know who is waiting.",
+            type: "integer",
+            minimum: 1,
         },
     },
 };
@@ -291,12 +322,226 @@ export const KindSchemaSchema = {
     properties: jsonSchemaKeywords(hoistedDefKey("KindSchema")),
     additionalProperties: true,
 };
+/** The `error` variable a `catch:` / `finally:` branch binds. One object, used
+ *  twice with different nullability — `finally` runs on the success path too. */
+const stepErrorProperties = {
+    code: {
+        description: "Structured error code; INTERNAL_ERROR for plain errors.",
+        type: "string",
+    },
+    message: { description: "Human-readable error message.", type: "string" },
+    step: { description: "Name of the step that threw.", type: "string" },
+    data: { description: "Structured payload from an InvokeError, else undefined." },
+};
+/** A step list's own items, written as the self-reference the localizer leaves
+ *  behind. A recursive fragment states its self-references ALREADY localized:
+ *  `hoistFragmentDef` copies the body verbatim into the consuming schema's
+ *  `$defs`, so a foreign `telo://manifest#/…` written here would survive into a
+ *  document the editor's local-only resolver throws on. */
+const stepList = (title, description) => ({
+    title,
+    description,
+    "x-telo-topology-role": "branch",
+    type: "array",
+    items: { $ref: `#/$defs/${hoistedDefKey("Step")}` },
+});
+/**
+ * One step of a step body: a dispatch, a computed value, or a control-flow block.
+ *
+ * THE GRAMMAR, owned here rather than by `modules/run`. It was declared four
+ * times in one file — `$defs` are local to the schema that declares them, so
+ * four kinds in one module could not share one, let alone four kinds in four
+ * modules — and that is why a kind wanting a body had to take a `!ref` to an
+ * executable instead. A fragment is what makes `Sql.Transaction` or a durable
+ * `Workflow` able to carry one directly.
+ *
+ * RECURSIVE (a branch holds steps), so a reference to it is localized and
+ * hoisted rather than expanded in place — see {@link localizeRecursiveFragment}.
+ *
+ * `while/do` is admitted in EVERY body. Three of the four copies dropped it
+ * ("the kind is itself the loop"), which is an editorial nudge rather than a
+ * soundness rule — a nested `while` inside a for-each body is ordinary control
+ * flow the same engine already runs — and a fragment cannot be narrowed by its
+ * consumer anyway: draft-07 makes `$ref` exclusive, so a sibling restating a
+ * subset would be silently ignored by AJV while still reaching completion. One
+ * grammar, or two fragments and the duplication back where it started.
+ */
+export const StepSchema = {
+    title: "Step",
+    description: "Single executable step or control-flow block.",
+    type: "object",
+    properties: {
+        name: { title: "Name", description: "Unique step name.", type: "string" },
+    },
+    oneOf: [
+        // THE dispatch site, shared with an Application's `targets:` rather than
+        // restated. `name` is hoisted to the enclosing step object above, which is
+        // why this branch carries only what a dispatch itself needs.
+        {
+            title: "invoke",
+            description: "Invokes an invocable or runnable resource.",
+            $ref: `${MANIFEST_SCHEMA_URI}#/$defs/InvokeStep`,
+        },
+        {
+            title: "if/then/else",
+            description: "Conditional branch; executes then or else based on a boolean expression.",
+            properties: {
+                if: {
+                    title: "If",
+                    description: "CEL boolean expression; true executes then, false executes else.",
+                    "x-telo-topology-role": "predicate",
+                    type: "boolean",
+                },
+                elseif: {
+                    title: "Else If",
+                    description: "Additional condition-branch pairs evaluated when if is false.",
+                    "x-telo-topology-role": "branch-list",
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            if: {
+                                title: "If",
+                                description: "CEL boolean expression for this else-if branch.",
+                                "x-telo-topology-role": "predicate",
+                                type: "boolean",
+                            },
+                            then: stepList("Then", "Steps executed when this else-if condition is true."),
+                        },
+                        required: ["if", "then"],
+                    },
+                },
+                then: stepList("Then", "Steps executed when if evaluates true."),
+                else: stepList("Else", "Steps executed when if (and all elseif conditions) evaluate false."),
+            },
+            required: ["if", "then"],
+        },
+        {
+            title: "while/do",
+            description: "Loop; executes do steps repeatedly while condition is true.",
+            properties: {
+                while: {
+                    title: "While",
+                    description: "CEL boolean expression; evaluated before each iteration.",
+                    "x-telo-topology-role": "predicate",
+                    type: "boolean",
+                },
+                do: stepList("Do", "Steps executed on each iteration."),
+            },
+            required: ["while", "do"],
+        },
+        {
+            title: "switch/cases/default",
+            description: "Multi-branch dispatch; matches a value expression against case keys.",
+            properties: {
+                switch: {
+                    title: "Switch",
+                    description: "CEL expression; result matched against case keys.",
+                    "x-telo-topology-role": "discriminator",
+                    type: "string",
+                },
+                cases: {
+                    title: "Cases",
+                    description: "Map of value to step list; executed when switch matches the key.",
+                    "x-telo-topology-role": "case-map",
+                    type: "object",
+                    additionalProperties: {
+                        type: "array",
+                        items: { $ref: `#/$defs/${hoistedDefKey("Step")}` },
+                    },
+                },
+                default: stepList("Default", "Steps executed when no case matches."),
+            },
+            required: ["switch", "cases"],
+        },
+        {
+            title: "try/catch/finally",
+            description: "Error boundary; executes try steps and handles failure via catch and finally.",
+            properties: {
+                try: stepList("Try", "Steps executed; halts on first failure and jumps to catch."),
+                catch: {
+                    ...stepList("Catch", "Steps executed when try fails; receives error context."),
+                    "x-telo-error-context": {
+                        type: "object",
+                        description: "The caught failure (always present inside catch).",
+                        properties: stepErrorProperties,
+                        additionalProperties: false,
+                    },
+                },
+                finally: {
+                    ...stepList("Finally", "Steps always executed after try/catch regardless of outcome."),
+                    // error is null on the success path and the caught failure when a
+                    // try/catch failure propagates. Typed nullable so the analyzer flags
+                    // unguarded field access (CEL_NULLABLE_ACCESS).
+                    "x-telo-error-context": {
+                        type: ["object", "null"],
+                        description: "The caught failure, or null when try (and catch) succeeded.",
+                        properties: stepErrorProperties,
+                        additionalProperties: false,
+                    },
+                },
+            },
+            required: ["try"],
+        },
+        {
+            title: "throw",
+            description: "Throws an InvokeError unconditionally. Works inside catch blocks via CEL " +
+                '(e.g. code set to `!cel "error.code"`).',
+            properties: {
+                throw: {
+                    title: "Throw",
+                    description: "InvokeError descriptor; code is required, message/data optional.",
+                    type: "object",
+                    properties: {
+                        code: {
+                            title: "Code",
+                            description: "Structured error code; uppercase SNAKE_CASE by convention.",
+                            type: "string",
+                        },
+                        message: {
+                            title: "Message",
+                            description: "Human-readable error message. Defaults to `code` when omitted.",
+                            type: "string",
+                        },
+                        data: {
+                            title: "Data",
+                            description: "Optional structured payload attached to the error.",
+                        },
+                    },
+                    required: ["code"],
+                },
+            },
+            required: ["throw"],
+        },
+        {
+            title: "value",
+            description: "Computes a value and publishes it as `steps.<name>.result`, with no dispatch — " +
+                "no resource, no span, no topology node. For an intermediate derived from an " +
+                "earlier step: reshape a response, total some rows, build the next call's inputs.",
+            properties: {
+                value: {
+                    title: "Value",
+                    description: "A CEL expression — or a structure (map / array) with `!cel` leaves — " +
+                        "evaluated in the step scope: `inputs`, the results of the steps before it, " +
+                        "and whatever the enclosing kind binds (`item` / `index` / `items`, " +
+                        "`iteration` / `previous`).",
+                },
+            },
+            required: ["value"],
+        },
+    ],
+    required: ["name"],
+};
+/** The fragments that CONTAIN THEMSELVES — a schema's properties hold schemas, a
+ *  step's branches hold steps. A reference to one is localized and hoisted
+ *  rather than expanded in place ({@link localizeRecursiveFragment}), because
+ *  inlining cannot terminate. */
+const RECURSIVE_FRAGMENTS = new Set(["JsonSchema7", "KindSchema", "Step"]);
 /** 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. */
+ *  they admit. Split from {@link RECURSIVE_FRAGMENTS} when `Step` landed: being
+ *  recursive is a fact about how a reference is RESOLVED, being a schema is a
+ *  fact about which vocabulary a slot admits, and `Step` is the first fragment
+ *  that is one without the other. */
 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
@@ -344,11 +589,53 @@ export const ManifestRootSchema = {
         RetryPolicy: RetryPolicySchema,
         RetryAttempts: RetryAttemptsSchema,
         InvokeStep: InvokeStepSchema,
+        Step: StepSchema,
         JsonSchema7: JsonSchema7Schema,
         KindSchema: KindSchemaSchema,
     },
 };
 deepFreeze(ManifestRootSchema);
+/**
+ * One expanded template per fragment, cloned per consumer.
+ *
+ * Expansion is a full walk of the body and the result is identical every time —
+ * `Step` alone is a couple of hundred nodes and `modules/run` hoists it four
+ * times, on the kernel's boot path. The copy handed out is still fresh, because
+ * downstream passes (`resolveSchemaRefKinds`, migrations) rewrite schemas in
+ * place.
+ */
+const expandedFragments = new Map();
+/**
+ * A fresh, fully expanded copy of a fragment body.
+ *
+ * TARGET-INDEPENDENT, which is what makes caching it correct: the walk is given
+ * a scratch hoist target and REFUSED if anything lands in it. A localized copy
+ * belongs in the schema a validator compiles, never inside another `$defs`
+ * entry, so a body that needed one could not have a single cached form — the
+ * first consumer would receive the entry and every later one would silently get
+ * a pointer to nothing. Nothing exercises that today: a recursive fragment
+ * writes its own self-references already localized, and a cross-reference
+ * between two recursive fragments is hoisted at the top level by
+ * {@link hoistFragmentDef}'s `pending` loop. If one ever does, this throws at
+ * the write instead of resolving by accident.
+ */
+function expandedFragment(name) {
+    let template = expandedFragments.get(name);
+    if (!template) {
+        const fragment = ManifestRootSchema.$defs[name];
+        template = structuredClone(fragment);
+        const scratch = {};
+        walkFragments(template, new Set(), { hoistTarget: scratch, depth: 1 });
+        if (scratch.$defs !== undefined) {
+            throw new Error(`Manifest fragment '${name}' references a recursive fragment from inside its body. ` +
+                `Its expanded form is no longer independent of where it is hoisted — localize the ` +
+                `reference in the fragment source (write '#/$defs/telo:<Name>' directly) or teach ` +
+                `expandedFragment to take the hoist target.`);
+        }
+        expandedFragments.set(name, template);
+    }
+    return structuredClone(template);
+}
 /** A private, expanded copy of a fragment, for a consumer that must EMBED one
  *  rather than `$ref` it — `builtins.ts` is not a manifest and never passes
  *  through the loader, so its dispatch site has to arrive already resolved and
@@ -358,7 +645,7 @@ export function manifestFragment(name) {
     if (!fragment || typeof fragment !== "object") {
         throw new Error(`Unknown manifest fragment '${name}'`);
     }
-    if (SCHEMA_FRAGMENTS.has(name)) {
+    if (RECURSIVE_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.
@@ -366,8 +653,7 @@ export function manifestFragment(name) {
             `point a slot at it with $ref: "${manifestFragmentRef(name)}" and pass the ` +
             `enclosing schema through withSchemaFragments().`);
     }
-    const copy = structuredClone(fragment);
-    expandManifestFragments(copy);
+    const copy = expandedFragment(name);
     copy[X_TELO_FRAGMENT] = name;
     return copy;
 }
@@ -469,7 +755,7 @@ function localizeRecursiveFragment(value, ctx) {
     if (typeof ref !== "string" || !ref.startsWith(FRAGMENT_PREFIX))
         return undefined;
     const name = ref.slice(FRAGMENT_PREFIX.length);
-    if (!SCHEMA_FRAGMENTS.has(name))
+    if (!RECURSIVE_FRAGMENTS.has(name))
         return undefined;
     hoistFragmentDef(ctx.hoistTarget, name);
     return { ...value, $ref: `#/$defs/${hoistedDefKey(name)}`, [X_TELO_FRAGMENT]: name };
@@ -492,8 +778,15 @@ function hoistFragmentDef(target, name) {
         // 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), [X_TELO_FRAGMENT]: next };
-        for (const nested of SCHEMA_FRAGMENTS) {
+        // A hoisted body may point at a NON-recursive fragment (`Step`'s dispatch
+        // branch is `InvokeStep`), and a copy left unexpanded carries a foreign
+        // `telo://manifest#/…` reference into a document the editor's resolver
+        // throws on — the same failure gating fragment expansion once caused. Where
+        // a nested LOCALIZED copy would belong is not this body; see
+        // {@link expandedFragment}, which refuses that case rather than guessing.
+        const body = expandedFragment(next);
+        defs[key] = { ...body, [X_TELO_FRAGMENT]: next };
+        for (const nested of RECURSIVE_FRAGMENTS) {
             if (nested !== next && referencesLocalDef(defs[key], nested))
                 pending.push(nested);
         }
@@ -562,10 +855,9 @@ function fragmentFor(value) {
     const fragment = ManifestRootSchema.$defs[name];
     if (!fragment || typeof fragment !== "object")
         return undefined;
-    const expanded = structuredClone(fragment);
     // A fragment may reference another (InvokeStep holds a RetryPolicy); the copy
-    // is expanded too, so one pass leaves no reference behind.
-    expandManifestFragments(expanded);
+    // arrives expanded, so one pass leaves no reference behind.
+    const expanded = expandedFragment(name);
     for (const [key, own] of Object.entries(node)) {
         if (key === "$ref")
             continue;

package/dist/module-compatibility.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Can this runtime host that module version? One question, one answer, one
+ * implementation — the CLI's `upgrade` and every IDE's upgrade affordance all
+ * ask it of a candidate version's `telo.yaml` text.
+ *
+ * It lives beside {@link readRequires} because the `requires:` grammar has
+ * exactly one reader by rule, and the moment a second host learned to filter
+ * candidates by compatibility that rule needed a shared verdict, not a second
+ * parser. Browser-safe: text in, verdict out, no transport and no filesystem —
+ * fetching the candidate manifest is the caller's job, since only the caller
+ * knows which transport (or cache) addresses it.
+ */
+import { type HostVersions } from "./requires-block.js";
+/**
+ * How a candidate version answered the compatibility question.
+ *
+ * `unknown` — the manifest could not be read or names no module document — is
+ * never treated as incompatible, since an unreachable registry must not
+ * silently freeze a consumer's imports.
+ *
+ * The two rejecting answers are kept APART because they call for different
+ * actions and the user is told which one applies: `too-new` is fixed by
+ * upgrading telo, `unreadable` cannot be fixed by the consumer at all.
+ * Collapsing them into one "no" and then printing "requires a newer telo" would
+ * assert a cause the check never established, and point at a runtime upgrade
+ * that will not help.
+ */
+export type ModuleCompatibility = "yes" | "too-new" | "unreadable" | "unknown";
+/**
+ * Read a module manifest's declared `requires:` and decide whether the runtime
+ * described by `teloVersion` / `host` can host it.
+ *
+ * A module that declares nothing is compatible — the bootstrap rule, permanent
+ * for everything published before the mechanism existed. A host that reports no
+ * version for an axis skips it rather than guessing, which is exactly the
+ * editor case: an IDE is not the machine that will run the manifest, so it
+ * speaks for the telo surface and for nothing else.
+ */
+export declare function manifestCompatibility(manifestText: string, teloVersion: string | undefined, host?: HostVersions): ModuleCompatibility;
+//# sourceMappingURL=module-compatibility.d.ts.map

package/dist/module-compatibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-compatibility.d.ts","sourceRoot":"","sources":["../src/module-compatibility.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,EAAkC,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExF;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,mBAAmB,GAAG,KAAK,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,CAAC;AAE/E;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,IAAI,GAAE,YAAiB,GACtB,mBAAmB,CAuBrB"}

package/dist/module-compatibility.js

@@ -0,0 +1,52 @@
+/**
+ * Can this runtime host that module version? One question, one answer, one
+ * implementation — the CLI's `upgrade` and every IDE's upgrade affordance all
+ * ask it of a candidate version's `telo.yaml` text.
+ *
+ * It lives beside {@link readRequires} because the `requires:` grammar has
+ * exactly one reader by rule, and the moment a second host learned to filter
+ * candidates by compatibility that rule needed a shared verdict, not a second
+ * parser. Browser-safe: text in, verdict out, no transport and no filesystem —
+ * fetching the candidate manifest is the caller's job, since only the caller
+ * knows which transport (or cache) addresses it.
+ */
+import { defaultCustomTags } from "@telorun/templating";
+import { parseAllDocuments } from "yaml";
+import { isModuleKind } from "./module-kinds.js";
+import { evaluateRequires, readRequires } from "./requires-block.js";
+/**
+ * Read a module manifest's declared `requires:` and decide whether the runtime
+ * described by `teloVersion` / `host` can host it.
+ *
+ * A module that declares nothing is compatible — the bootstrap rule, permanent
+ * for everything published before the mechanism existed. A host that reports no
+ * version for an axis skips it rather than guessing, which is exactly the
+ * editor case: an IDE is not the machine that will run the manifest, so it
+ * speaks for the telo surface and for nothing else.
+ */
+export function manifestCompatibility(manifestText, teloVersion, host = {}) {
+    let doc;
+    try {
+        for (const parsed of parseAllDocuments(manifestText, { customTags: defaultCustomTags() })) {
+            const value = parsed.toJS();
+            const kind = value?.kind;
+            if (typeof kind === "string" && isModuleKind(kind)) {
+                doc = value;
+                break;
+            }
+        }
+    }
+    catch {
+        return "unknown";
+    }
+    if (!doc)
+        return "unknown";
+    const { block, issues } = readRequires(doc);
+    // A malformed declaration is not a licence to install: the module claims a
+    // requirement it failed to state, and guessing which way it pointed is how a
+    // consumer ends up on a version that cannot load. The load gate warns about
+    // this same manifest, so the two halves agree.
+    if (issues.some((i) => !i.unknownAxis))
+        return "unreadable";
+    return evaluateRequires(block, teloVersion, host).satisfied ? "yes" : "too-new";
+}

package/dist/ref-slot-reading.d.ts

@@ -0,0 +1,30 @@
+export interface RefReadingScope {
+    /** The definition a canonical kind names. */
+    resolve(kind: string): Record<string, any> | undefined;
+    /** Canonicalizes an alias-qualified kind, for a slot whose constraint has not
+     *  been rewritten yet. */
+    resolveKind?(kind: string): string | undefined;
+}
+/**
+ * The reading schema for one ref slot, or undefined when the slot's constraint
+ * resolves to nothing — in which case the slot is left exactly as it was, the
+ * degrade-to-today direction every unresolved annotation takes here.
+ *
+ * A slot constrained to SEVERAL kinds types `status` from the kinds that agree
+ * and drops the rest: a read valid against one permitted target must not be
+ * rejected because a sibling kind does not declare that field.
+ */
+export declare function refSlotReadingSchema(slot: Record<string, any>, scope: RefReadingScope): Record<string, any> | undefined;
+/**
+ * Rewrite every ref slot in a kind's own `schema:` to what reading it yields, so
+ * the `self` CEL variable answers about published state rather than about the
+ * annotation node.
+ *
+ * A SCHEMA walk, so it recurses through `properties` / `items` /
+ * `additionalProperties` and nothing else — there is no inline-declaration
+ * boundary to stop at here, because a `kind` key inside a schema is a property
+ * NAMED kind, not a nested resource. Untouched subtrees keep their identity, so
+ * a schema declaring no ref slot is returned as it was.
+ */
+export declare function withRefSlotsAsReadings(schema: unknown, scope: RefReadingScope): unknown;
+//# sourceMappingURL=ref-slot-reading.d.ts.map

package/dist/ref-slot-reading.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref-slot-reading.d.ts","sourceRoot":"","sources":["../src/ref-slot-reading.ts"],"names":[],"mappings":"AA6BA,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC;IACvD;8BAC0B;IAC1B,WAAW,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CAChD;AAMD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACzB,KAAK,EAAE,eAAe,GACrB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAuBjC;AA6BD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,OAAO,EACf,KAAK,EAAE,eAAe,GACrB,OAAO,CAqBT"}

package/dist/ref-slot-reading.js

@@ -0,0 +1,139 @@
+/**
+ * What a `self.<refSlot>` READS as.
+ *
+ * A ref slot holds the live instance after Phase-5 injection, and the kernel
+ * substitutes each one with its last published reading before evaluating a
+ * template body (`celSelfView`) — so `self.table.name` and `resources.users.name`
+ * name the same fact. This is the static half of that equivalence: without it a
+ * ref slot's schema is whatever the kind wrote at the slot (a title, a
+ * description and the annotation), which types nothing at all.
+ *
+ * A published reading has two halves and they are typed differently, exactly as
+ * `resources.<name>` is:
+ *
+ *  - the FLAT half is what `snapshot()` returned, which no manifest declares, so
+ *    it stays open. Closing it would reject reads that are correct today, and
+ *    there is nothing to close it against.
+ *  - `status` is DECLARED (`status:` on the kind, folded along `extends`), so it
+ *    is typed and a typo below it is `CEL_UNKNOWN_FIELD`.
+ *
+ * Deliberately no attempt to type the flat half from the kind's own `schema:`:
+ * a snapshot is what the controller chose to publish, not the config it was
+ * given, and the two coincide only by convention. Typing one as the other would
+ * invent errors on a kind that publishes anything else.
+ *
+ * Browser-safe: no Node built-ins.
+ */
+import { effectiveStatusSchema } from "./extends-resolution.js";
+import { isRefSlot, readRefSlot } from "./ref-slot.js";
+function isObject(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * The reading schema for one ref slot, or undefined when the slot's constraint
+ * resolves to nothing — in which case the slot is left exactly as it was, the
+ * degrade-to-today direction every unresolved annotation takes here.
+ *
+ * A slot constrained to SEVERAL kinds types `status` from the kinds that agree
+ * and drops the rest: a read valid against one permitted target must not be
+ * rejected because a sibling kind does not declare that field.
+ */
+export function refSlotReadingSchema(slot, scope) {
+    const ref = readRefSlot(slot);
+    if (!ref || ref.kinds.length === 0)
+        return undefined;
+    const statuses = [];
+    for (const kind of ref.kinds) {
+        const canonical = scope.resolveKind?.(kind) ?? kind;
+        const definition = scope.resolve(canonical) ?? scope.resolve(kind);
+        if (!definition)
+            continue;
+        const status = effectiveStatusSchema(definition, (k) => scope.resolve(k));
+        if (isObject(status) && isObject(status.properties))
+            statuses.push(status);
+    }
+    if (statuses.length === 0)
+        return openReading(slot);
+    const shared = statuses.length === 1 ? statuses[0].properties : sharedProperties(statuses);
+    return {
+        ...describedBy(slot),
+        type: "object",
+        additionalProperties: true,
+        properties: {
+            status: { type: "object", additionalProperties: false, properties: shared },
+        },
+    };
+}
+/** Properties every candidate kind declares. A field only some of them report
+ *  is not one a read can rely on, and rejecting it would be wrong for the kinds
+ *  that do — so it degrades to the open half rather than to an error. */
+function sharedProperties(statuses) {
+    const [first, ...rest] = statuses;
+    const out = {};
+    for (const [name, schema] of Object.entries(first.properties)) {
+        if (rest.every((other) => name in other.properties)) {
+            out[name] = schema;
+        }
+    }
+    return out;
+}
+/** A reading whose `status` cannot be typed: open, so nothing new is rejected. */
+function openReading(slot) {
+    return { ...describedBy(slot), type: "object", additionalProperties: true };
+}
+/** The slot's own prose, kept so hover and completion still say what it is. */
+function describedBy(slot) {
+    const out = {};
+    if (typeof slot.title === "string")
+        out.title = slot.title;
+    if (typeof slot.description === "string")
+        out.description = slot.description;
+    return out;
+}
+/**
+ * Rewrite every ref slot in a kind's own `schema:` to what reading it yields, so
+ * the `self` CEL variable answers about published state rather than about the
+ * annotation node.
+ *
+ * A SCHEMA walk, so it recurses through `properties` / `items` /
+ * `additionalProperties` and nothing else — there is no inline-declaration
+ * boundary to stop at here, because a `kind` key inside a schema is a property
+ * NAMED kind, not a nested resource. Untouched subtrees keep their identity, so
+ * a schema declaring no ref slot is returned as it was.
+ */
+export function withRefSlotsAsReadings(schema, scope) {
+    if (Array.isArray(schema))
+        return schema.map((item) => withRefSlotsAsReadings(item, scope));
+    if (!isObject(schema))
+        return schema;
+    if (isRefSlot(schema))
+        return refSlotReadingSchema(schema, scope) ?? schema;
+    let changed = false;
+    const out = { ...schema };
+    for (const key of ["properties", "items", "additionalProperties"]) {
+        const node = schema[key];
+        if (node === undefined)
+            continue;
+        const next = key === "properties"
+            ? mapValues(node, (value) => withRefSlotsAsReadings(value, scope))
+            : withRefSlotsAsReadings(node, scope);
+        if (next !== node) {
+            out[key] = next;
+            changed = true;
+        }
+    }
+    return changed ? out : schema;
+}
+function mapValues(node, fn) {
+    if (!isObject(node))
+        return node;
+    let changed = false;
+    const out = {};
+    for (const [key, value] of Object.entries(node)) {
+        const next = fn(value);
+        if (next !== value)
+            changed = true;
+        out[key] = next;
+    }
+    return changed ? out : node;
+}