@telorun/analyzer 0.58.0 → 0.60.0

package/dist/manifest-schemas.js

@@ -0,0 +1,396 @@
+/**
+ * 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 const MANIFEST_SCHEMA_URI = "telo://manifest";
+/** `$ref` to a fragment in this set, as a module schema writes it. */
+export function manifestFragmentRef(name) {
+    return `${MANIFEST_SCHEMA_URI}#/$defs/${name}`;
+}
+/** 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 const ResourceRefSchema = {
+    title: "Resource reference",
+    anyOf: [
+        {
+            type: "object",
+            required: ["__tagged", "engine", "source"],
+            properties: {
+                __tagged: { const: true },
+                engine: { const: "ref" },
+                source: { type: "string", minLength: 1 },
+            },
+            additionalProperties: false,
+        },
+        {
+            type: "object",
+            required: ["kind"],
+            properties: { kind: { type: "string" } },
+            additionalProperties: true,
+        },
+    ],
+};
+/**
+ * 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 const RetryPolicySchema = {
+    title: "Retry policy",
+    description: "Re-attempts a failed dispatch with exponential backoff. A domain failure is " +
+        "retried; a cancellation and a contract violation are not — the latter is a " +
+        "property of the manifest and would fail identically every time.",
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        attempts: {
+            title: "Attempts",
+            description: "Re-attempts after the first try. 0 disables retrying.",
+            type: "integer",
+            minimum: 0,
+            default: 0,
+        },
+        initialDelay: {
+            title: "Initial delay",
+            description: "Milliseconds to wait before the first re-attempt.",
+            type: "integer",
+            minimum: 0,
+            default: 250,
+        },
+        factor: {
+            title: "Factor",
+            description: "Multiplier applied to the delay after each re-attempt.",
+            type: "number",
+            minimum: 1,
+            default: 2,
+        },
+        maxDelay: {
+            title: "Max delay",
+            description: "Ceiling on the delay between re-attempts, in milliseconds.",
+            type: "integer",
+            minimum: 0,
+            default: 32000,
+        },
+        jitter: {
+            title: "Jitter",
+            description: "`full` picks each delay uniformly from [0, delay], which is what stops " +
+                "work that failed together from re-attempting together.",
+            type: "string",
+            enum: ["none", "full"],
+            default: "full",
+        },
+        delay: {
+            title: "Delay",
+            description: "DEPRECATED duration string (`250ms`, `1s`) — read as `initialDelay` when " +
+                "that is absent. The pattern is what makes a typo a `telo check` failure " +
+                "instead of a silently different backoff.",
+            type: "string",
+            pattern: "^[0-9]+(\\.[0-9]+)?\\s*(ms|s|m|h)$",
+        },
+    },
+};
+/**
+ * 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 const RetryAttemptsSchema = {
+    title: "Retry attempts",
+    description: "Re-attempts after the first try. 0 disables retrying.",
+    type: "integer",
+    minimum: 0,
+    default: 0,
+};
+/**
+ * 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 const InvokeStepSchema = {
+    title: "Invoke step",
+    description: "Transfers control to a resource: what to call, what to pass it, whether to " +
+        "call it, and how to re-attempt it.",
+    type: "object",
+    required: ["invoke"],
+    additionalProperties: false,
+    properties: {
+        name: {
+            title: "Name",
+            description: "Publishes this dispatch's result as `steps.<name>.result`.",
+            type: "string",
+        },
+        invoke: {
+            title: "Invoke",
+            description: "Resource to invoke.",
+            "x-telo-topology-role": "invoke",
+            // A reference is always an object (a `!ref` sentinel or its resolved
+            // `{kind, name}`); requiring an object rejects a bare-string ref — which
+            // `validateReferenceForms` cannot catch at this nested slot — at
+            // `telo check` instead of as an obscure runtime failure.
+            type: "object",
+            "x-telo-ref": {
+                kind: "Telo.Executable",
+                use: "call",
+                inputs: "/inputs",
+            },
+        },
+        inputs: {
+            title: "Inputs",
+            description: "Values passed to the invoked resource.",
+            "x-telo-topology-role": "inputs",
+            type: "object",
+            additionalProperties: true,
+        },
+        when: {
+            title: "When",
+            description: "CEL guard — the dispatch is skipped when it evaluates false.",
+            type: "string",
+        },
+        retry: {
+            title: "Retry",
+            $ref: `${MANIFEST_SCHEMA_URI}#/$defs/RetryPolicy`,
+        },
+    },
+};
+/** 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
+ *  `x-telo-ref` node `InvokeStep` carries — and a consumer that embedded a
+ *  fragment WITHOUT cloning would corrupt every later expansion process-wide, in
+ *  a host that outlives one load (the editor, the LSP). Freezing turns that from
+ *  a rule someone has to remember into a throw at the write. */
+function deepFreeze(value) {
+    if (value && typeof value === "object" && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const child of Object.values(value))
+            deepFreeze(child);
+    }
+    return value;
+}
+/** Root schema registered with AJV under {@link MANIFEST_SCHEMA_URI}. Carries
+ *  `$defs` only — it isn't validated against directly. */
+export const ManifestRootSchema = {
+    $id: MANIFEST_SCHEMA_URI,
+    $defs: {
+        ResourceRef: ResourceRefSchema,
+        RetryPolicy: RetryPolicySchema,
+        RetryAttempts: RetryAttemptsSchema,
+        InvokeStep: InvokeStepSchema,
+    },
+};
+deepFreeze(ManifestRootSchema);
+/** 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 function manifestFragment(name) {
+    const fragment = ManifestRootSchema.$defs[name];
+    if (!fragment || typeof fragment !== "object") {
+        throw new Error(`Unknown manifest fragment '${name}'`);
+    }
+    const copy = structuredClone(fragment);
+    expandManifestFragments(copy);
+    copy[X_TELO_FRAGMENT] = name;
+    return copy;
+}
+const FRAGMENT_PREFIX = `${MANIFEST_SCHEMA_URI}#/$defs/`;
+/**
+ * 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 function expandManifestFragments(node, seen = new Set()) {
+    if (!node || typeof node !== "object")
+        return;
+    if (seen.has(node))
+        return;
+    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);
+        }
+        return;
+    }
+    const obj = node;
+    for (const [key, value] of Object.entries(obj)) {
+        const fragment = fragmentFor(value);
+        if (fragment)
+            obj[key] = fragment;
+        else
+            expandManifestFragments(value, seen);
+    }
+}
+/**
+ * The fragment a node references, expanded and merged with whatever the node
+ * declared beside the `$ref`, or undefined when it references none.
+ *
+ * SIBLINGS ARE MERGED, which draft-07 would ignore — `$ref` is exclusive there,
+ * so `{ $ref, properties: {...} }` silently drops the properties and `allOf` is
+ * the only standard alternative. `allOf` cannot preserve
+ * `additionalProperties: false`, because a branch only ever sees its own
+ * `properties`; a kind extending the shared retry policy with one HTTP-specific
+ * field would have had to give up a closed schema to do it. Merging at expansion
+ * gives the 2019-09 reading — `$ref` composes rather than replaces — on the
+ * draft the validators actually run.
+ *
+ * The node's own keys WIN, and `properties` merge key-wise, so an extension adds
+ * fields without restating the shared ones.
+ *
+ * The result is STAMPED with the fragment it came from. That stamp is what
+ * replaced `x-telo-retry`: a consumer asking "does this field declare a
+ * re-attempt, and where is the budget" reads which shape the author pointed at,
+ * rather than a marker the author had to remember to write beside it. Derived,
+ * never authored — the same standing as `metadata.exportedKinds` — and stripped
+ * before AJV like every other `x-telo-*` key, so it cannot affect validation.
+ *
+ * Deep-copied because downstream passes (`resolveSchemaRefKinds`, migrations)
+ * rewrite schemas in place, and a shared object would let one manifest's rewrite
+ * reach every other manifest that pointed at the same shape.
+ */
+function fragmentFor(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const node = value;
+    const ref = node.$ref;
+    if (typeof ref !== "string" || !ref.startsWith(FRAGMENT_PREFIX))
+        return undefined;
+    const name = ref.slice(FRAGMENT_PREFIX.length);
+    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);
+    for (const [key, own] of Object.entries(node)) {
+        if (key === "$ref")
+            continue;
+        if (key === "properties" && isPlainObject(own) && isPlainObject(expanded.properties)) {
+            expanded.properties = { ...expanded.properties, ...own };
+            continue;
+        }
+        if (key === "required" && Array.isArray(own) && Array.isArray(expanded.required)) {
+            expanded.required = [...new Set([...expanded.required, ...own])];
+            continue;
+        }
+        expanded[key] = own;
+    }
+    expanded[X_TELO_FRAGMENT] = name;
+    return expanded;
+}
+function isPlainObject(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+/** Stamped by {@link expandManifestFragments} with the name of the shared
+ *  fragment a slot pointed at. Derived, never author-written. */
+export 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 function manifestFragmentOf(schema) {
+    if (!schema || typeof schema !== "object")
+        return undefined;
+    const name = schema[X_TELO_FRAGMENT];
+    return typeof name === "string" ? name : undefined;
+}

package/dist/module-file-claims.d.ts

@@ -48,6 +48,12 @@ export type ModuleFileClaim = (ClaimBase & {
      *  `.gitignore`-style globs over the selected files, matched by the
      *  caller, which is the side that knows what was selected. */
     readonly siblings: readonly string[];
+    /** The source `path` was built from (`local_path=`), when the candidate
+     *  names one. The release path builds the entry point rather than reading
+     *  a prebuilt file, so it needs the source — and re-deriving it by parsing
+     *  `origin` would put PURL knowledge back into the consumer, which is
+     *  exactly what this module exists to hold. */
+    readonly localPath?: string;
 }) | (ClaimBase & {
     readonly role: "assets";
 });

package/dist/module-file-claims.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module-file-claims.d.ts","sourceRoot":"","sources":["../src/module-file-claims.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,wBAAwB,EAC9B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAuC,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAEpG;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,UAAU,SAAS;IACjB;;;uEAGmE;IACnE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;6CACyC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GACvB,CAAC,SAAS,GAAG;IACX,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC;;kEAE8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC,CAAC,GACF,CAAC,SAAS,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC,CAAC;AAiF9C;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,EACpB,QAAQ,GAAE,wBAA4C,GACrD,eAAe,EAAE,CAanB"}
+{"version":3,"file":"module-file-claims.d.ts","sourceRoot":"","sources":["../src/module-file-claims.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,wBAAwB,EAC9B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAuC,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAEpG;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,UAAU,SAAS;IACjB;;;uEAGmE;IACnE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;6CACyC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GACvB,CAAC,SAAS,GAAG;IACX,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC;;kEAE8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC;;;;mDAI+C;IAC/C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B,CAAC,GACF,CAAC,SAAS,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC,CAAC;AAqF9C;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,EACpB,QAAQ,GAAE,wBAA4C,GACrD,eAAe,EAAE,CAanB"}

package/dist/module-file-claims.js

@@ -40,6 +40,7 @@ function controllerClaims(json) {
         const entry = parsed.qualifiers?.path;
         if (typeof entry !== "string" || entry === "")
             continue;
+        const localPath = parsed.qualifiers?.local_path;
         claims.push({
             role: "controller",
             path: normalizeRelative(entry),
@@ -48,6 +49,9 @@ function controllerClaims(json) {
                 .split(",")
                 .map((p) => p.trim())
                 .filter((p) => p !== ""),
+            ...(typeof localPath === "string" && localPath !== ""
+                ? { localPath: normalizeRelative(localPath) }
+                : {}),
             origin: candidate,
         });
     }

package/dist/module-metadata-scope.d.ts

@@ -0,0 +1,44 @@
+/**
+ * What `module.<field>` may read: the metadata an AUTHOR wrote, never the
+ * loader's own stamps.
+ *
+ * A manifest reaching its own `metadata` is a small binding with one sharp edge.
+ * By the time analysis or the runtime sees a module doc, its `metadata` also
+ * carries fields nothing authored — `source` and `sourceLine` (the loader's
+ * provenance), `module`, `moduleGlobals`, `exportedKinds`, `reExportedKinds`,
+ * `forwardedExport` (derived indices the analyzer stamps). Exposing those would
+ * publish loader internals as a manifest surface, where they would be read,
+ * depended on, and then unchangeable.
+ *
+ * A DENYLIST rather than an allowlist, because the metadata vocabulary is
+ * deliberately open: a module may declare a field the standard library has never
+ * heard of, and an allowlist would silently hide it. The stamps, by contrast,
+ * are a closed set this repo controls — so the thing that can be enumerated is
+ * the thing enumerated.
+ */
+/** Fields written by the loader or the analyzer, not by the module's author. */
+export declare const DERIVED_METADATA_FIELDS: ReadonlySet<string>;
+/** The author-written half of a module doc's `metadata`. */
+export declare function authoredModuleMetadata(metadata: Record<string, unknown> | undefined | null): Record<string, unknown>;
+/**
+ * The `module` namespace as a JSON Schema, or `undefined` when there is nothing
+ * to type it from.
+ *
+ * **One derivation, two consumers.** `cel-environment.ts` needs CEL type strings
+ * and `kernel-globals.ts` needs JSON Schema, and they used to reach the same
+ * conclusion through two hand-written ternary chains that had to agree forever
+ * about which values are open and which are closed. The schema is the richer of
+ * the two shapes, so it is what is derived; the CEL side converts with
+ * `jsonSchemaToCelType`, which every other namespace already goes through.
+ *
+ * Typed from the VALUES because a module doc's metadata is literals, not a
+ * schema map — the module a resource belongs to is fixed, so there is nothing to
+ * resolve.
+ *
+ * `undefined` means **open**, and the distinction matters in the rejecting
+ * direction: a set with no module doc must leave `module.*` unconstrained rather
+ * than close it over whatever metadata happened to be at hand, or a valid
+ * `module.version` becomes a hard error nobody can act on.
+ */
+export declare function moduleMetadataSchema(metadata: Record<string, unknown> | undefined | null): Record<string, any> | undefined;
+//# sourceMappingURL=module-metadata-scope.d.ts.map

package/dist/module-metadata-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-metadata-scope.d.ts","sourceRoot":"","sources":["../src/module-metadata-scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,gFAAgF;AAChF,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,MAAM,CAQtD,CAAC;AAEH,4DAA4D;AAC5D,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,IAAI,GACnD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQzB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,IAAI,GACnD,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAsBjC"}

package/dist/module-metadata-scope.js

@@ -0,0 +1,82 @@
+/**
+ * What `module.<field>` may read: the metadata an AUTHOR wrote, never the
+ * loader's own stamps.
+ *
+ * A manifest reaching its own `metadata` is a small binding with one sharp edge.
+ * By the time analysis or the runtime sees a module doc, its `metadata` also
+ * carries fields nothing authored — `source` and `sourceLine` (the loader's
+ * provenance), `module`, `moduleGlobals`, `exportedKinds`, `reExportedKinds`,
+ * `forwardedExport` (derived indices the analyzer stamps). Exposing those would
+ * publish loader internals as a manifest surface, where they would be read,
+ * depended on, and then unchangeable.
+ *
+ * A DENYLIST rather than an allowlist, because the metadata vocabulary is
+ * deliberately open: a module may declare a field the standard library has never
+ * heard of, and an allowlist would silently hide it. The stamps, by contrast,
+ * are a closed set this repo controls — so the thing that can be enumerated is
+ * the thing enumerated.
+ */
+/** Fields written by the loader or the analyzer, not by the module's author. */
+export const DERIVED_METADATA_FIELDS = new Set([
+    "source",
+    "sourceLine",
+    "module",
+    "moduleGlobals",
+    "exportedKinds",
+    "reExportedKinds",
+    "forwardedExport",
+]);
+/** The author-written half of a module doc's `metadata`. */
+export function authoredModuleMetadata(metadata) {
+    if (!metadata || typeof metadata !== "object" || Array.isArray(metadata))
+        return {};
+    const authored = {};
+    for (const [key, value] of Object.entries(metadata)) {
+        if (DERIVED_METADATA_FIELDS.has(key))
+            continue;
+        authored[key] = value;
+    }
+    return authored;
+}
+/**
+ * The `module` namespace as a JSON Schema, or `undefined` when there is nothing
+ * to type it from.
+ *
+ * **One derivation, two consumers.** `cel-environment.ts` needs CEL type strings
+ * and `kernel-globals.ts` needs JSON Schema, and they used to reach the same
+ * conclusion through two hand-written ternary chains that had to agree forever
+ * about which values are open and which are closed. The schema is the richer of
+ * the two shapes, so it is what is derived; the CEL side converts with
+ * `jsonSchemaToCelType`, which every other namespace already goes through.
+ *
+ * Typed from the VALUES because a module doc's metadata is literals, not a
+ * schema map — the module a resource belongs to is fixed, so there is nothing to
+ * resolve.
+ *
+ * `undefined` means **open**, and the distinction matters in the rejecting
+ * direction: a set with no module doc must leave `module.*` unconstrained rather
+ * than close it over whatever metadata happened to be at hand, or a valid
+ * `module.version` becomes a hard error nobody can act on.
+ */
+export function moduleMetadataSchema(metadata) {
+    const authored = authoredModuleMetadata(metadata);
+    const keys = Object.keys(authored);
+    if (keys.length === 0)
+        return undefined;
+    const properties = {};
+    for (const key of keys) {
+        const value = authored[key];
+        properties[key] = Array.isArray(value)
+            ? { type: "array" }
+            : value !== null && typeof value === "object"
+                ? { type: "object", additionalProperties: true }
+                : {
+                    type: typeof value === "number"
+                        ? "number"
+                        : typeof value === "boolean"
+                            ? "boolean"
+                            : "string",
+                };
+    }
+    return { type: "object", properties, additionalProperties: false };
+}

package/dist/parse-loaded-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse-loaded-file.d.ts","sourceRoot":"","sources":["../src/parse-loaded-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAKxD,OAAO,KAAK,EAAE,UAAU,EAAc,MAAM,mBAAmB,CAAC;AAEhE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAK5D,MAAM,WAAW,YAAY;IAC3B;4EACwE;IACxE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;0DAGsD;IACtD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,uEAAuE;IACvE,UAAU,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;CACxC;AA4BD,oEAAoE;AACpE,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,YAAY,GACrB,UAAU,CA2DZ"}
+{"version":3,"file":"parse-loaded-file.d.ts","sourceRoot":"","sources":["../src/parse-loaded-file.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAKxD,OAAO,KAAK,EAAE,UAAU,EAAc,MAAM,mBAAmB,CAAC;AAEhE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAM5D,MAAM,WAAW,YAAY;IAC3B;4EACwE;IACxE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;0DAGsD;IACtD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,uEAAuE;IACvE,UAAU,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;CACxC;AA4BD,oEAAoE;AACpE,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,YAAY,GACrB,UAAU,CA0EZ"}

package/dist/parse-loaded-file.js

@@ -3,6 +3,7 @@ import { parseAllDocuments } from "yaml";
 import { buildCelEnvironment } from "./cel-environment.js";
 import { migrateManifests, NO_MIGRATIONS } from "./migrations/driver.js";
 import { buildDocumentPositions } from "./position-metadata.js";
+import { expandManifestFragments } from "./manifest-schemas.js";
 import { precompileDoc } from "./precompile.js";
 import { documentToAst } from "./yaml-ast.js";
 /** Append an actionable hint to raw yaml-parser messages that are otherwise
@@ -57,6 +58,21 @@ export function parseLoadedFile(source, requestedUrl, text, options) {
     const migrations = options?.migrate
         ? migrateManifests({ source, manifests, entries: options.migrations })
         : NO_MIGRATIONS;
+    // Shared structural fragments (`telo://manifest#/$defs/InvokeStep`) are
+    // expanded for EVERY consumer, deliberately ungated.
+    //
+    // They are not authoring sugar the way `imports:` or a `!ref` tag is — they are
+    // the analyzer's own closed set, and nothing downstream is equipped to meet one
+    // unresolved: the editor's schema resolver handles document-local `#/` refs
+    // only and THROWS on anything else, so a gated expansion took every canvas that
+    // renders a `Run` step down. Round-tripping is unaffected because a save writes
+    // the YAML documents the editor holds separately (`saveModuleFromDocuments`),
+    // never a manifest object — so unlike `migrate`, no expansion here can reach an
+    // author's file.
+    for (const manifest of manifests) {
+        if (manifest)
+            expandManifestFragments(manifest);
+    }
     let env;
     if (options?.compile) {
         for (let i = 0; i < manifests.length; i++) {

package/dist/release/bump-level.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The two vocabularies a release speaks, and the arithmetic between them.
+ *
+ * A **kind** is what an author writes in a fragment (`Added`, `Fixed`, …). It is
+ * changie's vocabulary, kept because it drives two things at once: the semantic
+ * level of the bump, and the heading the entry lands under in the changelog. A
+ * **level** is what the version arithmetic consumes.
+ *
+ * The mapping is the only place the two meet, and it is deliberately total: an
+ * unrecognized kind is refused rather than defaulted, because a typo that
+ * degraded to `patch` would silently under-release a breaking change.
+ */
+/** Semantic level of a version move. */
+export type BumpLevel = "major" | "minor" | "patch";
+export declare function maxLevel(a: BumpLevel, b: BumpLevel): BumpLevel;
+/**
+ * Fragment kinds, in changelog section order, each with the level it induces.
+ *
+ * `Changed` / `Removed` induce `major`, which the pre-1.0 guard then rejects —
+ * they are kept in the vocabulary rather than dropped so the rejection can name
+ * what was written and say why, instead of reporting an unknown kind.
+ */
+export declare const FRAGMENT_KINDS: {
+    readonly Added: "minor";
+    readonly Changed: "major";
+    readonly Deprecated: "minor";
+    readonly Removed: "major";
+    readonly Fixed: "patch";
+    readonly Security: "patch";
+};
+export type FragmentKind = keyof typeof FRAGMENT_KINDS;
+/** Declaration order, which is also the order sections appear in a changelog
+ *  release block. */
+export declare const FRAGMENT_KIND_ORDER: readonly FragmentKind[];
+export declare function isFragmentKind(value: unknown): value is FragmentKind;
+export declare function levelOfKind(kind: FragmentKind): BumpLevel;
+export declare function isReleaseVersion(value: unknown): value is string;
+/** Apply `level` to `version`. Throws on a version this system cannot represent,
+ *  rather than returning something plausible — every caller has already read the
+ *  value out of a manifest it is about to rewrite. */
+export declare function applyBump(version: string, level: BumpLevel): string;
+/** Numeric comparison, so `0.10.0` sorts after `0.9.0`. Returns a negative
+ *  number when `a` precedes `b`. An unparseable version sorts last rather than
+ *  throwing — this is used for display ordering, not for decisions. */
+export declare function compareVersions(a: string, b: string): number;
+//# sourceMappingURL=bump-level.d.ts.map

package/dist/release/bump-level.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bump-level.d.ts","sourceRoot":"","sources":["../../src/release/bump-level.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,wCAAwC;AACxC,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;AAOpD,wBAAgB,QAAQ,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,GAAG,SAAS,CAE9D;AAED;;;;;;GAMG;AACH,eAAO,MAAM,cAAc;;;;;;;CAOmB,CAAC;AAE/C,MAAM,MAAM,YAAY,GAAG,MAAM,OAAO,cAAc,CAAC;AAEvD;qBACqB;AACrB,eAAO,MAAM,mBAAmB,EAAE,SAAS,YAAY,EAEpC,CAAC;AAEpB,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAEpE;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,YAAY,GAAG,SAAS,CAEzD;AAOD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEhE;AAED;;sDAEsD;AACtD,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,CAWnE;AAED;;uEAEuE;AACvE,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAS5D"}