@telorun/kernel 0.4.1 → 0.6.0

package/src/runtime-registry.ts

@@ -0,0 +1,170 @@
+import type { ControllerPolicy } from "@telorun/sdk";
+import { RuntimeError } from "@telorun/sdk";
+
+export type { ControllerPolicy } from "@telorun/sdk";
+
+/**
+ * The PURL-type prefix the kernel itself runs (i.e. "no FFI" controllers
+ * for this kernel). For the Node.js kernel, that's `pkg:npm`. A future
+ * Rust kernel reports `pkg:cargo` here.
+ */
+export const KERNEL_NATIVE_PURL_TYPE = "pkg:npm";
+
+/**
+ * Wildcard sentinel inside a resolved `ControllerPolicy.load`. Means
+ * "all remaining controllers in declaration order, minus PURL types
+ * already listed earlier in the same policy." May appear at most once.
+ */
+export const POLICY_WILDCARD = "*";
+
+/**
+ * Maps user-facing runtime labels to PURL-type prefixes. The user-facing
+ * label is the implementation directory name a contributor sees at
+ * `modules/<name>/<label>/`.
+ */
+const LABEL_TO_PURL_TYPE: Readonly<Record<string, string>> = {
+  nodejs: "pkg:npm",
+  rust: "pkg:cargo",
+};
+
+/**
+ * Labels that only make sense as a single value (`runtime: auto`,
+ * `runtime: native`) — they describe a whole policy, not one slot in a
+ * list. `any` is also reserved but is allowed as the final list entry,
+ * so it is handled separately in `normalizeRuntime`.
+ */
+const SINGLE_ONLY_LABELS = new Set(["auto", "native"]);
+
+/**
+ * Default policy for missing `runtime:` field — equivalent to `runtime: auto`.
+ * Tries kernel-native first, then any other declared controller in declaration order.
+ */
+export const DEFAULT_POLICY: ControllerPolicy = {
+  load: [KERNEL_NATIVE_PURL_TYPE, POLICY_WILDCARD],
+};
+
+/**
+ * Resolve a `runtime:` field value (string, array, or undefined) into a
+ * canonical `ControllerPolicy`. Throws `ERR_RUNTIME_INVALID` on:
+ *  - empty array
+ *  - unknown label
+ *  - `any` anywhere but the final list entry
+ *  - duplicate label
+ */
+export function normalizeRuntime(value: string | ReadonlyArray<string> | undefined): ControllerPolicy {
+  if (value === undefined) {
+    return DEFAULT_POLICY;
+  }
+  if (typeof value === "string") {
+    return resolveSingle(value);
+  }
+  if (!Array.isArray(value)) {
+    throw new RuntimeError(
+      "ERR_RUNTIME_INVALID",
+      `runtime must be a string or array of strings, got ${typeof value}`,
+    );
+  }
+  if (value.length === 0) {
+    throw new RuntimeError(
+      "ERR_RUNTIME_INVALID",
+      "runtime: [] has no useful meaning. Omit the field for `auto`, or list at least one runtime label.",
+    );
+  }
+  const load: string[] = [];
+  for (let i = 0; i < value.length; i++) {
+    const entry = value[i];
+    if (typeof entry !== "string") {
+      throw new RuntimeError(
+        "ERR_RUNTIME_INVALID",
+        `runtime list entries must be strings, got ${typeof entry}`,
+      );
+    }
+    if (entry === "any") {
+      if (i !== value.length - 1) {
+        throw new RuntimeError(
+          "ERR_RUNTIME_INVALID",
+          "runtime: 'any' may only appear as the last entry in the list",
+        );
+      }
+      load.push(POLICY_WILDCARD);
+      continue;
+    }
+    const purlType = labelToPurlType(entry);
+    if (load.includes(purlType)) {
+      throw new RuntimeError(
+        "ERR_RUNTIME_INVALID",
+        `runtime: '${entry}' listed twice (resolves to ${purlType})`,
+      );
+    }
+    load.push(purlType);
+  }
+  return { load };
+}
+
+function resolveSingle(label: string): ControllerPolicy {
+  if (label === "auto") {
+    return DEFAULT_POLICY;
+  }
+  if (label === "native") {
+    return { load: [KERNEL_NATIVE_PURL_TYPE] };
+  }
+  if (label === "any") {
+    return { load: [POLICY_WILDCARD] };
+  }
+  return { load: [labelToPurlType(label)] };
+}
+
+function labelToPurlType(label: string): string {
+  if (SINGLE_ONLY_LABELS.has(label)) {
+    throw new RuntimeError(
+      "ERR_RUNTIME_INVALID",
+      `runtime label '${label}' describes a whole policy and is only valid as a single value, not inside a list`,
+    );
+  }
+  const purlType = LABEL_TO_PURL_TYPE[label];
+  if (!purlType) {
+    const known = Object.keys(LABEL_TO_PURL_TYPE).concat(["auto", "native", "any"]).sort().join(", ");
+    throw new RuntimeError(
+      "ERR_RUNTIME_INVALID",
+      `Unknown runtime label '${label}'. Known: ${known}`,
+    );
+  }
+  return purlType;
+}
+
+/**
+ * Stable short hash of a resolved policy, for use as a registry cache key
+ * suffix. Two imports with the same resolved policy share a cached
+ * controller; divergent policies get separate entries.
+ *
+ * Both `undefined` (no policy stamped) and any policy structurally equal to
+ * `DEFAULT_POLICY` (`runtime: auto`, missing `runtime:`, or any list that
+ * normalizes to the auto shape) collapse to the `"default"` fingerprint —
+ * the plan's contract is that "missing" is sugar for "auto", so they must
+ * share a cache entry.
+ */
+export function policyFingerprint(policy: ControllerPolicy | undefined): string {
+  if (!policy || isDefaultPolicy(policy)) {
+    return "default";
+  }
+  return policy.load.join(",");
+}
+
+/**
+ * Structural equality check against `DEFAULT_POLICY`. Used at policy-stamp
+ * time (import-controller) to skip stamping when the resolved policy is the
+ * canonical default — `runtime: auto`, `runtime: [nodejs, any]`, etc. all
+ * normalize to the same shape and should be observationally identical to a
+ * plain omitted `runtime:` field, both at the fingerprint level (handled by
+ * `policyFingerprint`) and at the policy-presence level.
+ */
+export function isDefaultPolicy(policy: ControllerPolicy): boolean {
+  if (policy === DEFAULT_POLICY) return true;
+  const a = policy.load;
+  const b = DEFAULT_POLICY.load;
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}

package/dist/manifest-adapters/local-file-adapter.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"local-file-adapter.d.ts","sourceRoot":"","sources":["../../src/manifest-adapters/local-file-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAcpF,qBAAa,gBAAiB,YAAW,eAAe;IACtD,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAU9B,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAQlE,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IASnD,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;IAMjD,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAgB/D,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;YAqB/C,kBAAkB;IAchC,OAAO,CAAC,UAAU;CAGnB"}

package/dist/manifest-adapters/local-file-adapter.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"local-file-adapter.js","sourceRoot":"","sources":["../../src/manifest-adapters/local-file-adapter.ts"],"names":[],"mappings":"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"}

package/dist/manifest-adapters/manifest-adapter.d.ts

@@ -1,35 +0,0 @@
-export interface ManifestSourceData {
-    /** Raw YAML text */
-    text: string;
-    /** Parsed YAML documents (result of yaml.loadAll) */
-    documents: any[];
-    /** Stored as metadata.source (file path or URL) */
-    source: string;
-    /** Base directory for resolving relative controller entrypoints */
-    baseDir: string;
-    /** URI prefix — full resource URI is `${uriBase}#${kind}.${name}` */
-    uriBase: string;
-}
-export interface ManifestAdapter {
-    /** Returns true if this adapter can handle the given path/URL */
-    supports(pathOrUrl: string): boolean;
-    /**
-     * Read a single manifest entry point.
-     * - File path or URL → read that file/URL.
-     * - Directory path → find and read `telo.yaml` within it.
-     */
-    read(pathOrUrl: string): Promise<ManifestSourceData>;
-    /**
-     * Read all manifest files reachable from the given path/URL.
-     * Used for module imports.
-     * - Directory path → recursive walk, one entry per .yaml/.yml file found.
-     * - File path or URL → single-item array.
-     */
-    readAll(pathOrUrl: string): Promise<ManifestSourceData[]>;
-    /**
-     * Resolve a potentially relative path/URL against a base directory/URL.
-     * For absolute inputs the base is ignored.
-     */
-    resolveRelative(base: string, relative: string): string;
-}
-//# sourceMappingURL=manifest-adapter.d.ts.map

package/dist/manifest-adapters/manifest-adapter.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"manifest-adapter.d.ts","sourceRoot":"","sources":["../../src/manifest-adapters/manifest-adapter.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,kBAAkB;IACjC,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,SAAS,EAAE,GAAG,EAAE,CAAC;IACjB,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IACrC;;;;OAIG;IACH,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACrD;;;;;OAKG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;IAC1D;;;OAGG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;CACzD"}

package/dist/manifest-adapters/manifest-adapter.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=manifest-adapter.js.map

package/dist/manifest-adapters/manifest-adapter.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"manifest-adapter.js","sourceRoot":"","sources":["../../src/manifest-adapters/manifest-adapter.ts"],"names":[],"mappings":""}

package/src/manifest-adapters/manifest-adapter.ts

@@ -1,35 +0,0 @@
-export interface ManifestSourceData {
-  /** Raw YAML text */
-  text: string;
-  /** Parsed YAML documents (result of yaml.loadAll) */
-  documents: any[];
-  /** Stored as metadata.source (file path or URL) */
-  source: string;
-  /** Base directory for resolving relative controller entrypoints */
-  baseDir: string;
-  /** URI prefix — full resource URI is `${uriBase}#${kind}.${name}` */
-  uriBase: string;
-}
-
-export interface ManifestAdapter {
-  /** Returns true if this adapter can handle the given path/URL */
-  supports(pathOrUrl: string): boolean;
-  /**
-   * Read a single manifest entry point.
-   * - File path or URL → read that file/URL.
-   * - Directory path → find and read `telo.yaml` within it.
-   */
-  read(pathOrUrl: string): Promise<ManifestSourceData>;
-  /**
-   * Read all manifest files reachable from the given path/URL.
-   * Used for module imports.
-   * - Directory path → recursive walk, one entry per .yaml/.yml file found.
-   * - File path or URL → single-item array.
-   */
-  readAll(pathOrUrl: string): Promise<ManifestSourceData[]>;
-  /**
-   * Resolve a potentially relative path/URL against a base directory/URL.
-   * For absolute inputs the base is ignored.
-   */
-  resolveRelative(base: string, relative: string): string;
-}