@telorun/analyzer 0.60.0 → 0.62.0

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.

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

@@ -42,6 +42,13 @@ interface ClaimBase {
  * controller claim with no selector that nothing would reject.
  */
 export type ModuleFileClaim = (ClaimBase & {
+    readonly role: "library";
+    readonly selector: ArtifactSelector;
+    /** The bare specifier a consumer's bundle imports this entry point by. */
+    readonly specifier: string;
+    /** The source `path` was built from, as on a controller claim. */
+    readonly localPath?: string;
+}) | (ClaimBase & {
     readonly role: "controller";
     readonly selector: ArtifactSelector;
     /** Extra payload patterns that belong in the same layer as this claim —

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;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"}
+{"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;AAGpG;;;;;;;;;;;;;;;;;;;;;;;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,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,kEAAkE;IAClE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B,CAAC,GACF,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;AAsG9C;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,EACpB,QAAQ,GAAE,wBAA4C,GACrD,eAAe,EAAE,CAiBnB"}

package/dist/module-file-claims.js

@@ -2,6 +2,7 @@ import { defaultCustomTags, defaultRegistry, walkCelExpressions, } from "@teloru
 import { PackageURL } from "packageurl-js";
 import { parseAllDocuments } from "yaml";
 import { selectorFromQualifiers, selectorKey } from "./artifact-selector.js";
+import { readLibraryCandidates } from "./module-library.js";
 /** `pkg:telo/local/<format>?path=…` — the bundled-controller delivery mode.
  *  Anything else (`pkg:npm`, `pkg:cargo`) fetches from its own ecosystem and
  *  contributes no layer. */
@@ -57,6 +58,21 @@ function controllerClaims(json) {
     }
     return claims;
 }
+/** The library entry points one document's `library:` block names. Unlike a
+ *  controller entry — reached only when this module's own kinds instantiate —
+ *  this one is what a *sibling* resolves a bare specifier to, which is why it
+ *  gets its own layer rather than riding in the controller layer: a consumer
+ *  must reach it without loading this module's controllers. */
+function libraryClaims(json) {
+    return readLibraryCandidates(json).candidates.map((candidate) => ({
+        role: "library",
+        path: candidate.path,
+        selector: candidate.selector,
+        specifier: candidate.specifier,
+        ...(candidate.localPath ? { localPath: candidate.localPath } : {}),
+        origin: candidate.origin,
+    }));
+}
 /** Claims contributed by tagged values, asked of the engine that owns each tag.
  *  The walk reaches every tagged scalar in the document, so an engine that
  *  embeds files is discovered wherever its tag was written.
@@ -81,7 +97,7 @@ function taggedClaims(json, registry) {
  *  their layers — dropping one would leave a platform's layer short a file it
  *  declared it needs. */
 function claimKey(claim) {
-    const selector = claim.role === "controller" ? selectorKey(claim.selector) : "";
+    const selector = claim.role === "controller" || claim.role === "library" ? selectorKey(claim.selector) : "";
     return `${claim.role}\0${selector}\0${claim.path}`;
 }
 /**
@@ -98,7 +114,11 @@ export function collectModuleFileClaims(manifestText, registry = defaultRegistry
     const claims = [];
     for (const doc of parseAllDocuments(manifestText, { customTags: defaultCustomTags() })) {
         const json = doc.toJSON();
-        for (const claim of [...controllerClaims(json), ...taggedClaims(json, registry)]) {
+        for (const claim of [
+            ...libraryClaims(json),
+            ...controllerClaims(json),
+            ...taggedClaims(json, registry),
+        ]) {
             const key = claimKey(claim);
             if (seen.has(key))
                 continue;

package/dist/module-library.d.ts

@@ -0,0 +1,97 @@
+/**
+ * A module's **exported code** — the `exports.code:` block on a `Telo.Library`
+ * doc, which names the entry point a *sibling module's* controller bundle
+ * resolves this module's bare specifier to.
+ *
+ * ```yaml
+ * exports:
+ *   kinds:
+ *     - Store
+ *   code:
+ *     - specifier: "@telorun/kv-store"
+ *       format: js
+ *       path: ./nodejs/kv-store.mjs
+ *       source: ./nodejs/src/index.ts
+ * ```
+ *
+ * ## Why it sits under `exports:`
+ *
+ * A library already declares what crosses its boundary — the kinds importers may
+ * name, the resource instances they may `!ref`. This is the same statement about
+ * its *code*, and it gates the same way: a specifier nobody declares resolves to
+ * nothing. Putting it beside them keeps one block for "reachable from outside"
+ * rather than a second top-level key whose name (`library:` on a `Telo.Library`)
+ * meant a different thing from the kind one line above it.
+ *
+ * ## Why it is not a package URL
+ *
+ * `controllers:` names a PURL because it must be able to say `pkg:npm/…` or
+ * `pkg:cargo/…` — an ecosystem fetch. This entry never fetches: it names a file
+ * the module already ships, so `pkg:telo/local/` would be three constant segments
+ * before the first real datum. What is left after removing them is exactly these
+ * fields, and as data they are visually editable, where a query string is one
+ * opaque text box.
+ *
+ * The **model** is unchanged: `format` plus the optional platform axes build the
+ * same `ArtifactSelector` a controller candidate does, so layer matching, platform
+ * fallthrough and lazy materialization are inherited whole.
+ *
+ * ## Why the specifier is declared here
+ *
+ * A bundle imports the bare specifier `@telorun/sql`; the consumer's manifest
+ * declares the dependency as `Sql: ../sql`. Something has to connect the two, and
+ * it is the *library* that says so, once, rather than each of its consumers:
+ *
+ * - the specifier is a property of the library — its name in a host language's
+ *   ecosystem — not of the relationship, so N consumers cannot disagree about it
+ *   and adding a consumer restates nothing;
+ * - it sits beside the format, which keeps runtime **derived, never declared**:
+ *   the entry says `format: js`, and a Rust entry carries `specifier:
+ *   telorun-sql` with no runtime-keyed map anywhere.
+ *
+ * **One specifier, one entry point.** Subpaths are deliberately not
+ * representable: reproducing npm's `exports` map inside the artifact would pull a
+ * package manager's resolution semantics into Telo, which is what the "only
+ * workspace modules are de-inlined" rule refuses on `kysely`'s behalf.
+ *
+ * `Telo.Application` has no `exports:` block at all — an application is a root
+ * with no importer, so nothing could resolve a specifier to it.
+ *
+ * Browser-safe: string work only. Whether the named file EXISTS is a separate
+ * question, asked by the Node-side caller that has a directory.
+ */
+import { type ArtifactSelector } from "./artifact-selector.js";
+export interface LibraryCandidate {
+    /** The bare specifier a sibling's controller bundle imports this library by. */
+    readonly specifier: string;
+    /** Module-root-relative path of the built entry point. */
+    readonly path: string;
+    /** Module-root-relative TypeScript source it is built from (`source:`), when
+     *  the entry names one. Present only while the module is a working copy; a
+     *  published artifact ships no `src/`. */
+    readonly localPath?: string;
+    readonly selector: ArtifactSelector;
+    /** Where the entry was written, for diagnostics. */
+    readonly origin: string;
+}
+/** Why an `exports.code` entry could not be read. Returned rather than thrown so
+ *  the analyzer can report every entry of a block, and so a reader on the load
+ *  path can carry on with the entries that are well-formed. */
+export interface LibraryCandidateProblem {
+    readonly origin: string;
+    readonly detail: string;
+}
+export interface LibraryCandidates {
+    readonly candidates: LibraryCandidate[];
+    readonly problems: LibraryCandidateProblem[];
+}
+/**
+ * Read the `exports.code:` block off an owner document's JSON projection.
+ *
+ * Everything malformed is a problem rather than a silent skip: an entry that
+ * cannot be read names no entry point, so a consumer's bundle falls back to
+ * *inlining* the library — the duplicated module scope this whole mechanism
+ * exists to remove — and it does so on someone else's machine.
+ */
+export declare function readLibraryCandidates(ownerJson: unknown): LibraryCandidates;
+//# sourceMappingURL=module-library.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"module-library.d.ts","sourceRoot":"","sources":["../src/module-library.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAEH,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,wBAAwB,CAAC;AAKhC,MAAM,WAAW,gBAAgB;IAC/B,gFAAgF;IAChF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;8CAE0C;IAC1C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;+DAE+D;AAC/D,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,UAAU,EAAE,gBAAgB,EAAE,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,uBAAuB,EAAE,CAAC;CAC9C;AAmBD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,OAAO,GAAG,iBAAiB,CAkF3E"}