@telorun/sdk 0.60.0 → 0.62.0

package/dist/contract-errors.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The ambient kernel error union: codes any dispatch can raise because the
+ * kernel — not the kind's controller — enforces the invocation contract.
+ *
+ * They are **catchable**: a `catches:` entry may name one and its `when:` is
+ * validated against this set, so a typo is caught statically like any declared
+ * code. They are **excluded from coverage counting**: the completeness rule
+ * keeps counting only a kind's own `throws:` codes. Folding them into every
+ * union instead would make every bounded `catches:` block in the standard
+ * library incomplete overnight; making them uncatchable would leave an author no
+ * way to handle a contract violation they can legitimately recover from.
+ *
+ * Shared by the kernel (which raises them), the analyzer (which type-checks
+ * `catches:` against them) and module authors (who name them in a catch).
+ */
+/** Inputs did not satisfy the target's declared `inputType`. */
+export declare const ERR_INPUT_INVALID = "ERR_INPUT_INVALID";
+/** A result did not satisfy the target's declared `outputType`. */
+export declare const ERR_OUTPUT_INVALID = "ERR_OUTPUT_INVALID";
+/** A declared contract could not be resolved to a schema — a named type that
+ *  never registered. Distinct from a value violation: nothing is wrong with the
+ *  data, the contract itself is unusable, and enforcement must fail rather than
+ *  quietly switch itself off. */
+export declare const ERR_CONTRACT_UNRESOLVABLE = "ERR_CONTRACT_UNRESOLVABLE";
+export declare const AMBIENT_CONTRACT_ERROR_CODES: readonly ["ERR_INPUT_INVALID", "ERR_OUTPUT_INVALID", "ERR_CONTRACT_UNRESOLVABLE"];
+export type AmbientContractErrorCode = (typeof AMBIENT_CONTRACT_ERROR_CODES)[number];
+/** True when a code is raised by the kernel's contract enforcement rather than
+ *  declared by a kind. Callers use it to accept the code in a `catches:` entry
+ *  without counting it toward that kind's declared union. */
+export declare function isAmbientContractErrorCode(code: string): boolean;
+//# sourceMappingURL=contract-errors.d.ts.map

package/dist/contract-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-errors.d.ts","sourceRoot":"","sources":["../src/contract-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,gEAAgE;AAChE,eAAO,MAAM,iBAAiB,sBAAsB,CAAC;AAErD,mEAAmE;AACnE,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AAEvD;;;iCAGiC;AACjC,eAAO,MAAM,yBAAyB,8BAA8B,CAAC;AAErE,eAAO,MAAM,4BAA4B,mFAI/B,CAAC;AAEX,MAAM,MAAM,wBAAwB,GAAG,CAAC,OAAO,4BAA4B,CAAC,CAAC,MAAM,CAAC,CAAC;AAIrF;;6DAE6D;AAC7D,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhE"}

package/dist/contract-errors.js

@@ -0,0 +1,36 @@
+/**
+ * The ambient kernel error union: codes any dispatch can raise because the
+ * kernel — not the kind's controller — enforces the invocation contract.
+ *
+ * They are **catchable**: a `catches:` entry may name one and its `when:` is
+ * validated against this set, so a typo is caught statically like any declared
+ * code. They are **excluded from coverage counting**: the completeness rule
+ * keeps counting only a kind's own `throws:` codes. Folding them into every
+ * union instead would make every bounded `catches:` block in the standard
+ * library incomplete overnight; making them uncatchable would leave an author no
+ * way to handle a contract violation they can legitimately recover from.
+ *
+ * Shared by the kernel (which raises them), the analyzer (which type-checks
+ * `catches:` against them) and module authors (who name them in a catch).
+ */
+/** Inputs did not satisfy the target's declared `inputType`. */
+export const ERR_INPUT_INVALID = "ERR_INPUT_INVALID";
+/** A result did not satisfy the target's declared `outputType`. */
+export const ERR_OUTPUT_INVALID = "ERR_OUTPUT_INVALID";
+/** A declared contract could not be resolved to a schema — a named type that
+ *  never registered. Distinct from a value violation: nothing is wrong with the
+ *  data, the contract itself is unusable, and enforcement must fail rather than
+ *  quietly switch itself off. */
+export const ERR_CONTRACT_UNRESOLVABLE = "ERR_CONTRACT_UNRESOLVABLE";
+export const AMBIENT_CONTRACT_ERROR_CODES = [
+    ERR_INPUT_INVALID,
+    ERR_OUTPUT_INVALID,
+    ERR_CONTRACT_UNRESOLVABLE,
+];
+const AMBIENT = new Set(AMBIENT_CONTRACT_ERROR_CODES);
+/** True when a code is raised by the kernel's contract enforcement rather than
+ *  declared by a kind. Callers use it to accept the code in a `catches:` entry
+ *  without counting it toward that kind's declared union. */
+export function isAmbientContractErrorCode(code) {
+    return AMBIENT.has(code);
+}

package/dist/evaluation-context.d.ts

@@ -50,8 +50,14 @@ export type InstanceFactory = (context: EvaluationContext, resource: ResourceMan
  *                   registered in this context but not yet initialized. Injection uses it
  *                   to defer a resource whose dependency exists but hasn't inited yet —
  *                   rather than leaving the slot unresolved — so the init loop retries it.
+ * @param owner  The context that OWNS this resource — the module context for a top-level
+ *               resource, the per-run scope child for a `with:`-scoped one. Anything the
+ *               hook builds on the resource's behalf (notably a scope handle for an
+ *               `x-telo-scope` field) must hang off this, not off the root: the inline
+ *               declarations inside a scope name kinds through the import aliases of the
+ *               module that DECLARED them, which the root context has never heard of.
  */
-export type PreInitHook = (resource: ResourceManifest, getInstance: (name: string, alias?: string) => ResourceInstance | undefined, isPending?: (name: string) => boolean) => void;
+export type PreInitHook = (resource: ResourceManifest, getInstance: (name: string, alias?: string) => ResourceInstance | undefined, isPending: ((name: string) => boolean) | undefined, owner: EvaluationContext) => void;
 /** Canonical key for a resource instance: "<module>.<kind>.<name>" */
 export declare function resourceKey(r: ResourceManifest): string;
 /** The resource that owns a spawned child context — the parent in the resource

package/dist/evaluation-context.d.ts.map

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

package/dist/index.d.ts

@@ -18,6 +18,7 @@ export * from "./module-context.js";
 export * from "./resource-context.js";
 export * from "./resource-instance.js";
 export * from "./resource-manifest.js";
+export * from "./contract-errors.js";
 export * from "./invoke-error.js";
 export * from "./log-record.js";
 export * from "./log-sink.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,UAAU,CAAC;AACzB,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,UAAU,CAAC;AACzB,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -18,6 +18,7 @@ export * from "./module-context.js";
 export * from "./resource-context.js";
 export * from "./resource-instance.js";
 export * from "./resource-manifest.js";
+export * from "./contract-errors.js";
 export * from "./invoke-error.js";
 export * from "./log-record.js";
 export * from "./log-sink.js";

package/dist/runtime-error.d.ts

@@ -1,3 +1,30 @@
+/** The manifest site a statically-raised diagnostic was reported at, carried
+ *  through verbatim from the analyzer's `data` so a renderer resolves
+ *  `file:line:col` against the `LoadedGraph` exactly as `telo check` does —
+ *  never by re-parsing the rendered message. */
+export interface DiagnosticOrigin {
+    filePath?: string;
+    /** Field path within the manifest doc, as keyed by its position index. */
+    path?: string;
+    resource?: {
+        kind?: string;
+        name?: string;
+    };
+    /** The diagnostic's own position, for one that has no field path to look up:
+     *  a YAML parse failure knows where the syntax broke but has no parsed tree
+     *  to index. Structurally the analyzer's LSP `Range` (0-based), so a renderer
+     *  can hand it back to the shared range resolver unchanged. */
+    range?: {
+        start: {
+            line: number;
+            character: number;
+        };
+        end: {
+            line: number;
+            character: number;
+        };
+    };
+}
 export interface RuntimeDiagnostic {
     severity?: "error" | "warning";
     message: string;
@@ -5,7 +32,21 @@ export interface RuntimeDiagnostic {
     kind?: string;
     details?: string;
     code?: string;
+    /** Set when the failure came from static analysis rather than a running
+     *  resource; lets the renderer point at the offending line. */
+    origin?: DiagnosticOrigin;
+    /** Set when this entry failed ONLY because another resource in the same
+     *  failure set did — it carries no independent cause. Renderers collapse
+     *  these into one line rather than repeating one failure per dependent. */
+    derived?: boolean;
+    /** When `derived`, the ROOT of the dependency chain — the resource a reader
+     *  has to fix. Absent when the blocker could not be named. */
+    blockedBy?: string;
+    /** Diagnostics from a nested context (an import's own resource init), kept
+     *  structured instead of flattened into `message` so the classification and
+     *  the error count see the real leaves. */
+    children?: RuntimeDiagnostic[];
 }
 /** Well-known kernel error codes. User-defined codes (e.g. from Type.JsonSchema rules) are also valid. */
-export type RuntimeErrorCode = "ERR_RESOURCE_NOT_FOUND" | "ERR_RESOURCE_NOT_RUNNABLE" | "ERR_CONTROLLER_NOT_FOUND" | "ERR_CONTROLLER_INVALID" | "ERR_RESOURCE_INITIALIZATION_FAILED" | "ERR_RESOURCE_NOT_INVOKABLE" | "ERR_RESOURCE_SCHEMA_VALIDATION_FAILED" | "ERR_DUPLICATE_RESOURCE" | "ERR_EXECUTION_FAILED" | "ERR_INVALID_VALUE" | "ERR_VISIBILITY_DENIED" | "ERR_MANIFEST_VALIDATION_FAILED" | "ERR_CIRCULAR_DEPENDENCY" | "ERR_SCOPE_RESOURCE_NOT_FOUND" | "ERR_TYPE_NOT_FOUND" | "ERR_TYPE_VALIDATION_FAILED" | "ERR_KERNEL_STATE_INVALID" | (string & {});
+export type RuntimeErrorCode = "ERR_RESOURCE_NOT_FOUND" | "ERR_RESOURCE_NOT_RUNNABLE" | "ERR_CONTROLLER_NOT_FOUND" | "ERR_CONTROLLER_INVALID" | "ERR_RESOURCE_INITIALIZATION_FAILED" | "ERR_RESOURCE_NOT_INVOKABLE" | "ERR_RESOURCE_SCHEMA_VALIDATION_FAILED" | "ERR_DUPLICATE_RESOURCE" | "ERR_EXECUTION_FAILED" | "ERR_INVALID_VALUE" | "ERR_VISIBILITY_DENIED" | "ERR_MANIFEST_VALIDATION_FAILED" | "ERR_CIRCULAR_DEPENDENCY" | "ERR_SCOPE_RESOURCE_NOT_FOUND" | "ERR_TYPE_NOT_FOUND" | "ERR_TYPE_VALIDATION_FAILED" | "ERR_KERNEL_STATE_INVALID" | "ERR_LOCAL_REF_PENDING" | "ERR_CROSS_MODULE_REF_PENDING" | (string & {});
 //# sourceMappingURL=runtime-error.d.ts.map

package/dist/runtime-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-error.d.ts","sourceRoot":"","sources":["../src/runtime-error.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,0GAA0G;AAC1G,MAAM,MAAM,gBAAgB,GACxB,wBAAwB,GACxB,2BAA2B,GAC3B,0BAA0B,GAC1B,wBAAwB,GACxB,oCAAoC,GACpC,4BAA4B,GAC5B,uCAAuC,GACvC,wBAAwB,GACxB,sBAAsB,GACtB,mBAAmB,GACnB,uBAAuB,GACvB,gCAAgC,GAChC,yBAAyB,GACzB,8BAA8B,GAC9B,oBAAoB,GACpB,4BAA4B,GAC5B,0BAA0B,GAC1B,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC"}
+{"version":3,"file":"runtime-error.d.ts","sourceRoot":"","sources":["../src/runtime-error.ts"],"names":[],"mappings":"AAAA;;;gDAGgD;AAChD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C;;;mEAG+D;IAC/D,KAAK,CAAC,EAAE;QACN,KAAK,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,MAAM,CAAA;SAAE,CAAC;QAC3C,GAAG,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,MAAM,CAAA;SAAE,CAAC;KAC1C,CAAC;CACH;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;mEAC+D;IAC/D,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B;;+EAE2E;IAC3E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;kEAC8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;+CAE2C;IAC3C,QAAQ,CAAC,EAAE,iBAAiB,EAAE,CAAC;CAChC;AAED,0GAA0G;AAC1G,MAAM,MAAM,gBAAgB,GACxB,wBAAwB,GACxB,2BAA2B,GAC3B,0BAA0B,GAC1B,wBAAwB,GACxB,oCAAoC,GACpC,4BAA4B,GAC5B,uCAAuC,GACvC,wBAAwB,GACxB,sBAAsB,GACtB,mBAAmB,GACnB,uBAAuB,GACvB,gCAAgC,GAChC,yBAAyB,GACzB,8BAA8B,GAC9B,oBAAoB,GACpB,4BAA4B,GAC5B,0BAA0B,GAC1B,uBAAuB,GACvB,8BAA8B,GAC9B,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC"}

package/dist/type-schema-ref.d.ts

@@ -11,7 +11,22 @@
  * pinned version is ever loaded, so the canonical id stays version-free.
  */
 export declare const TELO_TYPE_SCHEME = "telo://";
-/** The canonical, alias-resolved `$id` a named type schema is registered under. */
+/**
+ * The canonical, alias-resolved id a named type schema is registered under.
+ *
+ * Authority-free (`telo:<module>/<type>`, not `telo://<module>/<type>`) because
+ * a JSON Schema validator has to RESOLVE it: AJV parses a `$ref` as a
+ * URI-reference against the document base, and a non-standard scheme carrying an
+ * authority resolves to nothing — a schema registered under `telo://M/T` cannot
+ * be referenced by `$ref: "telo://M/T"` no matter how it is registered, while the
+ * authority-free form resolves natively. Nothing enforced this before because no
+ * runtime path ever compiled a `$ref`-bearing contract; the invocation contract
+ * does, on every declaring kind.
+ *
+ * This is the INTERNAL id only. Authors keep writing the readable authority form
+ * (`telo://Self/<type>`, `telo://<Alias>/<type>`) — see {@link parseTeloTypeRef} —
+ * and the loader rewrites it to this. Published manifests are unaffected.
+ */
 export declare function canonicalTypeSchemaId(moduleName: string, typeName: string): string;
 /**
  * Resolve `extends` into a single self-contained object schema by deep-merging an

package/dist/type-schema-ref.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"type-schema-ref.d.ts","sourceRoot":"","sources":["../src/type-schema-ref.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,gBAAgB,YAAY,CAAC;AAE1C,mFAAmF;AACnF,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAElF;AAiBD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GACjC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAqCzB;AAED,0EAA0E;AAC1E,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CAKjE"}
+{"version":3,"file":"type-schema-ref.d.ts","sourceRoot":"","sources":["../src/type-schema-ref.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,gBAAgB,YAAY,CAAC;AAE1C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAElF;AAiBD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GACjC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAqCzB;AAED,0EAA0E;AAC1E,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CAKjE"}

package/dist/type-schema-ref.js

@@ -11,9 +11,24 @@
  * pinned version is ever loaded, so the canonical id stays version-free.
  */
 export const TELO_TYPE_SCHEME = "telo://";
-/** The canonical, alias-resolved `$id` a named type schema is registered under. */
+/**
+ * The canonical, alias-resolved id a named type schema is registered under.
+ *
+ * Authority-free (`telo:<module>/<type>`, not `telo://<module>/<type>`) because
+ * a JSON Schema validator has to RESOLVE it: AJV parses a `$ref` as a
+ * URI-reference against the document base, and a non-standard scheme carrying an
+ * authority resolves to nothing — a schema registered under `telo://M/T` cannot
+ * be referenced by `$ref: "telo://M/T"` no matter how it is registered, while the
+ * authority-free form resolves natively. Nothing enforced this before because no
+ * runtime path ever compiled a `$ref`-bearing contract; the invocation contract
+ * does, on every declaring kind.
+ *
+ * This is the INTERNAL id only. Authors keep writing the readable authority form
+ * (`telo://Self/<type>`, `telo://<Alias>/<type>`) — see {@link parseTeloTypeRef} —
+ * and the loader rewrites it to this. Published manifests are unaffected.
+ */
 export function canonicalTypeSchemaId(moduleName, typeName) {
-    return `${TELO_TYPE_SCHEME}${moduleName}/${typeName}`;
+    return `telo:${moduleName}/${typeName}`;
 }
 /** Top-level keywords merged structurally rather than copied wholesale when
  *  resolving `extends`: object shape (`properties` / `required` /

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/sdk",
-  "version": "0.60.0",
+  "version": "0.62.0",
   "description": "Telo SDK - Public API for Telo module authors.",
   "keywords": [
     "telo",

package/src/contract-errors.ts

@@ -0,0 +1,44 @@
+/**
+ * The ambient kernel error union: codes any dispatch can raise because the
+ * kernel — not the kind's controller — enforces the invocation contract.
+ *
+ * They are **catchable**: a `catches:` entry may name one and its `when:` is
+ * validated against this set, so a typo is caught statically like any declared
+ * code. They are **excluded from coverage counting**: the completeness rule
+ * keeps counting only a kind's own `throws:` codes. Folding them into every
+ * union instead would make every bounded `catches:` block in the standard
+ * library incomplete overnight; making them uncatchable would leave an author no
+ * way to handle a contract violation they can legitimately recover from.
+ *
+ * Shared by the kernel (which raises them), the analyzer (which type-checks
+ * `catches:` against them) and module authors (who name them in a catch).
+ */
+
+/** Inputs did not satisfy the target's declared `inputType`. */
+export const ERR_INPUT_INVALID = "ERR_INPUT_INVALID";
+
+/** A result did not satisfy the target's declared `outputType`. */
+export const ERR_OUTPUT_INVALID = "ERR_OUTPUT_INVALID";
+
+/** A declared contract could not be resolved to a schema — a named type that
+ *  never registered. Distinct from a value violation: nothing is wrong with the
+ *  data, the contract itself is unusable, and enforcement must fail rather than
+ *  quietly switch itself off. */
+export const ERR_CONTRACT_UNRESOLVABLE = "ERR_CONTRACT_UNRESOLVABLE";
+
+export const AMBIENT_CONTRACT_ERROR_CODES = [
+  ERR_INPUT_INVALID,
+  ERR_OUTPUT_INVALID,
+  ERR_CONTRACT_UNRESOLVABLE,
+] as const;
+
+export type AmbientContractErrorCode = (typeof AMBIENT_CONTRACT_ERROR_CODES)[number];
+
+const AMBIENT = new Set<string>(AMBIENT_CONTRACT_ERROR_CODES);
+
+/** True when a code is raised by the kernel's contract enforcement rather than
+ *  declared by a kind. Callers use it to accept the code in a `catches:` entry
+ *  without counting it toward that kind's declared union. */
+export function isAmbientContractErrorCode(code: string): boolean {
+  return AMBIENT.has(code);
+}

package/src/evaluation-context.ts

@@ -67,11 +67,18 @@ export type InstanceFactory = (
  *                   registered in this context but not yet initialized. Injection uses it
  *                   to defer a resource whose dependency exists but hasn't inited yet —
  *                   rather than leaving the slot unresolved — so the init loop retries it.
+ * @param owner  The context that OWNS this resource — the module context for a top-level
+ *               resource, the per-run scope child for a `with:`-scoped one. Anything the
+ *               hook builds on the resource's behalf (notably a scope handle for an
+ *               `x-telo-scope` field) must hang off this, not off the root: the inline
+ *               declarations inside a scope name kinds through the import aliases of the
+ *               module that DECLARED them, which the root context has never heard of.
  */
 export type PreInitHook = (
   resource: ResourceManifest,
   getInstance: (name: string, alias?: string) => ResourceInstance | undefined,
-  isPending?: (name: string) => boolean,
+  isPending: ((name: string) => boolean) | undefined,
+  owner: EvaluationContext,
 ) => void;
 
 /** Canonical key for a resource instance: "<module>.<kind>.<name>" */

package/src/index.ts

@@ -18,6 +18,7 @@ export * from "./module-context.js";
 export * from "./resource-context.js";
 export * from "./resource-instance.js";
 export * from "./resource-manifest.js";
+export * from "./contract-errors.js";
 export * from "./invoke-error.js";
 export * from "./log-record.js";
 export * from "./log-sink.js";

package/src/runtime-error.ts

@@ -1,3 +1,22 @@
+/** The manifest site a statically-raised diagnostic was reported at, carried
+ *  through verbatim from the analyzer's `data` so a renderer resolves
+ *  `file:line:col` against the `LoadedGraph` exactly as `telo check` does —
+ *  never by re-parsing the rendered message. */
+export interface DiagnosticOrigin {
+  filePath?: string;
+  /** Field path within the manifest doc, as keyed by its position index. */
+  path?: string;
+  resource?: { kind?: string; name?: string };
+  /** The diagnostic's own position, for one that has no field path to look up:
+   *  a YAML parse failure knows where the syntax broke but has no parsed tree
+   *  to index. Structurally the analyzer's LSP `Range` (0-based), so a renderer
+   *  can hand it back to the shared range resolver unchanged. */
+  range?: {
+    start: { line: number; character: number };
+    end: { line: number; character: number };
+  };
+}
+
 export interface RuntimeDiagnostic {
   severity?: "error" | "warning";
   message: string;
@@ -5,6 +24,20 @@ export interface RuntimeDiagnostic {
   kind?: string;
   details?: string;
   code?: string;
+  /** Set when the failure came from static analysis rather than a running
+   *  resource; lets the renderer point at the offending line. */
+  origin?: DiagnosticOrigin;
+  /** Set when this entry failed ONLY because another resource in the same
+   *  failure set did — it carries no independent cause. Renderers collapse
+   *  these into one line rather than repeating one failure per dependent. */
+  derived?: boolean;
+  /** When `derived`, the ROOT of the dependency chain — the resource a reader
+   *  has to fix. Absent when the blocker could not be named. */
+  blockedBy?: string;
+  /** Diagnostics from a nested context (an import's own resource init), kept
+   *  structured instead of flattened into `message` so the classification and
+   *  the error count see the real leaves. */
+  children?: RuntimeDiagnostic[];
 }
 
 /** Well-known kernel error codes. User-defined codes (e.g. from Type.JsonSchema rules) are also valid. */
@@ -26,4 +59,6 @@ export type RuntimeErrorCode =
   | "ERR_TYPE_NOT_FOUND"
   | "ERR_TYPE_VALIDATION_FAILED"
   | "ERR_KERNEL_STATE_INVALID"
+  | "ERR_LOCAL_REF_PENDING"
+  | "ERR_CROSS_MODULE_REF_PENDING"
   | (string & {});

package/src/type-schema-ref.ts

@@ -13,9 +13,24 @@
 
 export const TELO_TYPE_SCHEME = "telo://";
 
-/** The canonical, alias-resolved `$id` a named type schema is registered under. */
+/**
+ * The canonical, alias-resolved id a named type schema is registered under.
+ *
+ * Authority-free (`telo:<module>/<type>`, not `telo://<module>/<type>`) because
+ * a JSON Schema validator has to RESOLVE it: AJV parses a `$ref` as a
+ * URI-reference against the document base, and a non-standard scheme carrying an
+ * authority resolves to nothing — a schema registered under `telo://M/T` cannot
+ * be referenced by `$ref: "telo://M/T"` no matter how it is registered, while the
+ * authority-free form resolves natively. Nothing enforced this before because no
+ * runtime path ever compiled a `$ref`-bearing contract; the invocation contract
+ * does, on every declaring kind.
+ *
+ * This is the INTERNAL id only. Authors keep writing the readable authority form
+ * (`telo://Self/<type>`, `telo://<Alias>/<type>`) — see {@link parseTeloTypeRef} —
+ * and the loader rewrites it to this. Published manifests are unaffected.
+ */
 export function canonicalTypeSchemaId(moduleName: string, typeName: string): string {
-  return `${TELO_TYPE_SCHEME}${moduleName}/${typeName}`;
+  return `telo:${moduleName}/${typeName}`;
 }
 
 /** Top-level keywords merged structurally rather than copied wholesale when