@telorun/sdk 0.72.0 → 0.74.0

package/dist/value-type.js

@@ -0,0 +1,317 @@
+/**
+ * `x-telo-type` — the one annotation that says what the value at a slot IS,
+ * beyond what JSON Schema's `type` vocabulary can express, and the single
+ * accessor every surface reads it through (the `ref-slot.ts` precedent).
+ *
+ * It replaced three keywords that answered one question differently: a nominal
+ * brand from a closed kernel table (`x-telo-type: TcpPort`), raw bytes
+ * (`x-telo-binary: true`), and a live handle (`x-telo-stream: true`). They
+ * differed in POSTURE toward the JSON Schema layer — refine, replace, exempt —
+ * not in kind, so each spelled as its own keyword meant a fourth cost eleven
+ * files across four packages, and left three defects: a typo'd brand degraded
+ * silently, bytes had no CEL identity, and a module string-matched the keyword
+ * because there was nothing on its surface to read.
+ *
+ * THE VOCABULARY IS DATA; THE BINDING TO A LANGUAGE IS NOT. Entries live at
+ * `sdk/value-types/*.json` (see the README there) and are copied in by the SDK's
+ * `prepare`. Every runtime that hosts Telo reads the same files — the Rust half
+ * types an `!include-bytes` slot from them in a kernel with no CEL engine — so
+ * an entry declares a symbolic `binding`, never a constructor name, and each
+ * runtime carries its own table mapping that key to its own identity.
+ *
+ * THE REGISTRY IS IN THE SDK because it is dependency-free and Node-built-in-free
+ * (so a browser-side analyzer can read it), because `Stream` already lives here,
+ * and because it is the only placement a module controller can reach: a module
+ * may import `@telorun/sdk` and nothing else.
+ */
+import { Stream } from "./stream.js";
+import { VALUE_TYPE_ENTRY_FILES } from "./value-types/entries/index.js";
+export const X_TELO_TYPE = "x-telo-type";
+/**
+ * Node's binding table — the ONLY per-language artifact in the whole mechanism.
+ *
+ * Keyed by an entry's symbolic `binding`, never by its name, so a runtime that
+ * represents two entries the same way says so once and a rename of a type does
+ * not touch any table.
+ */
+export const VALUE_TYPE_BINDINGS = {
+    bytes: { constructor: Uint8Array, celType: "bytes", placeholder: () => new Uint8Array() },
+    stream: { constructor: Stream, celType: "Stream" },
+};
+/** The CEL type a `json` representation's declared base carries. A brand's own
+ *  name is the CEL type; this is what it degrades to when the consuming slot
+ *  declares no brand of its own (gradual typing). */
+const CEL_TYPE_FOR_BASE = {
+    integer: "int",
+    number: "double",
+    string: "string",
+    boolean: "bool",
+    array: "list",
+    object: "map",
+};
+class ValueTypeEntryError extends Error {
+    constructor(file, detail) {
+        super(`Invalid value-type entry '${file}': ${detail}`);
+        this.name = "ValueTypeEntryError";
+    }
+}
+const ENTRY_KEYS = [
+    "name",
+    "representation",
+    "base",
+    "binding",
+    "live",
+    "parameters",
+    "description",
+    "$comment",
+];
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireString(file, node, key) {
+    const value = node[key];
+    if (typeof value !== "string" || value.length === 0) {
+        throw new ValueTypeEntryError(file, `'${key}' must be a non-empty string`);
+    }
+    return value;
+}
+function readParameters(file, raw) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw))
+        throw new ValueTypeEntryError(file, "'parameters' must be a sequence");
+    const params = raw.map((entry, i) => {
+        if (!isPlainObject(entry)) {
+            throw new ValueTypeEntryError(file, `parameters[${i}] must be a mapping`);
+        }
+        for (const key of Object.keys(entry)) {
+            if (key !== "name" && key !== "description" && key !== "element") {
+                throw new ValueTypeEntryError(file, `parameters[${i}] has no key '${key}'`);
+            }
+        }
+        if (entry.element !== undefined && typeof entry.element !== "boolean") {
+            throw new ValueTypeEntryError(file, `parameters[${i}].element must be a boolean when present`);
+        }
+        const name = requireString(file, entry, "name");
+        return {
+            name,
+            ...(entry.element === true ? { element: true } : {}),
+            ...(entry.description === undefined
+                ? {}
+                : { description: requireString(file, entry, "description") }),
+        };
+    });
+    // Two element parameters would make "the element of this value" ambiguous, and
+    // the reader is the only place that can refuse it — every consumer takes the
+    // first match and would silently pick one.
+    if (params.filter((p) => p.element).length > 1) {
+        throw new ValueTypeEntryError(file, "at most one parameter may declare 'element'");
+    }
+    return params;
+}
+/**
+ * Read one entry file's parsed data.
+ *
+ * Reading is STRICT and the vocabulary is closed at every level. A malformed or
+ * typo'd entry is an authoring mistake whose only other outcome is a type that
+ * quietly is not in the vocabulary — which reads to an author as "unknown name",
+ * pointing at their manifest instead of at the entry.
+ */
+export function parseValueTypeEntry(file, data) {
+    if (!isPlainObject(data))
+        throw new ValueTypeEntryError(file, "an entry must be a mapping");
+    for (const key of Object.keys(data)) {
+        if (!ENTRY_KEYS.includes(key)) {
+            throw new ValueTypeEntryError(file, `an entry has no key '${key}'. Known keys: ${ENTRY_KEYS.join(", ")}.`);
+        }
+    }
+    const name = requireString(file, data, "name");
+    if (!name.startsWith("Telo.")) {
+        throw new ValueTypeEntryError(file, `'name' must be Telo.-qualified — a representation is kernel-owned and cannot be module-defined`);
+    }
+    const representation = requireString(file, data, "representation");
+    if (representation !== "json" && representation !== "instance") {
+        throw new ValueTypeEntryError(file, `'representation' must be 'json' or 'instance'`);
+    }
+    if (data.live !== undefined && typeof data.live !== "boolean") {
+        throw new ValueTypeEntryError(file, "'live' must be a boolean when present");
+    }
+    // The two representations take disjoint parameters, and mixing them is a
+    // statement with no meaning: a `json` value has no constructor to assert, and
+    // an `instance` has no JSON base to refine.
+    if (representation === "json") {
+        if (data.binding !== undefined) {
+            throw new ValueTypeEntryError(file, "a 'json' representation takes no 'binding'");
+        }
+        const base = requireString(file, data, "base");
+        if (!(base in CEL_TYPE_FOR_BASE)) {
+            throw new ValueTypeEntryError(file, `'base' '${base}' is not a JSON Schema type (${Object.keys(CEL_TYPE_FOR_BASE).join(", ")})`);
+        }
+        if (data.live === true) {
+            throw new ValueTypeEntryError(file, "a 'json' representation cannot be 'live' — it is data");
+        }
+    }
+    else {
+        if (data.base !== undefined) {
+            throw new ValueTypeEntryError(file, "an 'instance' representation takes no 'base'");
+        }
+        requireString(file, data, "binding");
+    }
+    const entry = {
+        name,
+        representation,
+        ...(representation === "json" ? { base: data.base } : { binding: data.binding }),
+        live: data.live === true,
+        parameters: readParameters(file, data.parameters),
+        description: requireString(file, data, "description"),
+    };
+    return entry;
+}
+function buildRegistry() {
+    const registry = new Map();
+    for (const [file, data] of VALUE_TYPE_ENTRY_FILES) {
+        const entry = parseValueTypeEntry(file, data);
+        if (registry.has(entry.name)) {
+            throw new ValueTypeEntryError(file, `'${entry.name}' is already declared by another entry`);
+        }
+        // A binding with no row in THIS host's table is a hard error, never a
+        // skipped assertion: a type that cannot be asserted would silently exempt
+        // every slot declaring it, converting a contract into a hole. The same class
+        // of failure as an unrecognized `use` token degrading to the legacy reading.
+        if (entry.binding !== undefined && !(entry.binding in VALUE_TYPE_BINDINGS)) {
+            throw new ValueTypeEntryError(file, `binding '${entry.binding}' has no row in this runtime's table — a value type ` +
+                `whose assertion cannot be produced would silently exempt every slot that declares it`);
+        }
+        registry.set(entry.name, entry);
+    }
+    // Defence in depth against the packaging mistake, because the failure it
+    // produces is indistinguishable from an author's typo: every `x-telo-type`
+    // becomes an unknown name, reported against manifests that are correct. The
+    // build script refuses a missing source directory; this refuses the state that
+    // would reach a user if some other path ever produced it.
+    if (registry.size === 0) {
+        throw new Error("The value-type vocabulary is empty. `sdk/value-types/*.json` did not reach this " +
+            "build — check the file allowlist of whatever packaged it. Continuing would report " +
+            "every declared value type as an unknown name.");
+    }
+    return registry;
+}
+/** Every declared value type, keyed by its `Telo.`-qualified name. */
+export const VALUE_TYPES = buildRegistry();
+/** The declared names, in entry order — what `telo cel types` and the generated
+ *  docs section enumerate. */
+export function valueTypeNames() {
+    return [...VALUE_TYPES.keys()];
+}
+/**
+ * Read the annotation off a schema node.
+ *
+ * Two spellings, one meaning: a bare name (`x-telo-type: Telo.Bytes`) and the
+ * object form carrying arguments (`{ name: Telo.Stream, of: … }`). Returns
+ * undefined when the node carries no annotation at all — an unknown NAME still
+ * returns a slot, with `entry` undefined, because silently reading it as "no
+ * value type" is the degrade this annotation replaced.
+ */
+export function readValueTypeSlot(schema) {
+    if (!isPlainObject(schema))
+        return undefined;
+    const raw = schema[X_TELO_TYPE];
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw === "string") {
+        return { name: raw, entry: VALUE_TYPES.get(raw), args: {} };
+    }
+    if (isPlainObject(raw)) {
+        const name = typeof raw.name === "string" ? raw.name : "";
+        const args = {};
+        for (const [key, value] of Object.entries(raw)) {
+            if (key === "name")
+                continue;
+            // A bare NAME as an argument is sugar for a schema node carrying only that
+            // annotation, so `of: Telo.Bytes` and `of: { x-telo-type: Telo.Bytes }`
+            // are one thing. Normalized HERE, in the single reader, so no consumer
+            // re-derives it — a comparator that saw the string form would compare a
+            // string against a schema and quietly conclude nothing.
+            args[key] = typeof value === "string" ? { [X_TELO_TYPE]: value } : value;
+        }
+        return { name, entry: VALUE_TYPES.get(name), args };
+    }
+    return { name: "", entry: undefined, args: {} };
+}
+/** The entry a schema node declares, or undefined. The common read. */
+export function valueTypeOf(schema) {
+    return readValueTypeSlot(schema)?.entry;
+}
+/** True when this node declares a value type at all (known or not). */
+export function isValueTypeSlot(schema) {
+    return readValueTypeSlot(schema) !== undefined;
+}
+/** True when the node declares a `live` type, so its value is exempt from
+ *  validation — never traversed, never asserted. Typing is unaffected. */
+export function isLiveSlot(schema) {
+    return valueTypeOf(schema)?.live === true;
+}
+/** True when the node declares a type represented as a runtime instance —
+ *  the values no manifest literal can ever be. */
+export function isInstanceSlot(schema) {
+    return valueTypeOf(schema)?.representation === "instance";
+}
+/**
+ * The schema of what iterating a value at this slot yields, or undefined when
+ * the slot declares no value type, or one with no element parameter.
+ *
+ * The whole point of reading it from the entry is that no consumer names a type:
+ * a future iterable value type is covered by declaring `element` on its own
+ * parameter, with nothing to change here or in the analyzer. An element
+ * parameter left unsupplied means *any*, exactly as every other omitted argument
+ * does, so an unparameterized use degrades to permissive rather than to nothing.
+ */
+export function elementSchemaOf(schema) {
+    const slot = readValueTypeSlot(schema);
+    const parameter = slot?.entry?.parameters.find((p) => p.element);
+    if (!parameter)
+        return undefined;
+    return slot.args[parameter.name] ?? {};
+}
+/** The binding row for a schema node's declared type, or undefined when it
+ *  declares none / declares a `json` one. */
+export function bindingOf(schema) {
+    const binding = valueTypeOf(schema)?.binding;
+    return binding === undefined ? undefined : VALUE_TYPE_BINDINGS[binding];
+}
+/** The stand-in for a CEL leaf at this slot, or undefined when the slot declares
+ *  no instance type (ordinary JSON, so the schema's own shape decides) or a live
+ *  one (nothing validates it, so nothing has to satisfy anything). */
+export function valueTypePlaceholder(schema) {
+    return bindingOf(schema)?.placeholder?.();
+}
+/**
+ * The CEL type a value at this slot carries.
+ *
+ * A `json` representation carries its own NAME as a nominal brand — which is the
+ * whole point of one, since a `Telo.TcpPort` and a `Telo.UdpPort` are structurally
+ * identical. An `instance` carries whatever its binding says.
+ */
+export function celTypeOfValueType(entry) {
+    if (entry.representation === "json")
+        return entry.name;
+    const binding = VALUE_TYPE_BINDINGS[entry.binding];
+    return binding.celType;
+}
+/** The CEL type a brand degrades to where the consuming slot declares none —
+ *  gradual typing, so a `Telo.TcpPort` flows freely into a plain integer field.
+ *  Undefined for an `instance`, which has no base to fall back to. */
+export function celBaseOfValueType(entry) {
+    return entry.representation === "json" ? CEL_TYPE_FOR_BASE[entry.base] : undefined;
+}
+/** Every `json` representation's CEL brand → the base type it refines. The
+ *  gradual-typing table, derived rather than hand-written. */
+export function valueBrandBases() {
+    const out = {};
+    for (const entry of VALUE_TYPES.values()) {
+        const base = celBaseOfValueType(entry);
+        if (base !== undefined)
+            out[entry.name] = base;
+    }
+    return out;
+}

package/dist/value-types/entries/index.d.ts

@@ -0,0 +1,3 @@
+/** Every value-type entry file, in the order the registry reads them. */
+export declare const VALUE_TYPE_ENTRY_FILES: ReadonlyArray<readonly [file: string, data: unknown]>;
+//# sourceMappingURL=index.d.ts.map

package/dist/value-types/entries/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/value-types/entries/index.ts"],"names":[],"mappings":"AAOA,yEAAyE;AACzE,eAAO,MAAM,sBAAsB,EAAE,aAAa,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAKxF,CAAC"}

package/dist/value-types/entries/index.js

@@ -0,0 +1,13 @@
+// GENERATED by scripts/copy-value-type-entries.mjs — do not edit, and do not commit.
+// Source: sdk/value-types/*.json (lexically ordered).
+import e0 from "./telo-bytes.json" with { type: "json" };
+import e1 from "./telo-stream.json" with { type: "json" };
+import e2 from "./telo-tcp-port.json" with { type: "json" };
+import e3 from "./telo-udp-port.json" with { type: "json" };
+/** Every value-type entry file, in the order the registry reads them. */
+export const VALUE_TYPE_ENTRY_FILES = [
+    ["telo-bytes.json", e0],
+    ["telo-stream.json", e1],
+    ["telo-tcp-port.json", e2],
+    ["telo-udp-port.json", e3],
+];

package/dist/value-types/entries/telo-bytes.json

@@ -0,0 +1,7 @@
+{
+    "$comment": "Bytes are not expressible in JSON Schema's type vocabulary. `type: object` is satisfied by every object, so a mistyped literal reached the controller instead of failing check; `type: binary` is not an option, since a validator refuses to COMPILE an unknown type and a published telo.yaml would stop being JSON Schema for the hub, the editor and every third-party reader. Declaring the representation instead is what makes the check fall out: no YAML literal is ever a byte buffer, so a literal at a byte slot is rejected statically and a value arriving by reference passes.",
+    "name": "Telo.Bytes",
+    "representation": "instance",
+    "binding": "bytes",
+    "description": "Raw bytes. Never authorable inline — a byte slot is filled by reference (an `!include-bytes` embed, a resource output, a CEL expression), and the runtime asserts the value really is a byte buffer."
+}

package/dist/value-types/entries/telo-stream.json

@@ -0,0 +1,15 @@
+{
+    "$comment": "`live` is what separates a stream from bytes: consuming it has effects, so it is EXEMPT from validation rather than asserted — iterating a stream to check its elements is precisely what the exemption forbids. The exemption is from VALIDATION, never from TYPING: `of` still travels through every schema-typing walk, because that is where the argument check reads it.",
+    "name": "Telo.Stream",
+    "representation": "instance",
+    "binding": "stream",
+    "live": true,
+    "parameters": [
+        {
+            "name": "of",
+            "element": true,
+            "description": "The element the stream yields. Any schema node — an inline shape, a value type, a `!ref` to a named shape, or another parameterized type. Omitted means any element."
+        }
+    ],
+    "description": "A live handle over a sequence of values, consumed by reading. Its elements are never buffered or validated, and member access past it is rejected — a consumer iterates it instead."
+}

package/dist/value-types/entries/telo-tcp-port.json

@@ -0,0 +1,7 @@
+{
+    "$comment": "A `json` representation adds nominal identity to a value the declared schema already validates. A TcpPort and a UdpPort are both integers, so nothing structural tells them apart — the name is the whole difference, and it is what makes wiring one into the other's slot a static error.",
+    "name": "Telo.TcpPort",
+    "representation": "json",
+    "base": "integer",
+    "description": "A TCP port number. Distinct from a UDP port even though both are integers, so wiring one into the other's slot is a static error."
+}

package/dist/value-types/entries/telo-udp-port.json

@@ -0,0 +1,6 @@
+{
+    "name": "Telo.UdpPort",
+    "representation": "json",
+    "base": "integer",
+    "description": "A UDP port number. Distinct from a TCP port even though both are integers, so wiring one into the other's slot is a static error."
+}

package/package.json

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

package/src/bigint-json.ts

@@ -49,3 +49,30 @@ export function bigIntAt(holder: unknown, key: string): bigint | undefined {
   const source = (holder as Record<string, unknown> | null | undefined)?.[key];
   return typeof source === "bigint" ? source : undefined;
 }
+
+/**
+ * A declared-integer input read as a JS number, whichever representation the
+ * call site produced.
+ *
+ * A CEL integer is an int64 — a BigInt — and the kernel normalizes a declared
+ * `type: integer` OUTPUT to that form, so one resource's result reaching another
+ * resource's input arrives as a BigInt while a YAML literal at the same slot
+ * arrives as a plain number. A controller that reads such an input with
+ * `Number.isInteger(...)` or plain arithmetic therefore works for one call site
+ * and throws `Cannot mix BigInt and other types` for the other. Inputs are
+ * deliberately NOT normalized (that would change the authoring surface of every
+ * module rather than repair a false declaration), so this is how a controller
+ * reads one.
+ *
+ * Returns `undefined` for anything that is not an integer in either
+ * representation — including a BigInt too large for a double, since silently
+ * rounding it would be the precision loss int64 support exists to remove — so a
+ * caller's own "must be a non-negative integer" check still rejects what it
+ * should.
+ */
+export function integerInput(value: unknown): number | undefined {
+  if (typeof value === "number") return Number.isInteger(value) ? value : undefined;
+  if (typeof value !== "bigint") return undefined;
+  const asNumber = Number(value);
+  return Number.isSafeInteger(asNumber) ? asNumber : undefined;
+}

package/src/index.ts

@@ -34,4 +34,5 @@ export * from "./runtime-event.js";
 export * from "./runtime-resource.js";
 export * from "./stream.js";
 export * from "./types.js";
+export * from "./value-type.js";
 

package/src/resource-context.ts

@@ -27,6 +27,12 @@ export interface LoadOptions {
    *  inline imports resolve and execute identically to authored `Telo.Import`
    *  documents. Mirrors the analyzer loader's option of the same name. */
   desugarImports?: boolean;
+  /** When true, legacy manifest spellings are rewritten to the current ones
+   *  before the manifests are returned, so a module published years ago loads
+   *  against today's vocabulary. On for every runtime load; off only for a
+   *  round-trip view that must show the author's own text. Mirrors the analyzer
+   *  loader's option of the same name. */
+  migrate?: boolean;
 }
 
 export interface DataValidator {

package/src/type-schema-ref.ts

@@ -33,6 +33,22 @@ export function canonicalTypeSchemaId(moduleName: string, typeName: string): str
   return `telo:${moduleName}/${typeName}`;
 }
 
+/** The inverse of {@link canonicalTypeSchemaId}. Returns null for any other
+ *  string, including the authoring authority form and fragment-bearing built-ins.
+ *
+ *  A resolver reads a named shape through this rather than by bare name: the
+ *  canonical id carries the OWNING MODULE, so two libraries declaring a shape of
+ *  the same name stay distinct. Resolving by name alone was how an alias got
+ *  silently dropped. */
+export function parseCanonicalTypeSchemaId(
+  ref: unknown,
+): { moduleName: string; typeName: string } | null {
+  if (typeof ref !== "string") return null;
+  const match = /^telo:([^/#:]+)\/([^#/]+)$/.exec(ref);
+  if (!match) return null;
+  return { moduleName: match[1]!, typeName: match[2]! };
+}
+
 /** Top-level keywords merged structurally rather than copied wholesale when
  *  resolving `extends`: object shape (`properties` / `required` /
  *  `additionalProperties`) is deep-merged, and composition keywords (`allOf` /