@telorun/analyzer 0.61.0 → 0.62.1

package/dist/identifier-name.js

@@ -0,0 +1,183 @@
+/**
+ * Naming rules for every author-written Telo identifier — resource instances,
+ * kinds, modules, import aliases, step names, config declarations and CEL
+ * bindings. The single reader, so no surface re-derives the vocabulary; the
+ * `ref-slot.ts` / `zone-slot.ts` precedent.
+ *
+ * **The rules exist because Telo has no lexer.** A name is a YAML scalar, so
+ * nothing rejects its shape where it is declared, and every consequence
+ * surfaces later at a CEL site that references it — or not at all. Probed
+ * against the engine the runtime actually uses (`@marcbachmann/cel-js`):
+ *
+ *     resources.my-server.url  →  EVALUATES, as `resources.my - server.url`
+ *     resources.in             →  ParseError: Expected IDENTIFIER, got IN
+ *     resources.2fa            →  ParseError
+ *     resources.for            →  parses fine
+ *
+ * The first line is the one that decides the design. When a bare name is in
+ * scope — which `x-telo-bindings-from` deliberately makes possible — a
+ * hyphenated resource name yields a wrong number with no diagnostic anywhere.
+ * That is a swallowed error in the reference grammar, not a style preference.
+ * The last line is why the reserved set here is the whole keyword list rather
+ * than the subset today's parser happens to reject in field position: which
+ * keywords tokenize there is a property of a dependency, and a name that
+ * breaks on a parser upgrade was never safe.
+ *
+ * **Three tiers, because they fail in three different ways.**
+ *
+ * 1. `INVALID_NAME` (error, every surface) — not a CEL-safe identifier, or a
+ *    CEL keyword. Below this line the name is unreferenceable or silently
+ *    mis-referenced. This subsumes the old dot-only rule, which was the
+ *    strictest special case of it: `!ref` splits on the first dot.
+ *
+ * 2. `INVALID_TYPE_NAME` (error) — a type-level name not starting uppercase.
+ *    An error rather than a warning because half the reference grammar already
+ *    rejects the alternative: `EXTENDS_ALIAS_PATTERN` in the kernel's manifest
+ *    schema hard-rejects `extends: foo.Bar`, while nothing rejects the
+ *    `metadata.name: foo` that produced it. A lowercase kind is a kind nobody
+ *    can extend, so this only moves an existing failure to where it is
+ *    fixable.
+ *
+ * 3. `NAME_CASE_CONVENTION` (warning) — a value-level name not starting
+ *    lowercase. Warn-only, Rust's `non_snake_case` posture: a name is
+ *    occasionally dictated from outside, and Telo has no `#[allow]`, so a hard
+ *    error would leave no escape.
+ *
+ * **The convention: case encodes what the name denotes.** PascalCase names a
+ * *type* — something writable in `kind:` / `extends:` / an `x-telo-ref` or type
+ * slot. camelCase names a *value* — something holding data at runtime, read
+ * through `resources.` / `steps.` / `variables.` in CEL. That is what
+ * distinguishes `kind: Console.WriteLine` from `!ref Console.writeLine`, two
+ * character-identical grammars otherwise, and the collision is not
+ * hypothetical: it is the sanctioned singleton pattern (declare
+ * `kind: Self.WriteLine`, export the instance, withhold the kind).
+ *
+ * **Only the first character is checked.** A full camelCase pattern would
+ * relitigate `httpApi` vs `httpAPI` and `OAuthClient` vs `OauthClient` with no
+ * benefit — the first character is what carries the type/value signal, and a
+ * stricter rule would fight legitimate names containing acronyms or digits
+ * while owning a judgement nobody asked this pass to make. An
+ * entirely-acronym type name (`SQL`, `AI`) passes unchanged.
+ *
+ * **No `DiagnosticFix`.** A fix is a whole-value replacement for ONE node,
+ * and a rename is only correct when every reference moves with it — offering
+ * one here would rewrite `metadata.name` and break every `!ref` and CEL read
+ * of it. Renaming belongs to a refactor that owns the reference graph.
+ *
+ * Browser-safe: pure string predicates, no I/O, no Node built-ins.
+ */
+import { DiagnosticSeverity } from "./types.js";
+/**
+ * CEL keywords. A name matching one is unreachable — `true` lexes as a
+ * literal, `in` as an operator — so it is reserved everywhere a name becomes a
+ * CEL identifier, which is every surface this file governs.
+ */
+export const CEL_RESERVED_WORDS = [
+    "as",
+    "break",
+    "const",
+    "continue",
+    "else",
+    "false",
+    "for",
+    "function",
+    "if",
+    "import",
+    "in",
+    "let",
+    "loop",
+    "namespace",
+    "null",
+    "package",
+    "return",
+    "true",
+    "var",
+    "void",
+    "while",
+];
+const RESERVED = new Set(CEL_RESERVED_WORDS);
+/** What a CEL identifier may be — and therefore what a name that will be read
+ *  through `resources.` / `steps.` / `variables.` must be. */
+const CEL_IDENTIFIER_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Document kinds whose `metadata.name` is type-level. Everything else
+ *  declaring a name is a resource instance, whose level is decided by its
+ *  kind's capability (see {@link NameLevel}). */
+export const TYPE_LEVEL_DOC_KINDS = new Set([
+    "Telo.Application",
+    "Telo.Library",
+    "Telo.Definition",
+    "Telo.Abstract",
+    "Telo.Import",
+]);
+/**
+ * Check one author-written name.
+ *
+ * `surface` is the noun phrase naming what was declared ("resource name",
+ * "step name", "import alias"), used as the message's subject.
+ *
+ * Returns the first violation only: the tiers are ordered by how badly the
+ * name is broken, and telling an author their unparseable name is also
+ * miscased buries the part that matters.
+ */
+export function checkName(name, level, surface) {
+    const subject = `${surface} '${name}'`;
+    if (!CEL_IDENTIFIER_RE.test(name)) {
+        return {
+            tier: "grammar",
+            code: "INVALID_NAME",
+            severity: DiagnosticSeverity.Error,
+            message: `${subject} must match /^[A-Za-z_][A-Za-z0-9_]*$/ — ${grammarReason(name, level)}`,
+        };
+    }
+    if (RESERVED.has(name)) {
+        return {
+            tier: "reserved",
+            code: "INVALID_NAME",
+            severity: DiagnosticSeverity.Error,
+            message: `${subject} is a CEL keyword, so no expression can reference it. Rename it.`,
+        };
+    }
+    const first = name[0];
+    if (level === "type" && !(first >= "A" && first <= "Z")) {
+        return {
+            tier: "case",
+            code: "INVALID_TYPE_NAME",
+            severity: DiagnosticSeverity.Error,
+            message: `${subject} must start with an uppercase letter — it names a type, and the ` +
+                `alias-qualified grammar of 'kind:' / 'extends:' accepts only PascalCase.`,
+        };
+    }
+    if (level === "value" && !(first >= "a" && first <= "z")) {
+        return {
+            tier: "case",
+            code: "NAME_CASE_CONVENTION",
+            severity: DiagnosticSeverity.Warning,
+            message: `${subject} should start with a lowercase letter — camelCase names a value (read ` +
+                `through a CEL scope), PascalCase names a type.`,
+        };
+    }
+    return undefined;
+}
+/**
+ * Why the character set is what it is — which differs by level, and saying so
+ * accurately matters more than one shared sentence. A value-level name becomes
+ * a CEL identifier. A type-level name never does: it is a kind prefix or
+ * suffix, so what constrains it is the alias-qualified `<Alias>.<Kind>` grammar
+ * (`EXTENDS_ALIAS_PATTERN` in the kernel's manifest schema), which accepts the
+ * same characters for its own reasons.
+ */
+function grammarReason(name, level) {
+    if (level === "type") {
+        return name.includes(".")
+            ? `a '.' separates the two halves of every '<Alias>.<Kind>' reference, so a dotted name cannot appear in either.`
+            : `that is the character set the alias-qualified '<Alias>.<Kind>' grammar accepts on both sides.`;
+    }
+    if (name.includes("-")) {
+        return (`it becomes a CEL identifier and CEL reads '-' as subtraction, so where a bare name is in ` +
+            `scope this evaluates as arithmetic instead of failing.`);
+    }
+    if (name.includes(".")) {
+        return `in a '!ref' the first '.' separates the import alias from the name.`;
+    }
+    return `it becomes a CEL identifier, so as written it cannot be referenced.`;
+}

package/dist/index.d.ts

@@ -7,6 +7,8 @@ export { collectZoneModuleDocuments, flattenForAnalyzer, flattenLoadedModule, fo
 export { buildEvalPaths, evalPathCovers } from "./eval-paths.js";
 export { BINDINGS_ANNOTATION, bindingContextProperties, bindingDependencies, findBindingSites, resolveBindingOrder, } from "./cel-bindings.js";
 export type { BindingSites } from "./cel-bindings.js";
+export { CEL_RESERVED_WORDS, TYPE_LEVEL_DOC_KINDS, checkName, } from "./identifier-name.js";
+export type { NameLevel, NameViolation } from "./identifier-name.js";
 export { applyObservedStateNode, buildObservedStateIndex, buildObservedStateResourcesSchema, collectRunReachableNames, observedStateRead, validateObservedStateDeclarations, OBSERVED_STATE_SCHEMA, } from "./validate-observed-state.js";
 export type { AnalyzedResource, ObservedStateRead } from "./validate-observed-state.js";
 export { moduleScopedDefResolver, scopeResolverForModule } from "./alias-resolver.js";
@@ -26,6 +28,13 @@ export type { RefSlot, RefUse, RefUseCases } from "./ref-slot.js";
 export { ANNOTATION_KEYWORDS, registerTeloKeywords, valueTypeKeyword, } from "./value-type-keyword.js";
 export { applyTextEdits, isPlainSafe, quoteStyleOf, renderFixReplacement, } from "./yaml-source-edit.js";
 export type { QuoteStyle, TextEdit } from "./yaml-source-edit.js";
+export { KNOWN_HOST_AXES, evaluateRequires, readRequires } from "./requires-block.js";
+export type { HostAxis, HostVersions, ReadRequiresResult, RequiresBlock, RequiresIssue, RequiresVerdict, } from "./requires-block.js";
+export { TELO_SURFACE_VERSION } from "./telo-version.js";
+export { validateRequires } from "./validate-requires.js";
+export type { ValidateRequiresOptions } from "./validate-requires.js";
+export { isUnsatisfiable, lowerBound, parseVersionRange, rangeAccepts, upperBound, } from "./version-range.js";
+export type { ComparatorOperator, VersionComparator, VersionRange, VersionRangeResult, } from "./version-range.js";
 export { hasProvidesZone, hasRequiresZone, readProvidesZone, readRequiresZone, rewriteRequiresZoneKind, } from "./zone-slot.js";
 export type { ProvidesZoneSlot, RequiresZoneSlot } from "./zone-slot.js";
 export { deriveLibraryExportRequirements, projectZoneRequirements, runZoneAnalysis, zoneDocumentsSignature, } from "./resolve-zone-requirements.js";
@@ -88,6 +97,7 @@ export type { CelNode, CelSegment } from "./cel-ast.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";
+export * from "./schema-keywords.js";
 export { DERIVED_METADATA_FIELDS, authoredModuleMetadata, } from "./module-metadata-scope.js";
 export * from "./release/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -4,6 +4,7 @@ export { importResolutionDiagnostics } from "./import-resolution-diagnostics.js"
 export { collectZoneModuleDocuments, flattenForAnalyzer, flattenLoadedModule, forwardReExportManifests, parseExportEntry, reExportSpecsFromExports, resolveExportedKinds, selectModuleManifestsForAnalysis, stampExportedKinds, stampReExportedKinds, } from "./flatten-for-analyzer.js";
 export { buildEvalPaths, evalPathCovers } from "./eval-paths.js";
 export { BINDINGS_ANNOTATION, bindingContextProperties, bindingDependencies, findBindingSites, resolveBindingOrder, } from "./cel-bindings.js";
+export { CEL_RESERVED_WORDS, TYPE_LEVEL_DOC_KINDS, checkName, } from "./identifier-name.js";
 export { applyObservedStateNode, buildObservedStateIndex, buildObservedStateResourcesSchema, collectRunReachableNames, observedStateRead, validateObservedStateDeclarations, OBSERVED_STATE_SCHEMA, } from "./validate-observed-state.js";
 export { moduleScopedDefResolver, scopeResolverForModule } from "./alias-resolver.js";
 export { ancestorChain, contractDeclarer, controllerBearingAncestor, effectiveAuthorSchema, effectiveContractField, effectiveStatusSchema, hasOwnControllerOrTemplate, inheritedCapability, isInheritedDelegation, mappingFieldFor, needsContractMapping, resolveParent, } from "./extends-resolution.js";
@@ -14,6 +15,10 @@ export { buildReferenceFieldMap, isRefEntry, isScopeEntry } from "./reference-fi
 export { hasDeclaredUse, isRefSlot, isRefUse, possibleUses, readRefSlot, REF_USES, refSlotAnnotation, rewriteRefSlotKinds, transfersControl, } from "./ref-slot.js";
 export { ANNOTATION_KEYWORDS, registerTeloKeywords, valueTypeKeyword, } from "./value-type-keyword.js";
 export { applyTextEdits, isPlainSafe, quoteStyleOf, renderFixReplacement, } from "./yaml-source-edit.js";
+export { KNOWN_HOST_AXES, evaluateRequires, readRequires } from "./requires-block.js";
+export { TELO_SURFACE_VERSION } from "./telo-version.js";
+export { validateRequires } from "./validate-requires.js";
+export { isUnsatisfiable, lowerBound, parseVersionRange, rangeAccepts, upperBound, } from "./version-range.js";
 export { hasProvidesZone, hasRequiresZone, readProvidesZone, readRequiresZone, rewriteRequiresZoneKind, } from "./zone-slot.js";
 export { deriveLibraryExportRequirements, projectZoneRequirements, runZoneAnalysis, zoneDocumentsSignature, } from "./resolve-zone-requirements.js";
 export { validateZoneSlotDeclarations } from "./validate-zone-slots.js";
@@ -53,6 +58,9 @@ export { documentToAst, parseToAst } from "./yaml-ast.js";
 export { CelParseError, buildCelSegments, wrapCelAst } from "./cel-ast.js";
 export { DEFAULT_MANIFEST_FILENAME, DiagnosticSeverity, diagnosticFix } from "./types.js";
 export * from "./manifest-schemas.js";
+// The JSON Schema vocabulary a manifest may write, as data — the source both the
+// validating fragments and the IDE's completion are built from.
+export * from "./schema-keywords.js";
 // The release model — module identity, fragments, the ledger, the edge graph and
 // version planning. Pure data in, plan out, so the editor and the CLI release
 // from one model.

package/dist/manifest-schemas.d.ts

@@ -236,6 +236,64 @@ export declare const InvokeStepSchema: {
         };
     };
 };
+/**
+ * A JSON Schema an author writes as a manifest VALUE — an `inputType:`, an
+ * `outputType:`, a `status:` block, an API route's `request.schema`.
+ *
+ * Declared so the surfaces that read a slot's schema learn what lives there. A
+ * slot spelled `type: object` told them "some object": completion offered
+ * nothing from the first key down, hover had nothing to show, and a misspelled
+ * keyword travelled to a runtime failure that named the wrong field.
+ *
+ * OPEN, deliberately (`additionalProperties: true`, `type` admitting the
+ * boolean form a nested `additionalProperties: false` takes). The keyword set
+ * below is draft-07's — the dialect AJV actually runs — and everything outside
+ * it, every `x-telo-*` annotation included, passes through untouched. Closing
+ * this would reject the next annotation the moment a module invented one, for a
+ * check nobody asked for; what it buys as it stands is the value of a keyword
+ * an author DID write (`required: "name"`, `type: 5`) being wrong at
+ * `telo check` rather than at dispatch.
+ *
+ * RECURSIVE, which is why it is not expanded in place like the fragments above
+ * it: a schema's properties hold schemas. `expandManifestFragments` rewrites a
+ * reference to this to the document-local `#/$defs/JsonSchema7` and hoists one
+ * copy to the enclosing schema's root, so the pointer resolves inside whatever
+ * AJV compiles, and the editor's local-only `$ref` resolver keeps working.
+ */
+export declare const JsonSchema7Schema: {
+    title: string;
+    description: string;
+    type: string[];
+    properties: import("./schema-keywords.js").SchemaKeywords;
+    additionalProperties: boolean;
+};
+/**
+ * The schema a KIND declares for its own configuration — a `Telo.Definition`'s
+ * `schema:` block.
+ *
+ * The same body as {@link JsonSchema7Schema}, under its own name because the
+ * name is the discriminator: a kind's schema is where the `x-telo-*` vocabulary
+ * belongs (`x-telo-eval`, `x-telo-ref`, `x-telo-scope`, …) and a plain data
+ * schema is where it does not. Completion reads the `x-telo-fragment` stamp to
+ * decide which vocabulary to offer, exactly as a retry-budget consumer reads
+ * which of `RetryPolicy` / `RetryAttempts` a slot pointed at.
+ *
+ * The annotations are NOT properties here — see `schema-keywords.ts` for why a
+ * literal `x-telo-*` key inside a hoisted `properties` map would read to the
+ * annotation walkers as a slot the author never wrote.
+ */
+export declare const KindSchemaSchema: {
+    title: string;
+    description: string;
+    type: string[];
+    properties: import("./schema-keywords.js").SchemaKeywords;
+    additionalProperties: boolean;
+};
+/** 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
+ *  `schema`. The one accessor every consumer asks, so no surface re-spells the
+ *  set. */
+export declare function isSchemaFragment(name: string | undefined): boolean;
 /** Root schema registered with AJV under {@link MANIFEST_SCHEMA_URI}. Carries
  *  `$defs` only — it isn't validated against directly. */
 export declare const ManifestRootSchema: {
@@ -371,6 +429,20 @@ export declare const ManifestRootSchema: {
                 };
             };
         };
+        JsonSchema7: {
+            title: string;
+            description: string;
+            type: string[];
+            properties: import("./schema-keywords.js").SchemaKeywords;
+            additionalProperties: boolean;
+        };
+        KindSchema: {
+            title: string;
+            description: string;
+            type: string[];
+            properties: import("./schema-keywords.js").SchemaKeywords;
+            additionalProperties: boolean;
+        };
     };
 };
 /** A private, expanded copy of a fragment, for a consumer that must EMBED one
@@ -398,6 +470,15 @@ export declare function manifestFragment(name: string): Record<string, unknown>;
  * loaded manifest see the same expanded shape.
  */
 export declare function expandManifestFragments(node: unknown, seen?: Set<object>): void;
+/**
+ * Expand fragments in a schema that never passes through the loader —
+ * `builtins.ts` is not a manifest, so its slots have to arrive already
+ * localized, with the hoisted `$defs` at the root of the schema AJV compiles.
+ *
+ * Returns the same object, expanded in place, for use as a declaration
+ * initializer.
+ */
+export declare function withSchemaFragments<T extends Record<string, unknown>>(schema: T): T;
 /** 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";

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;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"}
+{"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"}

package/dist/manifest-schemas.js

@@ -27,6 +27,8 @@
  * Adding a fragment means putting it under `$defs` in {@link ManifestRootSchema}
  * and `$ref`-ing it from module schemas. Browser-safe: no Node built-ins.
  */
+import { jsonSchemaKeywords } from "./schema-keywords.js";
+import { SCHEMA_REGION_KEYS } from "./schema-region.js";
 export const MANIFEST_SCHEMA_URI = "telo://manifest";
 /** `$ref` to a fragment in this set, as a module schema writes it. */
 export function manifestFragmentRef(name) {
@@ -236,6 +238,88 @@ export const InvokeStepSchema = {
         },
     },
 };
+/**
+ * A JSON Schema an author writes as a manifest VALUE — an `inputType:`, an
+ * `outputType:`, a `status:` block, an API route's `request.schema`.
+ *
+ * Declared so the surfaces that read a slot's schema learn what lives there. A
+ * slot spelled `type: object` told them "some object": completion offered
+ * nothing from the first key down, hover had nothing to show, and a misspelled
+ * keyword travelled to a runtime failure that named the wrong field.
+ *
+ * OPEN, deliberately (`additionalProperties: true`, `type` admitting the
+ * boolean form a nested `additionalProperties: false` takes). The keyword set
+ * below is draft-07's — the dialect AJV actually runs — and everything outside
+ * it, every `x-telo-*` annotation included, passes through untouched. Closing
+ * this would reject the next annotation the moment a module invented one, for a
+ * check nobody asked for; what it buys as it stands is the value of a keyword
+ * an author DID write (`required: "name"`, `type: 5`) being wrong at
+ * `telo check` rather than at dispatch.
+ *
+ * RECURSIVE, which is why it is not expanded in place like the fragments above
+ * it: a schema's properties hold schemas. `expandManifestFragments` rewrites a
+ * reference to this to the document-local `#/$defs/JsonSchema7` and hoists one
+ * copy to the enclosing schema's root, so the pointer resolves inside whatever
+ * AJV compiles, and the editor's local-only `$ref` resolver keeps working.
+ */
+export const JsonSchema7Schema = {
+    title: "JSON Schema",
+    description: "The shape of a value, as JSON Schema (draft-07).",
+    type: ["object", "boolean"],
+    properties: jsonSchemaKeywords(hoistedDefKey("JsonSchema7")),
+    additionalProperties: true,
+};
+/**
+ * The schema a KIND declares for its own configuration — a `Telo.Definition`'s
+ * `schema:` block.
+ *
+ * The same body as {@link JsonSchema7Schema}, under its own name because the
+ * name is the discriminator: a kind's schema is where the `x-telo-*` vocabulary
+ * belongs (`x-telo-eval`, `x-telo-ref`, `x-telo-scope`, …) and a plain data
+ * schema is where it does not. Completion reads the `x-telo-fragment` stamp to
+ * decide which vocabulary to offer, exactly as a retry-budget consumer reads
+ * which of `RetryPolicy` / `RetryAttempts` a slot pointed at.
+ *
+ * The annotations are NOT properties here — see `schema-keywords.ts` for why a
+ * literal `x-telo-*` key inside a hoisted `properties` map would read to the
+ * annotation walkers as a slot the author never wrote.
+ */
+export const KindSchemaSchema = {
+    title: "Kind schema",
+    description: "The configuration a resource of this kind accepts, as JSON Schema plus the `x-telo-*` annotations that say how each field behaves.",
+    type: ["object", "boolean"],
+    properties: jsonSchemaKeywords(hoistedDefKey("KindSchema")),
+    additionalProperties: true,
+};
+/** 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. */
+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
+ *  `schema`. The one accessor every consumer asks, so no surface re-spells the
+ *  set. */
+export function isSchemaFragment(name) {
+    return name !== undefined && SCHEMA_FRAGMENTS.has(name);
+}
+/**
+ * The `$defs` key a hoisted fragment is written under, and the one its own
+ * self-reference points at.
+ *
+ * NAMESPACED so a collision is unrepresentable rather than diagnosable: `$defs`
+ * is the author's namespace, and a kind declaring its own `$defs: { KindSchema:
+ * … }` beside a slot pointing at the fragment would otherwise have its shape
+ * silently validate every such slot — a wrong-but-plausible validation, which is
+ * worse than a loud failure and impossible to see. With a reserved key the two
+ * coexist, and "already present" can only mean a previous hoist of the same
+ * fragment, which is what makes {@link hoistFragmentDef}'s skip provably safe.
+ */
+function hoistedDefKey(name) {
+    return `telo:${name}`;
+}
 /** Recursively freeze, so the fragment set cannot be edited through any of the
  *  references handed out. `fragmentFor` clones precisely because downstream
  *  passes rewrite schemas in place — `resolveSchemaRefKinds` rewrites the very
@@ -260,6 +344,8 @@ export const ManifestRootSchema = {
         RetryPolicy: RetryPolicySchema,
         RetryAttempts: RetryAttemptsSchema,
         InvokeStep: InvokeStepSchema,
+        JsonSchema7: JsonSchema7Schema,
+        KindSchema: KindSchemaSchema,
     },
 };
 deepFreeze(ManifestRootSchema);
@@ -272,6 +358,14 @@ export function manifestFragment(name) {
     if (!fragment || typeof fragment !== "object") {
         throw new Error(`Unknown manifest fragment '${name}'`);
     }
+    if (SCHEMA_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.
+        throw new Error(`Manifest fragment '${name}' is recursive and cannot be embedded — ` +
+            `point a slot at it with $ref: "${manifestFragmentRef(name)}" and pass the ` +
+            `enclosing schema through withSchemaFragments().`);
+    }
     const copy = structuredClone(fragment);
     expandManifestFragments(copy);
     copy[X_TELO_FRAGMENT] = name;
@@ -298,6 +392,26 @@ const FRAGMENT_PREFIX = `${MANIFEST_SCHEMA_URI}#/$defs/`;
  * loaded manifest see the same expanded shape.
  */
 export function expandManifestFragments(node, seen = new Set()) {
+    if (!node || typeof node !== "object")
+        return;
+    walkFragments(node, seen, { hoistTarget: node, depth: 0 });
+}
+/**
+ * Descend one key. A TOP-LEVEL schema-valued key (`schema:`, `inputType:`,
+ * `status:`, …) opens a new hoist target, because that node is what a validator
+ * compiles: a `#/$defs/…` pointer written below it resolves against IT, not
+ * against the document. Depth-anchored for the reason migrations anchor `under`
+ * at top-level keys — a slot DESCRIBING a field named `schema` is not itself a
+ * schema region, and treating it as one would scatter `$defs` blocks into the
+ * middle of a kind's property map.
+ */
+function childContext(ctx, key, value) {
+    if (ctx.depth === 0 && SCHEMA_REGION_KEYS.includes(key) && isPlainObject(value)) {
+        return { hoistTarget: value, depth: 1 };
+    }
+    return { hoistTarget: ctx.hoistTarget, depth: ctx.depth + 1 };
+}
+function walkFragments(node, seen, ctx) {
     if (!node || typeof node !== "object")
         return;
     if (seen.has(node))
@@ -305,23 +419,111 @@ export function expandManifestFragments(node, seen = new Set()) {
     seen.add(node);
     if (Array.isArray(node)) {
         for (let i = 0; i < node.length; i++) {
-            const fragment = fragmentFor(node[i]);
-            if (fragment)
-                node[i] = fragment;
-            else
-                expandManifestFragments(node[i], seen);
+            const localized = localizeRecursiveFragment(node[i], ctx);
+            if (localized)
+                node[i] = localized;
+            else {
+                const fragment = fragmentFor(node[i]);
+                if (fragment)
+                    node[i] = fragment;
+                else
+                    walkFragments(node[i], seen, { ...ctx, depth: ctx.depth + 1 });
+            }
         }
         return;
     }
     const obj = node;
     for (const [key, value] of Object.entries(obj)) {
+        const localized = localizeRecursiveFragment(value, ctx);
+        if (localized) {
+            obj[key] = localized;
+            continue;
+        }
         const fragment = fragmentFor(value);
         if (fragment)
             obj[key] = fragment;
         else
-            expandManifestFragments(value, seen);
+            walkFragments(value, seen, childContext(ctx, key, value));
+    }
+}
+/**
+ * Rewrite a reference to a RECURSIVE fragment to the document-local pointer,
+ * hoisting one copy of the fragment into the enclosing schema's `$defs`.
+ *
+ * Localized rather than inlined because the shape contains itself: inlining
+ * cannot terminate, which is what the "closed, non-recursive set" caveat above
+ * says. Localized rather than left pointing at `telo://manifest` because two
+ * consumers cannot follow a foreign URI — the editor's resolver throws on any
+ * `$ref` that does not start with `#/`, and that throw takes the whole canvas
+ * down, exactly as gating fragment expansion once did.
+ *
+ * Siblings written beside the `$ref` are kept, but draft-07 makes `$ref`
+ * exclusive, so they reach the human surfaces (completion, hover, the editor)
+ * and not AJV. A slot adds a `title` / `description` that way; a slot narrowing
+ * the shape would be silently ignored and should declare its own schema.
+ */
+function localizeRecursiveFragment(value, ctx) {
+    if (!isPlainObject(value))
+        return undefined;
+    const ref = value.$ref;
+    if (typeof ref !== "string" || !ref.startsWith(FRAGMENT_PREFIX))
+        return undefined;
+    const name = ref.slice(FRAGMENT_PREFIX.length);
+    if (!SCHEMA_FRAGMENTS.has(name))
+        return undefined;
+    hoistFragmentDef(ctx.hoistTarget, name);
+    return { ...value, $ref: `#/$defs/${hoistedDefKey(name)}`, [X_TELO_FRAGMENT]: name };
+}
+/** Add `name` (and anything it references in turn) to `target.$defs`, cloned —
+ *  the fragment set is frozen, and later passes rewrite schemas in place. */
+function hoistFragmentDef(target, name) {
+    const defs = (target.$defs ??= {});
+    const pending = [name];
+    while (pending.length > 0) {
+        const next = pending.pop();
+        const key = hoistedDefKey(next);
+        if (defs[key])
+            continue;
+        const fragment = ManifestRootSchema.$defs[next];
+        if (!fragment || typeof fragment !== "object")
+            continue;
+        // Stamped on the hoisted body, not only on the slot that pointed at it: a
+        // schema nests, so the node a consumer resolves two levels down is the
+        // 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) {
+            if (nested !== next && referencesLocalDef(defs[key], nested))
+                pending.push(nested);
+        }
     }
 }
+/** Does a hoisted fragment point at another one? Cheap and structural: the set
+ *  is small and a missed edge would leave an unresolvable pointer, which AJV
+ *  reports loudly rather than silently skipping. */
+function referencesLocalDef(node, name) {
+    if (!node || typeof node !== "object")
+        return false;
+    if (Array.isArray(node))
+        return node.some((item) => referencesLocalDef(item, name));
+    const obj = node;
+    if (obj.$ref === `#/$defs/${hoistedDefKey(name)}`)
+        return true;
+    return Object.values(obj).some((value) => referencesLocalDef(value, name));
+}
+/**
+ * Expand fragments in a schema that never passes through the loader —
+ * `builtins.ts` is not a manifest, so its slots have to arrive already
+ * localized, with the hoisted `$defs` at the root of the schema AJV compiles.
+ *
+ * Returns the same object, expanded in place, for use as a declaration
+ * initializer.
+ */
+export function withSchemaFragments(schema) {
+    expandManifestFragments(schema);
+    return schema;
+}
 /**
  * The fragment a node references, expanded and merged with whatever the node
  * declared beside the `$ref`, or undefined when it references none.