@telorun/analyzer 0.43.0 → 0.44.0

package/dist/reconcile-module-versions.d.ts

@@ -13,8 +13,8 @@ export interface VersionReconciliation {
     diagnostics: AnalysisDiagnostic[];
 }
 /**
- * Reconcile a loaded import graph so each module identity (`namespace/name`)
- * resolves to a single version. Within a shared major the highest version wins
+ * Reconcile a loaded import graph so each module location (an import ref minus
+ * its version) resolves to a single version. Within a shared major the highest version wins
  * (a non-lossy hoist, given Telo's additive-only pre-1.0 policy); a major
  * mismatch is a hard conflict. Mutates `importEdges` in place — every edge that
  * pointed at a losing source is repointed at the winner — so `flattenForAnalyzer`

package/dist/reconcile-module-versions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reconcile-module-versions.d.ts","sourceRoot":"","sources":["../src/reconcile-module-versions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAElE,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIzE;;;;0CAI0C;AAC1C,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B;2EACuE;IACvE,WAAW,EAAE,kBAAkB,EAAE,CAAC;CACnC;AAwKD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,EAClC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,GAChD,qBAAqB,CAiDvB"}
+{"version":3,"file":"reconcile-module-versions.d.ts","sourceRoot":"","sources":["../src/reconcile-module-versions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAElE,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAIzE;;;;0CAI0C;AAC1C,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B;2EACuE;IACvE,WAAW,EAAE,kBAAkB,EAAE,CAAC;CACnC;AAuMD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,EAClC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,GAChD,qBAAqB,CAsEvB"}

package/dist/reconcile-module-versions.js

@@ -64,27 +64,56 @@ function compareVersions(a, b) {
     }
     return 0;
 }
-/** Read a loaded module's `namespace/name` identity, version, and raw owner
- *  text. Returns `null` for modules without a namespace: only a registry
- *  identity (`<namespace>/<name>`) is a stable cross-import key. Two namespace-
- *  less local libraries that merely share a `metadata.name` are distinct modules
- *  reached via distinct source URLs — reconciling them would drop one and break
- *  its kinds; the same local file reached via two paths is already collapsed by
- *  canonical-source dedup, so there is nothing left to reconcile here. */
-function moduleIdentityOf(mod) {
+/** The location identity of an import ref: the ref with its version stripped.
+ *  Two refs share an identity when they address the same module at different
+ *  versions, whatever transport owns them:
+ *
+ *    "std/kv-store@0.3.0"             → "std/kv-store"
+ *    "oci://ghcr.io/acme/s3@1.2.0"    → "oci://ghcr.io/acme/s3"
+ *    "https://x.com/lib/telo.yaml"    → itself (a URL carries no version)
+ *
+ *  Returns `null` for a relative path, which addresses one file on the
+ *  publisher's disk and is therefore not a cross-import key: two local libraries
+ *  that merely agree on `metadata.name` are distinct modules, and reconciling
+ *  them would drop one and break its kinds. The same local file reached via two
+ *  paths is already collapsed by canonical-source dedup.
+ *
+ *  **What this key cannot relate.** It compares ref *spellings*, so it groups by
+ *  origin exactly and nothing else. Two consequences, both accepted:
+ *
+ *  - A module imported once by a registry ref and once by a relative path is two
+ *    groups, so a version skew between them is not hoisted. Keying on what the
+ *    module declares about itself would catch that case, but only by trusting a
+ *    self-declared identity — which is what this change removes, and which
+ *    cannot tell two same-named modules from different origins apart.
+ *  - A bare `std/kv-store@0.4.0` and the equivalent direct
+ *    `https://<registry>/std/kv-store/0.4.0/telo.yaml` are two groups. Relating
+ *    them needs the configured registry base, which this pure, browser-safe
+ *    function does not have. */
+function refIdentity(ref) {
+    const base = ref.split("#")[0];
+    if (!base || base.startsWith(".") || base.startsWith("/") || base.startsWith("file:")) {
+        return null;
+    }
+    const lastSlash = base.lastIndexOf("/");
+    const at = base.lastIndexOf("@");
+    return at > lastSlash && at > 0 ? base.slice(0, at) : base;
+}
+/** Read a loaded module's version and raw owner text under the location
+ *  identity the import edge reached it by. The identity comes from the ref, not
+ *  from anything the module declares about itself — a module's own metadata
+ *  cannot distinguish two same-named modules published to different origins. */
+function moduleIdentityOf(mod, identity) {
     const doc = mod.owner.manifests.find((m) => m && isModuleKind(m.kind));
     if (!doc)
         return null;
     const meta = doc.metadata;
-    const name = meta?.name;
-    if (typeof name !== "string" || name.length === 0)
-        return null;
-    if (typeof meta.namespace !== "string" || meta.namespace.length === 0)
+    if (typeof meta?.name !== "string" || meta.name.length === 0)
         return null;
     const version = typeof meta.version === "string" ? meta.version : "";
     return {
         source: mod.owner.source,
-        identity: `${meta.namespace}/${name}`,
+        identity,
         version,
         parsed: parseVersion(version),
         text: mod.owner.text,
@@ -154,8 +183,8 @@ function hoistDiagnostic(identity, importerSource, alias, loser, winner, conflic
     return null;
 }
 /**
- * Reconcile a loaded import graph so each module identity (`namespace/name`)
- * resolves to a single version. Within a shared major the highest version wins
+ * Reconcile a loaded import graph so each module location (an import ref minus
+ * its version) resolves to a single version. Within a shared major the highest version wins
  * (a non-lossy hoist, given Telo's additive-only pre-1.0 policy); a major
  * mismatch is a hard conflict. Mutates `importEdges` in place — every edge that
  * pointed at a losing source is repointed at the winner — so `flattenForAnalyzer`
@@ -165,10 +194,33 @@ function hoistDiagnostic(identity, importerSource, alias, loser, winner, conflic
 export function reconcileModuleVersions(modules, importEdges) {
     const overrides = new Map();
     const diagnostics = [];
+    // Location identity per resolved module, taken from the ref that reached it.
+    // Two refs at different versions resolve to different canonical sources, so a
+    // source normally maps to exactly one identity; the entry module has no
+    // inbound edge and needs none (it is never reconciled against itself).
+    //
+    // One source CAN be reached by two spellings of the same location (a bare
+    // registry ref and the direct URL it resolves to). Both name the same module
+    // at the same version, so either identity groups it correctly — but the choice
+    // must not depend on edge iteration order, or the same graph could reconcile
+    // differently across runs. First edge wins.
+    const identityBySource = new Map();
+    for (const aliasMap of importEdges.values()) {
+        for (const edge of aliasMap.values()) {
+            if (identityBySource.has(edge.targetSource))
+                continue;
+            const identity = refIdentity(edge.targetRef);
+            if (identity)
+                identityBySource.set(edge.targetSource, identity);
+        }
+    }
     const groups = new Map();
     const infoBySource = new Map();
-    for (const mod of modules.values()) {
-        const info = moduleIdentityOf(mod);
+    for (const [source, mod] of modules) {
+        const identity = identityBySource.get(source);
+        if (!identity)
+            continue;
+        const info = moduleIdentityOf(mod, identity);
         if (!info)
             continue;
         infoBySource.set(info.source, info);

package/dist/reference-field-map.d.ts

@@ -1,6 +1,7 @@
 /** An entry for a field that carries one or more x-telo-ref constraints. */
 export interface RefFieldEntry {
-    /** One or more canonical ref strings ("namespace/module#TypeName" or "telo#TypeName").
+    /** One or more canonical kind keys ("<module>.<Kind>"), or the deprecated
+     *  identity form ("<namespace>/<module>#<Kind>") for a legacy published module.
      *  Multiple entries arise from anyOf branches. */
     refs: string[];
     /** True when the field path traversed through at least one array (path contains "[]"). */

package/dist/reference-field-map.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reference-field-map.d.ts","sourceRoot":"","sources":["../src/reference-field-map.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B;sDACkD;IAClD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,0FAA0F;IAC1F,OAAO,EAAE,OAAO,CAAC;IACjB;8DAC0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC9B;;;;;;;;;;kCAU8B;IAC9B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B;2CACuC;IACvC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CAC1B;AAED;8CAC8C;AAC9C,MAAM,WAAW,oBAAoB;IACnC;;qFAEiF;IACjF,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,aAAa,GAAG,aAAa,GAAG,eAAe,GAAG,oBAAoB,CAAC;AAEnF;0FAC0F;AAC1F,MAAM,MAAM,iBAAiB,GAAG,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAE3D,wBAAgB,UAAU,CAAC,KAAK,EAAE,aAAa,GAAG,KAAK,IAAI,aAAa,CAEvE;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,KAAK,IAAI,eAAe,CAE3E;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,GAAG,KAAK,IAAI,oBAAoB,CAErF;AAED,oGAAoG;AACpG,eAAO,MAAM,cAAc,aAAwC,CAAC;AAEpE;;;;;;;;;2EAS2E;AAC3E,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAItE;AAED;;;;sEAIsE;AACtE,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;wDAUwD;AACxD,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAoCpF;AAED;+DAC+D;AAC/D,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CAExE;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,iBAAiB,CAQrF;AASD,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,EAAE,CAa/D;AAED;;;8CAG8C;AAC9C,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,UAAU,EAAE,MAAM,GACjB,iBAAiB,CAInB"}
+{"version":3,"file":"reference-field-map.d.ts","sourceRoot":"","sources":["../src/reference-field-map.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B;;sDAEkD;IAClD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,0FAA0F;IAC1F,OAAO,EAAE,OAAO,CAAC;IACjB;8DAC0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC9B;;;;;;;;;;kCAU8B;IAC9B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B;2CACuC;IACvC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CAC1B;AAED;8CAC8C;AAC9C,MAAM,WAAW,oBAAoB;IACnC;;qFAEiF;IACjF,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,aAAa,GAAG,aAAa,GAAG,eAAe,GAAG,oBAAoB,CAAC;AAEnF;0FAC0F;AAC1F,MAAM,MAAM,iBAAiB,GAAG,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAE3D,wBAAgB,UAAU,CAAC,KAAK,EAAE,aAAa,GAAG,KAAK,IAAI,aAAa,CAEvE;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,KAAK,IAAI,eAAe,CAE3E;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,GAAG,KAAK,IAAI,oBAAoB,CAErF;AAED,oGAAoG;AACpG,eAAO,MAAM,cAAc,aAAwC,CAAC;AAEpE;;;;;;;;;2EAS2E;AAC3E,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAItE;AAED;;;;sEAIsE;AACtE,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;wDAUwD;AACxD,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAoCpF;AAED;+DAC+D;AAC/D,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CAExE;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,iBAAiB,CAQrF;AASD,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,EAAE,CAa/D;AAED;;;8CAG8C;AAC9C,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,UAAU,EAAE,MAAM,GACjB,iBAAiB,CAInB"}

package/dist/resolve-schema-ref-kinds.d.ts

@@ -0,0 +1,62 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import type { AliasResolver } from "./alias-resolver.js";
+/** Why an `x-telo-ref` constraint did not canonicalize.
+ *
+ *  - `legacy`  — the deprecated `<namespace>/<module>#<Kind>` identity form,
+ *                still resolved through the identity table.
+ *  - `unknown` — the prefix is not an alias in the declaring module's scope: a
+ *                typo, a missing `imports:` entry — or a value that was already
+ *                canonical, which the caller separates by asking the registry.
+ *  - `gated`   — the alias is known and the target owns the kind, but its
+ *                `exports.kinds` does not list it. */
+export type RefConstraintReason = "legacy" | "unknown" | "gated";
+/** An `x-telo-ref` constraint that did not canonicalize. */
+export interface RefConstraintIssue {
+    /** The constraint string exactly as authored. */
+    ref: string;
+    /** Dotted path to the annotated schema node within the doc, e.g.
+     *  `schema.properties.store`. Points the author at the slot, not just the doc. */
+    path: string;
+    /** The `Telo.Definition` / `Telo.Abstract` doc that declares the slot. */
+    manifest: ResourceManifest;
+    reason: RefConstraintReason;
+    /** For `gated`: the target module and the kinds it does export. */
+    gate?: {
+        module: string;
+        exported: string[];
+    };
+    /** Aliases the declaring scope does know — the "did you mean" material for
+     *  an `unknown` prefix. */
+    knownAliases?: string[];
+}
+/** True for the legacy identity form, which is split on `#` by the identity table. */
+export declare function isLegacyRefIdentity(ref: string): boolean;
+/**
+ * Rewrites the `x-telo-ref` constraints on one definition doc from the alias
+ * form (`KvStore.Store`, `Self.Store`, `Telo.Invocable`) to the canonical
+ * `<module>.<Kind>` key the definition registry is keyed by.
+ *
+ * `resolver` must be the scope of the module that DECLARES the definition, not
+ * the consumer's: an imported library names its dependencies by its own aliases.
+ * This mirrors how `extends:` and `capability:` are pre-resolved before
+ * registration, so the registry never needs module context to answer a ref query.
+ *
+ * Every constraint that does not canonicalize is returned, tagged with why. That
+ * matters more than it looks: an unresolved constraint leaves a string naming no
+ * registered kind, and the reference check treats an unknown target as partial
+ * context and skips it — so an unreported one would silently let the slot accept
+ * anything. The authored value is left in place either way, so a diagnostic
+ * quotes what the author actually wrote.
+ *
+ * An `unknown` result also covers an already-canonical value (`kv-store.Store`
+ * names a module, not an alias), which is what keeps the rewrite idempotent —
+ * the caller drops those by checking the definition registry once every kind is
+ * registered.
+ *
+ * The walk covers the whole doc rather than a fixed field list: a constraint can
+ * sit in `schema`, `inputType`, `outputType`, or a `$defs` entry nested in any of
+ * them, and rewriting one that appears in a template body's inline schema is
+ * correct too.
+ */
+export declare function resolveSchemaRefKinds(definition: ResourceManifest, resolver: Pick<AliasResolver, "resolveKindResult" | "knownAliases">): RefConstraintIssue[];
+//# sourceMappingURL=resolve-schema-ref-kinds.d.ts.map

package/dist/resolve-schema-ref-kinds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-schema-ref-kinds.d.ts","sourceRoot":"","sources":["../src/resolve-schema-ref-kinds.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAIzD;;;;;;;;sDAQsD;AACtD,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;AAEjE,4DAA4D;AAC5D,MAAM,WAAW,kBAAkB;IACjC,iDAAiD;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ;sFACkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,MAAM,EAAE,mBAAmB,CAAC;IAC5B,mEAAmE;IACnE,IAAI,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAC9C;+BAC2B;IAC3B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,sFAAsF;AACtF,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,gBAAgB,EAC5B,QAAQ,EAAE,IAAI,CAAC,aAAa,EAAE,mBAAmB,GAAG,cAAc,CAAC,GAClE,kBAAkB,EAAE,CAiDtB"}

package/dist/resolve-schema-ref-kinds.js

@@ -0,0 +1,81 @@
+const REF_ANNOTATION = "x-telo-ref";
+/** True for the legacy identity form, which is split on `#` by the identity table. */
+export function isLegacyRefIdentity(ref) {
+    return ref.includes("#");
+}
+/**
+ * Rewrites the `x-telo-ref` constraints on one definition doc from the alias
+ * form (`KvStore.Store`, `Self.Store`, `Telo.Invocable`) to the canonical
+ * `<module>.<Kind>` key the definition registry is keyed by.
+ *
+ * `resolver` must be the scope of the module that DECLARES the definition, not
+ * the consumer's: an imported library names its dependencies by its own aliases.
+ * This mirrors how `extends:` and `capability:` are pre-resolved before
+ * registration, so the registry never needs module context to answer a ref query.
+ *
+ * Every constraint that does not canonicalize is returned, tagged with why. That
+ * matters more than it looks: an unresolved constraint leaves a string naming no
+ * registered kind, and the reference check treats an unknown target as partial
+ * context and skips it — so an unreported one would silently let the slot accept
+ * anything. The authored value is left in place either way, so a diagnostic
+ * quotes what the author actually wrote.
+ *
+ * An `unknown` result also covers an already-canonical value (`kv-store.Store`
+ * names a module, not an alias), which is what keeps the rewrite idempotent —
+ * the caller drops those by checking the definition registry once every kind is
+ * registered.
+ *
+ * The walk covers the whole doc rather than a fixed field list: a constraint can
+ * sit in `schema`, `inputType`, `outputType`, or a `$defs` entry nested in any of
+ * them, and rewriting one that appears in a template body's inline schema is
+ * correct too.
+ */
+export function resolveSchemaRefKinds(definition, resolver) {
+    const issues = [];
+    const record = (ref, path) => {
+        if (isLegacyRefIdentity(ref)) {
+            issues.push({ ref, path, manifest: definition, reason: "legacy" });
+            return;
+        }
+        const result = resolver.resolveKindResult(ref);
+        if (result.status === "ok")
+            return;
+        issues.push(result.status === "gated"
+            ? {
+                ref,
+                path,
+                manifest: definition,
+                reason: "gated",
+                gate: { module: result.module, exported: result.exported },
+            }
+            : {
+                ref,
+                path,
+                manifest: definition,
+                reason: "unknown",
+                knownAliases: resolver.knownAliases(),
+            });
+    };
+    const walk = (value, path) => {
+        if (value === null || typeof value !== "object")
+            return;
+        if (Array.isArray(value)) {
+            value.forEach((item, i) => walk(item, `${path}[${i}]`));
+            return;
+        }
+        const obj = value;
+        const ref = obj[REF_ANNOTATION];
+        if (typeof ref === "string" && ref) {
+            const result = isLegacyRefIdentity(ref) ? null : resolver.resolveKindResult(ref);
+            if (result?.status === "ok")
+                obj[REF_ANNOTATION] = result.kind;
+            else
+                record(ref, path);
+        }
+        for (const key of Object.keys(obj)) {
+            walk(obj[key], path ? `${path}.${key}` : key);
+        }
+    };
+    walk(definition, "");
+    return issues;
+}

package/dist/sources/manifest-cache.d.ts

@@ -7,16 +7,26 @@ export declare const MANIFEST_CACHE_BASE_URL = "https://manifests.telo.sh";
  *  stores per version — `{ transport, host, path, version }` — so the tracker's
  *  write key and the editor's read key come from the same function and never
  *  drift. `path` is the slash-separated repo/module path (multi-segment OCI
- *  repos nest as prefixes). */
+ *  repos nest as prefixes), empty for a module addressed at a host's root. */
 export interface ManifestCacheCoords {
     transport: string;
     host: string;
     path: string;
-    version: string;
+    /** Omit only when the ref carries no version to key by — a direct `https://`
+     *  URL addresses exactly one file, so its path alone is already unambiguous.
+     *  Every ref whose grammar has a version segment must supply it, or two
+     *  versions of one module would collide on a single key. */
+    version?: string;
+    /** File within the version directory. Defaults to the module manifest, which
+     *  is the only file the hub's bucket stores; the local install cache also
+     *  holds each `include:` partial, which is named here. */
+    file?: string;
 }
 /** Deterministic cache key for one module version:
- *  `<transport>/<host>/<path…>/<version>/telo.yaml`. Returns `null` when any
- *  coordinate is empty or would traverse out of the key space. */
+ *  `<transport>/<host>/<path…>/<version>/<file>`, where `version` is omitted
+ *  when the coordinates carry none and `file` defaults to the module manifest.
+ *  Returns `null` when any coordinate is empty or would traverse out of the key
+ *  space. */
 export declare function manifestCacheKey(coords: ManifestCacheCoords): string | null;
 /** Cache coordinates for an `oci://host/repo@tag` ref. Returns `null` when the
  *  ref carries no explicit tag (a defaulted `latest` or a `sha256:` digest is

package/dist/sources/manifest-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest-cache.d.ts","sourceRoot":"","sources":["../../src/sources/manifest-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAKlD;;iFAEiF;AACjF,eAAO,MAAM,uBAAuB,8BAA8B,CAAC;AAEnE;;;;+BAI+B;AAC/B,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAOD;;kEAEkE;AAClE,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,GAAG,IAAI,CAO3E;AAED;;;6EAG6E;AAC7E,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAY9E;AAID;;2DAE2D;AAC3D,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;;;;;;;;oEASoE;AACpE,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAuB/F;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,GAAG,mBAAmB,EACzC,OAAO,GAAE,MAAgC,GACxC,MAAM,GAAG,IAAI,CAKf;AAED;;;;;+DAK+D;AAC/D,qBAAa,mBAAoB,YAAW,cAAc;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,GAAE,MAAgC;IAEtE,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAQxB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAalE;;;iEAG6D;IAC7D,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;CAOxD"}
+{"version":3,"file":"manifest-cache.d.ts","sourceRoot":"","sources":["../../src/sources/manifest-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAKlD;;iFAEiF;AACjF,eAAO,MAAM,uBAAuB,8BAA8B,CAAC;AAEnE;;;;8EAI8E;AAC9E,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb;;;gEAG4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;8DAE0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAOD;;;;aAIa;AACb,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,GAAG,IAAI,CAe3E;AAED;;;6EAG6E;AAC7E,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAY9E;AAID;;2DAE2D;AAC3D,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;;;;;;;;oEASoE;AACpE,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAuB/F;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,GAAG,mBAAmB,EACzC,OAAO,GAAE,MAAgC,GACxC,MAAM,GAAG,IAAI,CAKf;AAED;;;;;+DAK+D;AAC/D,qBAAa,mBAAoB,YAAW,cAAc;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,GAAE,MAAgC;IAEtE,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAQxB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAalE;;;iEAG6D;IAC7D,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;CAOxD"}

package/dist/sources/manifest-cache.js

@@ -10,15 +10,24 @@ function invalidSegment(segment) {
     return segment === "" || segment === "." || segment === ".." || segment.includes("\\");
 }
 /** Deterministic cache key for one module version:
- *  `<transport>/<host>/<path…>/<version>/telo.yaml`. Returns `null` when any
- *  coordinate is empty or would traverse out of the key space. */
+ *  `<transport>/<host>/<path…>/<version>/<file>`, where `version` is omitted
+ *  when the coordinates carry none and `file` defaults to the module manifest.
+ *  Returns `null` when any coordinate is empty or would traverse out of the key
+ *  space. */
 export function manifestCacheKey(coords) {
-    const { transport, host, path, version } = coords;
-    const segments = [transport, host, ...path.split("/"), version];
-    if (segments.some(invalidSegment) || transport.includes("/") || host.includes("/") || version.includes("/")) {
+    const { transport, host, path, version, file } = coords;
+    const segments = [transport, host, ...(path ? path.split("/") : [])];
+    if (version !== undefined)
+        segments.push(version);
+    segments.push(file ?? DEFAULT_MANIFEST_FILENAME);
+    if (segments.some(invalidSegment) ||
+        transport.includes("/") ||
+        host.includes("/") ||
+        (version !== undefined && version.includes("/")) ||
+        (file !== undefined && file.includes("/"))) {
         return null;
     }
-    return `${segments.join("/")}/${DEFAULT_MANIFEST_FILENAME}`;
+    return segments.join("/");
 }
 /** Cache coordinates for an `oci://host/repo@tag` ref. Returns `null` when the
  *  ref carries no explicit tag (a defaulted `latest` or a `sha256:` digest is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.43.0",
+  "version": "0.44.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",
@@ -48,7 +48,7 @@
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.54.0"
+    "@telorun/sdk": "0.56.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/analysis-registry.ts

@@ -17,7 +17,7 @@ export interface RefFieldInfo {
   path: string;
   /** True when the path traverses at least one array. */
   isArray: boolean;
-  /** Accepted `x-telo-ref` constraint strings (e.g. `telo#Runnable`). */
+  /** Accepted `x-telo-ref` constraint strings, canonicalized (e.g. `Telo.Runnable`). */
   refs: string[];
   /** Distinct capabilities the slot may target (`Telo.Runnable`,
    *  `Telo.Service`, `Telo.Provider`, …) — one per resolvable constraint. The
@@ -119,9 +119,9 @@ export class AnalysisRegistry {
 
   /** Base capability an `x-telo-ref` constraint targets. A definition's declared
    *  `capability` is always one of the base capabilities, so it wins — this
-   *  resolves user-defined abstracts (e.g. `std/ai#Model`, declared
+   *  resolves user-defined abstracts (e.g. `ai.Model`, declared
    *  `capability: Telo.Invocable`) to the capability instances satisfy, not the
-   *  abstract kind. Builtin abstracts (`telo#Runnable`) carry no `capability`
+   *  abstract kind. Builtin abstracts (`Telo.Runnable`) carry no `capability`
    *  field — there the kind itself *is* the capability. Undefined when
    *  unresolvable. */
   capabilityForRef(xTeloRef: string): string | undefined {
@@ -306,7 +306,7 @@ export class AnalysisRegistry {
   }
 
   /** Returns every user-facing (alias-form) kind that satisfies the given
-   *  `x-telo-ref` constraint string (e.g. `"telo#Invocable"`, `"std/sql#Connection"`).
+   *  `x-telo-ref` constraint string, canonicalized (e.g. `"Telo.Invocable"`, `"sql.Connection"`).
    *  Resolution mirrors `validateReferences.checkKind`: abstract targets expand to
    *  the set of definitions extending them; concrete targets yield just themselves.
    *  Returns `undefined` when the ref can't be resolved (e.g. unregistered identity),

package/src/analyzer.ts

@@ -20,6 +20,7 @@ import { isModuleKind } from "./module-kinds.js";
 import { normalizeInlineResources } from "./normalize-inline-resources.js";
 import { REF_VALIDATION_SKIP_KINDS } from "./system-kinds.js";
 import { resolveRefSentinels } from "./resolve-ref-sentinels.js";
+import { resolveSchemaRefKinds, type RefConstraintIssue } from "./resolve-schema-ref-kinds.js";
 import { resolveSchemaTypeRefs } from "./resolve-schema-type-refs.js";
 import { validateSchemaTypeRefs } from "./validate-schema-type-refs.js";
 import { rewriteSyntheticOrigins } from "./rewrite-synthetic-origins.js";
@@ -1035,6 +1036,7 @@ export class StaticAnalyzer {
     // declaring scope's resolver, so `extendedBy` is keyed by canonical kind regardless
     // of alias choices. `capability` covers the legacy implements-this-abstract overload;
     // `extends` is the canonical first-class form.
+    const refConstraintIssues: RefConstraintIssue[] = [];
     for (const m of manifests) {
       if (m.kind !== "Telo.Definition" && m.kind !== "Telo.Abstract") continue;
       const def = m as unknown as ResourceDefinition;
@@ -1043,6 +1045,15 @@ export class StaticAnalyzer {
         ownModule && !rootModules.has(ownModule)
           ? (aliasesByModule.get(ownModule) ?? new AliasResolver())
           : aliases;
+      // Canonicalize alias-form `x-telo-ref` constraints in the DECLARING module's
+      // scope, before the schema reaches `register()` and the lazily-built field
+      // maps. Same pre-resolution `capability` / `extends` get below.
+      const issues = resolveSchemaRefKinds(m, scopeResolver);
+      // Report only for definitions the author can edit. A published dependency
+      // still on the deprecated form — or with a constraint that no longer
+      // resolves — is not the consumer's to fix, and every import would
+      // otherwise flood `telo check` with unactionable noise.
+      if (!ownModule || rootModules.has(ownModule)) refConstraintIssues.push(...issues);
       const resolvedCapability = def.capability
         ? (scopeResolver.resolveKind(def.capability) ?? def.capability)
         : def.capability;
@@ -1063,6 +1074,57 @@ export class StaticAnalyzer {
     // distinguishable from the resolver's own substitution (after Phase 2/2.5
     // they are the same object).
     if (!options?.skipValidation) {
+      for (const issue of refConstraintIssues) {
+        // An `unknown` prefix is also what an ALREADY-CANONICAL value looks like
+        // (`kv-store.Store` names a module, not an alias). Now that every kind is
+        // registered, the registry separates the two — anything it resolves was
+        // canonical, anything it doesn't names nothing at all.
+        if (issue.reason === "unknown" && defs.resolve(issue.ref)) continue;
+        const resource = {
+          kind: issue.manifest.kind,
+          name: issue.manifest.metadata?.name as string,
+        };
+        const filePath = (issue.manifest.metadata as { source?: string } | undefined)?.source;
+        const data = { resource, filePath, path: issue.path };
+        if (issue.reason === "legacy") {
+          diagnostics.push({
+            severity: DiagnosticSeverity.Warning,
+            code: "X_TELO_REF_LEGACY_IDENTITY",
+            source: SOURCE,
+            message:
+              `x-telo-ref '${issue.ref}' at '${issue.path}' uses the deprecated ` +
+              `'<namespace>/<module>#<Kind>' form. Write the target as an alias-qualified kind ` +
+              `instead — '<Alias>.<Kind>' for a module declared in this file's 'imports:' map, ` +
+              `'Self.<Kind>' for a kind in this library, or 'Telo.<Kind>' for a built-in capability.`,
+            data,
+          });
+        } else if (issue.reason === "gated") {
+          diagnostics.push({
+            severity: DiagnosticSeverity.Error,
+            code: "KIND_NOT_EXPORTED",
+            source: SOURCE,
+            message:
+              `x-telo-ref '${issue.ref}' at '${issue.path}' targets a kind module ` +
+              `'${issue.gate?.module}' does not export. Add ` +
+              `'${issue.ref.slice(issue.ref.indexOf(".") + 1)}' to that module's exports.kinds. ` +
+              `Exported kinds: ${issue.gate?.exported.join(", ") || "(none)"}.`,
+            data,
+          });
+        } else {
+          diagnostics.push({
+            severity: DiagnosticSeverity.Error,
+            code: "X_TELO_REF_UNRESOLVED",
+            source: SOURCE,
+            message:
+              `x-telo-ref '${issue.ref}' at '${issue.path}' names no kind. The prefix must be an ` +
+              `import alias declared in this file's 'imports:' map, 'Self' for a kind in this ` +
+              `library, or 'Telo' for a built-in capability. An unresolvable constraint would ` +
+              `leave the slot accepting any resource. Known aliases: ` +
+              `${issue.knownAliases?.join(", ") || "(none)"}.`,
+            data,
+          });
+        }
+      }
       diagnostics.push(...validateReferenceForms(manifests, defs, aliases, aliasesByModule));
     }
 
@@ -1089,10 +1151,31 @@ export class StaticAnalyzer {
         rootModules.has(ownModule) ? aliases : (aliasesByModule.get(ownModule) ?? new AliasResolver());
       const canonicalKind = scopeResolver.resolveKind(m.kind as string) ?? (m.kind as string);
       if (defs.resolve(canonicalKind)?.capability !== "Telo.Type") continue;
-      defs.registerNamedTypeSchema(
-        canonicalTypeSchemaId(ownModule, m.metadata.name as string),
+      const typeName = m.metadata.name as string;
+      const registered = defs.registerNamedTypeSchema(
+        canonicalTypeSchemaId(ownModule, typeName),
         m.schema as Record<string, any>,
       );
+      // Kinds and named types share one `telo://<module>/<Name>` id space. A
+      // collision would leave every `$ref` to that id resolving to the kind's
+      // schema — validating the wrong shape, silently — so it is an error, not
+      // a last-writer-wins.
+      if (!registered && !options?.skipValidation) {
+        diagnostics.push({
+          severity: DiagnosticSeverity.Error,
+          code: "DUPLICATE_SCHEMA_ID",
+          source: SOURCE,
+          message:
+            `Type '${typeName}' collides with the kind '${ownModule}.${typeName}': both claim the ` +
+            `schema id '${canonicalTypeSchemaId(ownModule, typeName)}'. A '$ref' to it would ` +
+            `resolve to the kind's schema. Rename one of them.`,
+          data: {
+            resource: { kind: m.kind, name: typeName },
+            filePath: (m.metadata as { source?: string } | undefined)?.source,
+            path: "metadata.name",
+          },
+        });
+      }
     }
     if (!options?.skipValidation) {
       diagnostics.push(

package/src/builtins.ts

@@ -97,7 +97,7 @@ const ROOT_LOGGING_SCHEMA = {
       type: "array",
       items: {
         type: "object",
-        "x-telo-ref": "telo#LogSink",
+        "x-telo-ref": "Telo.LogSink",
         "x-telo-inline": true,
       },
     },
@@ -444,8 +444,8 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
           type: "array",
           items: {
             anyOf: [
-              { type: "string", "x-telo-ref": "telo#Runnable" },
-              { type: "string", "x-telo-ref": "telo#Service" },
+              { type: "string", "x-telo-ref": "Telo.Runnable" },
+              { type: "string", "x-telo-ref": "Telo.Service" },
               // Post-resolution shape that `resolveRefSentinels`
               // substitutes a `!ref <name>` sentinel into. The
               // adjacent `x-telo-ref` constraints govern the kind
@@ -469,8 +469,8 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
                 properties: {
                   ref: {
                     anyOf: [
-                      { type: "string", "x-telo-ref": "telo#Runnable" },
-                      { type: "string", "x-telo-ref": "telo#Service" },
+                      { type: "string", "x-telo-ref": "Telo.Runnable" },
+                      { type: "string", "x-telo-ref": "Telo.Service" },
                       {
                         type: "object",
                         required: ["kind", "name"],
@@ -510,8 +510,8 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
                     },
                     additionalProperties: true,
                     anyOf: [
-                      { "x-telo-ref": "telo#Invocable" },
-                      { "x-telo-ref": "telo#Runnable" },
+                      { "x-telo-ref": "Telo.Invocable" },
+                      { "x-telo-ref": "Telo.Runnable" },
                     ],
                   },
                   inputs: { type: "object", additionalProperties: true },