@telorun/kernel 0.84.0 → 0.86.0

package/src/resource-edges.ts

@@ -0,0 +1,114 @@
+/**
+ * What the create-time reference edges tell us about a set of resources.
+ *
+ * The edges themselves are captured by `collectResourceRefs` and projected onto
+ * local names by `localDependencyNames` (both in `evaluation-context.ts`, beside
+ * the init loop that records them). This module is the two questions asked of
+ * that record afterwards, and they are the same question read in opposite
+ * directions:
+ *
+ *  - **Forward**, for teardown: in what order may these unwind, so that a
+ *    consumer's inverses run while what it holds is still alive.
+ *  - **Reverse**, for reconciliation: if these resources are about to become
+ *    invalid, who else is holding one and therefore becomes invalid too.
+ *
+ * Both read `Map<consumer, provider names>` and neither knows what a resource
+ * is, which is what keeps them testable without a kernel.
+ */
+
+/** A resource's outgoing edges: the local names it holds. */
+export type DependencyMap = ReadonlyMap<string, readonly string[]>;
+
+/**
+ * Order resources so that a consumer is torn down before everything it holds.
+ *
+ * The caller's order is the TIEBREAK, not the rule. Reverse insertion is
+ * already a valid reverse-topological order for every edge Phase-5 injection
+ * resolves, because the init loop defers a resource whose refs are unresolved
+ * (`ERR_LOCAL_REF_PENDING`) and so cannot insert a consumer before its
+ * provider. What this adds is the edges that never pass through injection — a
+ * controller resolving a sibling by name inside `init()` — where insertion
+ * order says nothing.
+ *
+ * A cycle emits the first unordered entry and continues: teardown must always
+ * run to completion, so an unorderable set degrades to the caller's order
+ * rather than raising.
+ */
+export function reverseTopologicalOrder<T>(
+  entries: ReadonlyArray<readonly [string, T]>,
+  nameOf: (value: T) => string,
+  dependenciesOf: (name: string) => readonly string[] | undefined,
+): Array<readonly [string, T]> {
+  const indexByName = new Map<string, number>();
+  entries.forEach(([, value], index) => indexByName.set(nameOf(value), index));
+
+  // One edge per (consumer, provider): the provider waits for the consumer.
+  const providersOf: number[][] = entries.map(() => []);
+  const waiting: number[] = entries.map(() => 0);
+  entries.forEach(([, value], consumer) => {
+    for (const dependency of dependenciesOf(nameOf(value)) ?? []) {
+      const provider = indexByName.get(dependency);
+      if (provider === undefined || provider === consumer) continue;
+      providersOf[consumer]!.push(provider);
+      waiting[provider]! += 1;
+    }
+  });
+
+  const ordered: Array<readonly [string, T]> = [];
+  const emitted: boolean[] = entries.map(() => false);
+  for (let count = 0; count < entries.length; count++) {
+    let pick = entries.findIndex((_, i) => !emitted[i] && waiting[i] === 0);
+    if (pick < 0) pick = entries.findIndex((_, i) => !emitted[i]);
+    emitted[pick] = true;
+    ordered.push(entries[pick]!);
+    for (const provider of providersOf[pick]!) waiting[provider]! -= 1;
+  }
+  return ordered;
+}
+
+/**
+ * Every resource that becomes invalid when `seeds` do: the seeds themselves, and
+ * everything that transitively HOLDS one of them.
+ *
+ * A holder has to go with what it holds because it is holding the instance
+ * itself — Phase-5 injection wrote a live object into its reference slot, and
+ * rebuilding the target leaves the holder pointing at an object nothing will
+ * ever call again. There is no version of this where the holder keeps running,
+ * which is why replacing one resource restarts everything above it. That is a
+ * cost to state rather than a defect to fix: editing a connection's declaration
+ * restarts what uses it.
+ *
+ * **Exact over the DECLARED edge set, and only that.** An edge exists here when
+ * a reference slot named the target, or when a CEL expression read it. A
+ * controller that resolves a sibling by NAME instead has a real dependency no
+ * walk of the manifest can see; those resolutions are recorded separately as
+ * they happen (`opaquelyRead`), and a caller whose closure reaches one has to
+ * escalate rather than trust this answer.
+ *
+ * A cycle is not a special case: the walk visits each name once.
+ */
+export function impactClosure(seeds: Iterable<string>, dependencies: DependencyMap): Set<string> {
+  // Reversed once per call rather than maintained: the map moves on every
+  // create, this is asked once per reconciliation, and an index kept in step
+  // with a mutating map is a second source of truth.
+  const holdersOf = new Map<string, string[]>();
+  for (const [consumer, providers] of dependencies) {
+    for (const provider of providers) {
+      const held = holdersOf.get(provider);
+      if (held) held.push(consumer);
+      else holdersOf.set(provider, [consumer]);
+    }
+  }
+
+  const impacted = new Set<string>();
+  const queue = [...seeds];
+  while (queue.length > 0) {
+    const name = queue.pop()!;
+    if (impacted.has(name)) continue;
+    impacted.add(name);
+    for (const holder of holdersOf.get(name) ?? []) {
+      if (!impacted.has(holder)) queue.push(holder);
+    }
+  }
+  return impacted;
+}

package/src/runtime-seam.ts

@@ -167,7 +167,6 @@ export class KernelRuntimeSeam implements RuntimeSeam {
       stdout: stdout.writable,
       stderr: stderr.writable,
       sources: [...this.kernel.injectedSources],
-      registryUrl: this.kernel.registryUrl,
     });
 
     // A child that fails to load is not an exception on this side: the caller
@@ -223,7 +222,7 @@ export class KernelRuntimeSeam implements RuntimeSeam {
     // rather than the kernel's own loader because a checked manifest is often
     // deliberately broken and has no business entering the running kernel's
     // parse cache.
-    const loader = new Loader(defaultTransportRegistry(this.kernel.registryUrl).sources(), {
+    const loader = new Loader(defaultTransportRegistry().sources(), {
       celHandlers: nodeCelHandlers,
     });
     for (const injected of this.kernel.injectedSources) {

package/src/transports/http-transport.ts

@@ -0,0 +1,209 @@
+import {
+  DEFAULT_MANIFEST_FILENAME,
+  HttpSource,
+  sha256Base64Url,
+  splitIntegrity,
+  type ArtifactLayer,
+  type ManifestCacheCoords,
+  type ManifestSource,
+} from "@telorun/analyzer";
+import { fetchOrThrow } from "@telorun/sdk";
+import { createHash } from "crypto";
+
+import type { PayloadFile } from "../bundle/files-integrity.js";
+import { assertPublicEgress } from "./egress-guard.js";
+import type {
+  PayloadLayer,
+  PublishBundle,
+  PublishOptions,
+  PublishResult,
+  Transport,
+} from "./transport.js";
+
+const QUERY_HASH_LENGTH = 12;
+
+/** Mirror `HttpSource.read`'s `fetchUrl` derivation: when the URL does not
+ *  already point at a YAML file, append `/telo.yaml`, so a raw import URL and
+ *  the canonical source it resolves to map to the same cache path. */
+function normalizePathname(rawUrl: string, parsed: URL): string {
+  let pathname = parsed.pathname;
+  if (!rawUrl.includes(".yaml")) {
+    pathname = pathname.endsWith("/")
+      ? `${pathname}${DEFAULT_MANIFEST_FILENAME}`
+      : `${pathname}/${DEFAULT_MANIFEST_FILENAME}`;
+  }
+  return pathname;
+}
+
+/** Short hash of `search + hash` so two URLs that differ only in query /
+ *  fragment do not collide at the same cache path. */
+function disambiguatePath(pathname: string, search: string, hash: string): string {
+  if (!search && !hash) return pathname;
+  const digest = createHash("sha256")
+    .update(search + hash)
+    .digest("hex")
+    .slice(0, QUERY_HASH_LENGTH);
+  const dotIdx = pathname.lastIndexOf(".");
+  const slashIdx = pathname.lastIndexOf("/");
+  const ext = dotIdx > slashIdx ? pathname.slice(dotIdx) : "";
+  const base = pathname.slice(0, pathname.length - ext.length);
+  return `${base}.${digest}${ext}`;
+}
+
+/** The transport for direct `https://…` (and `http://`) module URLs. Its
+ *  resolution `source` composes the browser-safe `HttpSource` from `analyzer`;
+ *  the Node-only management methods live here. This is the fallback transport
+ *  for any ref that carries no owning scheme, so `oci://` (or a future `s3://`)
+ *  never falls through to it — those refs are claimed by their own transport's
+ *  `supports()`.
+ *
+ *  A URL addresses exactly one file, so it names no enumerable version: this
+ *  transport publishes nothing, lists no versions, and has no `@version` segment
+ *  to bump. What it does own is reading, hashing and caching those bytes. */
+export class HttpTransport implements Transport {
+  private readonly httpSource: HttpSource;
+  readonly source: ManifestSource;
+
+  constructor() {
+    this.httpSource = new HttpSource();
+    this.source = {
+      supports: (url) => this.supports(url),
+      read: async (url) => {
+        // The browser-safe source does the fetch; the Node-side egress policy
+        // is enforced here, on the host the read will actually hit.
+        await assertPublicEgress(url);
+        return this.httpSource.read(url);
+      },
+      resolveRelative: (base, relative) => this.httpSource.resolveRelative(base, relative),
+    };
+  }
+
+  supports(ref: string): boolean {
+    const { base } = splitIntegrity(ref);
+    return base.startsWith("http://") || base.startsWith("https://");
+  }
+
+  cacheCoords(ref: string): ManifestCacheCoords | null {
+    const url = splitIntegrity(ref).base;
+    if (!url.startsWith("http://") && !url.startsWith("https://")) return null;
+
+    let parsed: URL;
+    try {
+      parsed = new URL(url);
+    } catch {
+      return null;
+    }
+    const pathname = normalizePathname(url, parsed);
+
+    // `url` subtree, query-hash suffix on collision. No version segment: a URL
+    // addresses exactly one file, and the version it declares lives inside
+    // bytes the cache maps paths without.
+    const cleanPath = pathname.startsWith("/") ? pathname.slice(1) : pathname;
+    const segments = disambiguatePath(cleanPath, parsed.search, parsed.hash).split("/");
+    const file = segments.pop();
+    if (!file) return null;
+    return { transport: "url", host: parsed.host, path: segments.join("/"), file };
+  }
+
+  async listVersions(): Promise<string[] | null> {
+    // A direct `https://` URL has no version-list endpoint.
+    return null;
+  }
+
+  refVersion(): string | null {
+    // A direct `https://` URL has no version segment to bump.
+    return null;
+  }
+
+  withVersion(ref: string): string {
+    throw new Error(
+      `cannot set a version on '${ref}': a URL addresses one file and carries no version segment.`,
+    );
+  }
+
+  /** Mirrors the source's fetch-URL derivation: the URL points at (or contains)
+   *  the YAML file. `null` when this transport does not own the ref's shape. */
+  private manifestUrl(ref: string): string | null {
+    const { base } = splitIntegrity(ref);
+    if (!base.startsWith("http://") && !base.startsWith("https://")) return null;
+    return base.includes(".yaml") ? base : `${base}/${DEFAULT_MANIFEST_FILENAME}`;
+  }
+
+  async digest(ref: string): Promise<string | null> {
+    // The digest is Telo's canonical hash over the `telo.yaml` bytes — the same
+    // value `manifestHash` returns, but absent-is-null rather than a throw.
+    const fetchUrl = this.manifestUrl(ref);
+    if (!fetchUrl) return null;
+    await assertPublicEgress(fetchUrl);
+    const res = await fetchOrThrow(fetchUrl, undefined, { operation: "Module manifest read" });
+    if (res.status === 404) return null;
+    if (!res.ok) {
+      throw new Error(`${fetchUrl} returned ${res.status} ${res.statusText}`);
+    }
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    return `sha256-${await sha256Base64Url(bytes)}`;
+  }
+
+  /** Hashes the **raw response bytes**, which is exactly what `verifiedFetch`
+   *  checks an inline `#sha256-…` pin against on the read path. */
+  async manifestHash(ref: string): Promise<string> {
+    const fetchUrl = this.manifestUrl(ref);
+    if (!fetchUrl) {
+      throw new Error(`cannot hash non-remote import '${ref}'`);
+    }
+    await assertPublicEgress(fetchUrl);
+    const res = await fetchOrThrow(fetchUrl, undefined, { operation: "Module manifest hash" });
+    if (!res.ok) {
+      throw new Error(`fetch ${fetchUrl}: ${res.status} ${res.statusText}`);
+    }
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    return `sha256-${await sha256Base64Url(bytes)}`;
+  }
+
+  /** Layered artifacts are an OCI concept — a module reached over a plain URL is
+   *  manifest-only, and its controllers come from npm. */
+  async fetchLayer(ref: string, blobDigest: string): Promise<PayloadFile[]> {
+    throw new Error(
+      `Cannot fetch layer ${blobDigest} of ${ref}: a plain URL serves the manifest only. ` +
+        `A module with a bundled payload is published as an OCI artifact (oci://host/repo).`,
+    );
+  }
+
+  async layerIndex(layers: readonly PayloadLayer[]): Promise<ArtifactLayer[]> {
+    // Same boundary `fetchLayer` and `publish` draw: a plain URL serves the
+    // manifest only, so it frames no layer and can name no blob. An empty set is
+    // not a payload, so it answers rather than throws — a manifest-only module
+    // builds its payload through this transport during analysis.
+    if (layers.every((layer) => layer.files.length === 0)) return [];
+    throw new Error(
+      "A plain URL serves the manifest only, so it cannot index payload layers. " +
+        "A module with a bundled payload is published as an OCI artifact (oci://host/repo).",
+    );
+  }
+
+  async publish(
+    destination: string,
+    bundle: PublishBundle,
+    opts: PublishOptions = {},
+  ): Promise<PublishResult> {
+    // `telo publish` rejects a non-OCI destination up front, so this is only a
+    // guard for a direct programmatic call.
+    throw new Error(
+      "Publishing over HTTP has been removed. Publish to an OCI registry " +
+        "(oci://host/repo) instead.",
+    );
+  }
+
+  canonicalizeSiblingRef(destination: string, relativeSource: string, version: string): string {
+    // Canonicalizing a sibling is publish-path work, and this transport does not
+    // publish — so it refuses here for the same reason `publish` does, rather
+    // than computing a ref nothing could ever push. Silence would be worse than
+    // useless: an `https://host/` destination has no path to resolve `../lib`
+    // beside, so joining anyway yields a ref one segment short with no error.
+    throw new Error(
+      `Cannot canonicalize the relative import '${relativeSource}' against '${destination}': ` +
+        `publishing over plain HTTP has been removed. Publish to an OCI registry ` +
+        `(oci://host/repo) instead.`,
+    );
+  }
+}

package/src/transports/transport-registry.ts

@@ -1,8 +1,8 @@
 import type { ManifestCacheCoords, ManifestSource } from "@telorun/analyzer";
 
 import type { PayloadFile } from "../bundle/files-integrity.js";
+import { HttpTransport } from "./http-transport.js";
 import { OciTransport } from "./oci/oci-transport.js";
-import { RegistryTransport } from "./registry-transport.js";
 import type {
   PublishBundle,
   PublishOptions,
@@ -12,9 +12,9 @@ import type {
 
 /** Dispatches ref-scheme-specific operations to the transport that owns a ref.
  *  The loader, cache source, `upgrade`, and `publish` consult this instead of
- *  branching on ref shape. `RegistryTransport` is always last so it is the
- *  fallback for bare / `https` refs, and a scheme-owning transport (OCI, later
- *  S3) claims its refs via `supports()` before the fallback is reached. */
+ *  branching on ref shape. `HttpTransport` is always last so it is the fallback
+ *  for plain `https` refs, and a scheme-owning transport (OCI, later S3) claims
+ *  its refs via `supports()` before the fallback is reached. */
 export class TransportRegistry {
   constructor(private readonly transports: Transport[]) {}
 
@@ -73,27 +73,20 @@ export class TransportRegistry {
 }
 
 /** The default transport set. Scheme-owning transports come first; the
- *  `RegistryTransport` is last, the fallback for bare / `https` refs. OCI (and
- *  later S3) claim their `oci://` / `s3://` refs before the fallback is reached. */
-export function defaultTransports(registryUrl?: string): Transport[] {
-  return [new OciTransport(), new RegistryTransport(registryUrl)];
+ *  `HttpTransport` is last, the fallback for plain `https` refs. OCI (and later
+ *  S3) claim their `oci://` / `s3://` refs before the fallback is reached. */
+export function defaultTransports(): Transport[] {
+  return [new OciTransport(), new HttpTransport()];
 }
 
-const defaultRegistryCache = new Map<string, TransportRegistry>();
+let defaultRegistry: TransportRegistry | undefined;
 
-/** A `TransportRegistry` seeded with {@link defaultTransports}, memoized per
- *  `registryUrl`. The default transports hold no per-call state, so one shared
- *  instance per registry URL is safe — and avoids re-instantiating the whole set
- *  on hot paths like `cachePathForCanonical`. It is also what gives
- *  `OciTransport`'s per-instance read-client pool a process-wide lifetime here,
- *  so the bearer-token cache survives across operations without the pool having
- *  to be global. */
-export function defaultTransportRegistry(registryUrl?: string): TransportRegistry {
-  const key = registryUrl ?? "";
-  let cached = defaultRegistryCache.get(key);
-  if (!cached) {
-    cached = new TransportRegistry(defaultTransports(registryUrl));
-    defaultRegistryCache.set(key, cached);
-  }
-  return cached;
+/** A `TransportRegistry` seeded with {@link defaultTransports}, memoized. The
+ *  default transports hold no per-call state, so one shared instance is safe —
+ *  and avoids re-instantiating the whole set on hot paths like
+ *  `cachePathForCanonical`. It is also what gives `OciTransport`'s per-instance
+ *  read-client pool a process-wide lifetime here, so the bearer-token cache
+ *  survives across operations without the pool having to be global. */
+export function defaultTransportRegistry(): TransportRegistry {
+  return (defaultRegistry ??= new TransportRegistry(defaultTransports()));
 }

package/dist/transports/registry-transport.d.ts

@@ -1,41 +0,0 @@
-import { type ArtifactLayer, type ManifestCacheCoords, type ManifestSource } from "@telorun/analyzer";
-import type { PayloadFile } from "../bundle/files-integrity.js";
-import type { PayloadLayer, PublishBundle, PublishOptions, PublishResult, Transport } from "./transport.js";
-/** The default HTTP transport: bare `namespace/name@version` registry refs and
- *  direct `https://…` URLs, resolving against `registry.telo.run` (or a
- *  configured registry). Its resolution `source` composes the browser-safe
- *  `RegistrySource` / `HttpSource` from `analyzer`; the Node-only management
- *  methods live here. This is the fallback transport for any ref that carries
- *  no owning scheme, so `oci://` (or a future `s3://`) never falls through to
- *  it — those refs are claimed by their own transport's `supports()`. */
-export declare class RegistryTransport implements Transport {
-    private readonly registryUrl;
-    private readonly registrySource;
-    private readonly httpSource;
-    readonly source: ManifestSource;
-    constructor(registryUrl?: string);
-    supports(ref: string): boolean;
-    cacheCoords(ref: string): ManifestCacheCoords | null;
-    /** Host of the configured registry, or `null` when the URL is unparseable. */
-    private registryHost;
-    listVersions(ref: string): Promise<string[] | null>;
-    refVersion(ref: string): string | null;
-    withVersion(ref: string, version: string): string;
-    /** Mirrors the sources' fetch-URL derivation: a direct URL points at (or
-     *  contains) the YAML file; a bare registry ref folds into the registry
-     *  layout. `null` when this transport does not own the ref's shape. */
-    private manifestUrl;
-    digest(ref: string): Promise<string | null>;
-    /** Hashes the **raw response bytes**, which is exactly what `verifiedFetch`
-     *  checks an inline `#sha256-…` pin against on the read path. */
-    manifestHash(ref: string): Promise<string>;
-    /** Layered artifacts are an OCI concept, and the registry origin is read-only
-     *  — nothing has ever published a payload here, so there is no layer to pull.
-     *  A module reached over the registry is manifest-only, and its controllers
-     *  come from npm. */
-    fetchLayer(ref: string, blobDigest: string): Promise<PayloadFile[]>;
-    layerIndex(layers: readonly PayloadLayer[]): Promise<ArtifactLayer[]>;
-    publish(destination: string, bundle: PublishBundle, opts?: PublishOptions): Promise<PublishResult>;
-    canonicalizeSiblingRef(destination: string, relativeSource: string, version: string): string;
-}
-//# sourceMappingURL=registry-transport.d.ts.map

package/dist/transports/registry-transport.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"registry-transport.d.ts","sourceRoot":"","sources":["../../src/transports/registry-transport.ts"],"names":[],"mappings":"AAAA,OAAO,EAUL,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACpB,MAAM,mBAAmB,CAAC;AAI3B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAEhE,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EACb,cAAc,EACd,aAAa,EACb,SAAS,EACV,MAAM,gBAAgB,CAAC;AAkDxB;;;;;;yEAMyE;AACzE,qBAAa,iBAAkB,YAAW,SAAS;IAKrC,OAAO,CAAC,QAAQ,CAAC,WAAW;IAJxC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiB;IAChD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IACxC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;gBAEH,WAAW,GAAE,MAA6B;IAiBvE,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAK9B,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI;IAwEpD,8EAA8E;IAC9E,OAAO,CAAC,YAAY;IAQd,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC;IAoBzD,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAMtC,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM;IAIjD;;2EAEuE;IACvE,OAAO,CAAC,WAAW;IAYb,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAkBjD;qEACiE;IAC3D,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAiBhD;;;yBAGqB;IACf,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAOnE,UAAU,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAYrE,OAAO,CACX,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,aAAa,EACrB,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,aAAa,CAAC;IAWzB,sBAAsB,CACpB,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM,GACd,MAAM;CAwBV"}