@telorun/analyzer 0.59.0 → 0.60.0

package/dist/manifest-schemas.d.ts

@@ -0,0 +1,407 @@
+/**
+ * Shared JSON-Schema fragments every module's `telo.yaml` may point at with
+ * `$ref: "telo://manifest#/$defs/<Name>"`.
+ *
+ * WHY THE ANALYZER OWNS THEM. These describe manifest structure, which is what
+ * this package exists to read — and the layering forces the choice anyway: the
+ * editor validates in a browser through `@telorun/analyzer`, and the analyzer
+ * must not depend on the kernel. A fragment in the kernel would exist only at
+ * runtime, so `telo check` and the editor could not see a step's shape at all.
+ * The kernel re-exports these from its own `manifest-schemas` surface, and both
+ * halves register the same root document with AJV, so a `$ref` resolves
+ * identically in the editor, in `telo check` and at dispatch.
+ *
+ * A fragment here is STRUCTURE, not a named user type. The two are different
+ * mechanisms and both exist:
+ *
+ *   - `#/$defs/<Name>` is private to the declaring kind's own schema — Run's
+ *     `WhileStep` is Run's business and nothing outside it can name one.
+ *   - `telo://manifest#/$defs/<Name>` is this set: shapes the kernel defines, so
+ *     several unrelated documents can agree on one. `builtins.ts` is not a module
+ *     document and has no `$defs` any module could reach, which is why a shared
+ *     shape cannot live in one of the modules that use it.
+ *   - `telo:<module>/<Type>` names a `Telo.JsonSchema` resource a MODULE
+ *     declared, resolved through the type registry and carrying its owner so two
+ *     libraries may both declare a `Filter`.
+ *
+ * Adding a fragment means putting it under `$defs` in {@link ManifestRootSchema}
+ * and `$ref`-ing it from module schemas. Browser-safe: no Node built-ins.
+ */
+export declare const MANIFEST_SCHEMA_URI = "telo://manifest";
+/** `$ref` to a fragment in this set, as a module schema writes it. */
+export declare function manifestFragmentRef(name: string): string;
+/** Schema fragment for a resource-reference slot. The only form a manifest
+ *  author writes is the `!ref <name>` (or `!ref <Alias>.<name>`) YAML tag,
+ *  which parses to a `TaggedSentinel` (engine "ref") whose `source` is the
+ *  bare resource name. In practice module schemas mark a ref slot with a bare
+ *  `x-telo-ref` annotation (plus, where the slot only ever holds a reference,
+ *  `type: object` to reject a stray scalar); the analyzer's reference walker
+ *  reads `x-telo-ref` to look the name up against that constraint, independent
+ *  of this fragment. A slot opts into this fragment only when it wants this
+ *  exact two-branch shape enforced at the AJV layer too — it is not required,
+ *  and slots that also accept an inline value (e.g. `inputType` / `outputType`)
+ *  deliberately do not use it (an inline JSON Schema has no `kind`).
+ *
+ *  Two `anyOf` branches because the value's shape depends on the phase at
+ *  which it is validated:
+ *
+ *   1. The raw `!ref` sentinel — what survives to AJV when a cross-module
+ *      reference can't be resolved in standalone single-file analysis (the
+ *      imported module isn't loaded). `substituteCelFields` deliberately
+ *      keeps the sentinel so this branch matches.
+ *   2. A resolved reference object — `{kind, name, alias?}` substituted in
+ *      place of a sentinel (or an inline definition `{kind, ...config}`
+ *      reached through a local `$ref` that escapes extraction). Both the
+ *      kernel and the analyzer validate ref slots *after* sentinel
+ *      resolution, so this is the shape AJV usually sees.
+ *
+ *  The object-form `{kind, name}` reference a user could once type directly
+ *  is gone: a plain object at a ref slot is only ever an inline definition
+ *  or the resolver's own substitution, never an author-written reference.
+ *  That removal is enforced by the analyzer (it rejects an author-written
+ *  `{kind, name}` before normalization), not by this schema — branch 2
+ *  cannot distinguish an author's `{kind, name}` from the resolver's. */
+export declare const ResourceRefSchema: {
+    title: string;
+    anyOf: ({
+        type: string;
+        required: string[];
+        properties: {
+            __tagged: {
+                const: boolean;
+            };
+            engine: {
+                const: string;
+            };
+            source: {
+                type: string;
+                minLength: number;
+            };
+            kind?: undefined;
+        };
+        additionalProperties: boolean;
+    } | {
+        type: string;
+        required: string[];
+        properties: {
+            kind: {
+                type: string;
+            };
+            __tagged?: undefined;
+            engine?: undefined;
+            source?: undefined;
+        };
+        additionalProperties: boolean;
+    })[];
+};
+/**
+ * How a dispatch is re-attempted.
+ *
+ * ONE shape, because a retry policy is a cross-cutting primitive rather than
+ * each composer's own idea: it was written out six times across `run` and
+ * `http-client` and had already drifted — one copy declared no defaults, another
+ * carried a field the others lacked. Defaults live here, so the Node step leaf
+ * and a second-language one read the same numbers instead of each re-deriving
+ * them from the other's source.
+ *
+ * `delay` survives as the older duration-string spelling because published
+ * manifests carry it, and it cannot be migrated away: a migration entry writes a
+ * SCALAR, and `"250ms"` → `250` is a computation the vocabulary deliberately
+ * cannot express.
+ */
+export declare const RetryPolicySchema: {
+    title: string;
+    description: string;
+    type: string;
+    additionalProperties: boolean;
+    properties: {
+        attempts: {
+            title: string;
+            description: string;
+            type: string;
+            minimum: number;
+            default: number;
+        };
+        initialDelay: {
+            title: string;
+            description: string;
+            type: string;
+            minimum: number;
+            default: number;
+        };
+        factor: {
+            title: string;
+            description: string;
+            type: string;
+            minimum: number;
+            default: number;
+        };
+        maxDelay: {
+            title: string;
+            description: string;
+            type: string;
+            minimum: number;
+            default: number;
+        };
+        jitter: {
+            title: string;
+            description: string;
+            type: string;
+            enum: string[];
+            default: string;
+        };
+        delay: {
+            title: string;
+            description: string;
+            type: string;
+            pattern: string;
+        };
+    };
+};
+/**
+ * The bare-count spelling of a re-attempt — `Http.Request.retries`, deprecated
+ * but carried by every manifest published before `retry:` existed.
+ *
+ * Its own fragment rather than a special case in the reader: what a consumer
+ * needs to know is WHERE the budget is, and pointing at this shape says "the
+ * value itself" as precisely as pointing at a policy says "its `attempts`". It
+ * cannot be migrated to the policy form — a migration entry writes a scalar, and
+ * wrapping one in an object is not something the vocabulary can express.
+ */
+export declare const RetryAttemptsSchema: {
+    title: string;
+    description: string;
+    type: string;
+    minimum: number;
+    default: number;
+};
+/**
+ * A DISPATCH SITE: name a target, pass it arguments, optionally guard it,
+ * optionally re-attempt it.
+ *
+ * The runtime has always had exactly one of these — `InvokeStep` in the SDK, run
+ * by `executeInvokeStep`, which every dispatch passes through. What did not exist
+ * was the schema half: the shape was hand-restated by each composer (four times
+ * in `run`, once in `builtins.ts`) and they drifted, which is why `retry:` worked
+ * in a sequence step and was a schema error one line away in `targets:` — not a
+ * decision anyone made about boot, just a copy that never grew the field.
+ *
+ * Owning it here is also what retired `x-telo-retry` for a step: the analyzer
+ * reads `step.retry.attempts` because that is what a step IS, rather than
+ * discovering a retry-bearing field through a marker the kind had to remember to
+ * write.
+ *
+ * `name` is optional: a boot target only needs one to publish
+ * `steps.<name>.result`, and a composer that requires one says so in its own
+ * schema. Closed, so a misspelled key is rejected wherever a dispatch is written.
+ */
+export declare const InvokeStepSchema: {
+    title: string;
+    description: string;
+    type: string;
+    required: string[];
+    additionalProperties: boolean;
+    properties: {
+        name: {
+            title: string;
+            description: string;
+            type: string;
+        };
+        invoke: {
+            title: string;
+            description: string;
+            "x-telo-topology-role": string;
+            type: string;
+            "x-telo-ref": {
+                kind: string;
+                use: string;
+                inputs: string;
+            };
+        };
+        inputs: {
+            title: string;
+            description: string;
+            "x-telo-topology-role": string;
+            type: string;
+            additionalProperties: boolean;
+        };
+        when: {
+            title: string;
+            description: string;
+            type: string;
+        };
+        retry: {
+            title: string;
+            $ref: string;
+        };
+    };
+};
+/** Root schema registered with AJV under {@link MANIFEST_SCHEMA_URI}. Carries
+ *  `$defs` only — it isn't validated against directly. */
+export declare const ManifestRootSchema: {
+    $id: string;
+    $defs: {
+        ResourceRef: {
+            title: string;
+            anyOf: ({
+                type: string;
+                required: string[];
+                properties: {
+                    __tagged: {
+                        const: boolean;
+                    };
+                    engine: {
+                        const: string;
+                    };
+                    source: {
+                        type: string;
+                        minLength: number;
+                    };
+                    kind?: undefined;
+                };
+                additionalProperties: boolean;
+            } | {
+                type: string;
+                required: string[];
+                properties: {
+                    kind: {
+                        type: string;
+                    };
+                    __tagged?: undefined;
+                    engine?: undefined;
+                    source?: undefined;
+                };
+                additionalProperties: boolean;
+            })[];
+        };
+        RetryPolicy: {
+            title: string;
+            description: string;
+            type: string;
+            additionalProperties: boolean;
+            properties: {
+                attempts: {
+                    title: string;
+                    description: string;
+                    type: string;
+                    minimum: number;
+                    default: number;
+                };
+                initialDelay: {
+                    title: string;
+                    description: string;
+                    type: string;
+                    minimum: number;
+                    default: number;
+                };
+                factor: {
+                    title: string;
+                    description: string;
+                    type: string;
+                    minimum: number;
+                    default: number;
+                };
+                maxDelay: {
+                    title: string;
+                    description: string;
+                    type: string;
+                    minimum: number;
+                    default: number;
+                };
+                jitter: {
+                    title: string;
+                    description: string;
+                    type: string;
+                    enum: string[];
+                    default: string;
+                };
+                delay: {
+                    title: string;
+                    description: string;
+                    type: string;
+                    pattern: string;
+                };
+            };
+        };
+        RetryAttempts: {
+            title: string;
+            description: string;
+            type: string;
+            minimum: number;
+            default: number;
+        };
+        InvokeStep: {
+            title: string;
+            description: string;
+            type: string;
+            required: string[];
+            additionalProperties: boolean;
+            properties: {
+                name: {
+                    title: string;
+                    description: string;
+                    type: string;
+                };
+                invoke: {
+                    title: string;
+                    description: string;
+                    "x-telo-topology-role": string;
+                    type: string;
+                    "x-telo-ref": {
+                        kind: string;
+                        use: string;
+                        inputs: string;
+                    };
+                };
+                inputs: {
+                    title: string;
+                    description: string;
+                    "x-telo-topology-role": string;
+                    type: string;
+                    additionalProperties: boolean;
+                };
+                when: {
+                    title: string;
+                    description: string;
+                    type: string;
+                };
+                retry: {
+                    title: string;
+                    $ref: string;
+                };
+            };
+        };
+    };
+};
+/** 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
+ *  already stamped. Cloned for the reason {@link deepFreeze} explains. */
+export declare function manifestFragment(name: string): Record<string, unknown>;
+/**
+ * Replace every `telo://manifest#/$defs/<Name>` reference with the fragment
+ * itself, in place, throughout a parsed manifest.
+ *
+ * EXPANDED rather than left as a reference, which is the opposite of what
+ * `resolveSchemaTypeRefs` does for a named user type — and for the opposite
+ * reasons. A user type must stay a reference because it can recurse and because
+ * the compiled-validator cache is keyed on schema identity. These fragments are a
+ * closed, non-recursive set the analyzer itself owns, and expanding them is what
+ * keeps a composer that points at a shared shape legible to walks that never
+ * resolved anything: the CEL-placeholder substitution, the eval-path collector,
+ * the editor's field walk. Teaching each of those to follow a reference is the
+ * same fix applied N times, and the failure mode when one is missed is silent —
+ * a role-driven lookup finds nothing and the check it feeds simply stops
+ * reporting.
+ *
+ * Runs in the shared loader, so both kernels' Node halves and every consumer of a
+ * loaded manifest see the same expanded shape.
+ */
+export declare function expandManifestFragments(node: unknown, seen?: Set<object>): void;
+/** Stamped by {@link expandManifestFragments} with the name of the shared
+ *  fragment a slot pointed at. Derived, never author-written. */
+export declare const X_TELO_FRAGMENT = "x-telo-fragment";
+/** The shared fragment a schema node was expanded from, or undefined. The one
+ *  accessor every consumer reads the stamp through. */
+export declare function manifestFragmentOf(schema: unknown): string | undefined;
+//# sourceMappingURL=manifest-schemas.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-schemas.d.ts","sourceRoot":"","sources":["../src/manifest-schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,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;AAiBF;0DAC0D;AAC1D,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAQ9B,CAAC;AAIF;;;0EAG0E;AAC1E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAStE;AAID;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,cAAoB,GAAG,IAAI,CAoBrF;AA+DD;iEACiE;AACjE,eAAO,MAAM,eAAe,oBAAoB,CAAC;AAEjD;uDACuD;AACvD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAItE"}