@telorun/kernel 0.41.0 → 0.43.0

package/dist/transports/registry-transport.js

@@ -0,0 +1,225 @@
+import { DEFAULT_MANIFEST_FILENAME, HttpSource, IntegrityError, RegistrySource, isRegistryRef, parseModuleRef, splitIntegrity, } from "@telorun/analyzer";
+import { createHash } from "crypto";
+import { computeFilesIntegrity, injectFilesIntegrity } from "../bundle/files-integrity.js";
+import { readOwnerManifest } from "../bundle/module-manifest.js";
+import { makeTarGz, readTarGz, toPayloadFiles } from "../bundle/tar.js";
+const DEFAULT_REGISTRY_URL = "https://registry.telo.run";
+const HTTP_NAMESPACE = "__http";
+const QUERY_HASH_LENGTH = 12;
+const MAX_PUSH_ATTEMPTS = 4;
+const PUSH_BASE_DELAY_MS = 1000;
+/** Registry / object-storage backends treat 408/425/429/5xx as transient. */
+function isRetryableStatus(status) {
+    return status === 408 || status === 425 || status === 429 || status >= 500;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** 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, parsed) {
+    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, search, hash) {
+    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 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 class RegistryTransport {
+    constructor(registryUrl = DEFAULT_REGISTRY_URL) {
+        this.registryUrl = registryUrl;
+        this.registrySource = new RegistrySource(registryUrl);
+        this.httpSource = new HttpSource();
+        const pick = (ref) => this.httpSource.supports(ref) ? this.httpSource : this.registrySource;
+        this.source = {
+            supports: (url) => this.supports(url),
+            read: (url) => pick(url).read(url),
+            resolveRelative: (base, relative) => pick(base).resolveRelative(base, relative),
+        };
+    }
+    supports(ref) {
+        const { base } = splitIntegrity(ref);
+        return base.startsWith("http://") || base.startsWith("https://") || isRegistryRef(ref);
+    }
+    cacheLocation(ref) {
+        const url = splitIntegrity(ref).base;
+        const trimmedRegistry = this.registryUrl.replace(/\/+$/, "");
+        // 1. Registry ref form: namespace/name@version
+        if (isRegistryRef(url)) {
+            let parsed;
+            try {
+                parsed = parseModuleRef(url);
+            }
+            catch {
+                return null;
+            }
+            return [parsed.modulePath, parsed.version, DEFAULT_MANIFEST_FILENAME];
+        }
+        // 2. HTTP(S) URL — a direct registry URL or arbitrary external.
+        if (url.startsWith("http://") || url.startsWith("https://")) {
+            let parsed;
+            try {
+                parsed = new URL(url);
+            }
+            catch {
+                return null;
+            }
+            const pathname = normalizePathname(url, parsed);
+            // 2a. On the configured registry, no query/fragment: fold into the
+            //     registry layout so a ref and a direct URL land on the same file.
+            const normalizedUrl = `${parsed.protocol}//${parsed.host}${pathname}`;
+            if (!parsed.search &&
+                !parsed.hash &&
+                (normalizedUrl === trimmedRegistry || normalizedUrl.startsWith(`${trimmedRegistry}/`))) {
+                const rel = normalizedUrl.slice(trimmedRegistry.length + 1);
+                if (!rel)
+                    return null;
+                return rel.split("/");
+            }
+            // 2b. Arbitrary HTTP(S) → __http subtree, query-hash suffix on collision.
+            const cleanPath = pathname.startsWith("/") ? pathname.slice(1) : pathname;
+            const disambiguated = disambiguatePath(cleanPath, parsed.search, parsed.hash);
+            return [HTTP_NAMESPACE, parsed.host, ...disambiguated.split("/")];
+        }
+        return null;
+    }
+    async listVersions(ref) {
+        // Only bare registry refs are version-enumerable — a direct `https://` URL
+        // has no version-list endpoint.
+        if (!isRegistryRef(ref))
+            return null;
+        const { modulePath } = parseModuleRef(ref);
+        const url = `${this.registryUrl.replace(/\/+$/, "")}/${modulePath}`;
+        const res = await fetch(url, { headers: { accept: "application/json" } });
+        if (res.status === 404)
+            return null;
+        if (!res.ok) {
+            throw new Error(`Registry returned ${res.status} ${res.statusText} for ${modulePath}`);
+        }
+        const body = (await res.json());
+        return Array.isArray(body.versions) ? body.versions : [];
+    }
+    async fetchArtifact(ref) {
+        // `read` verifies the manifest bytes against the inline `#sha256-...` hash.
+        const { text: manifest, source } = await this.source.read(ref);
+        const meta = readOwnerManifest(manifest);
+        if (!meta.declaresFiles)
+            return { manifest, files: [] };
+        // The payload rides beside the manifest as `module.tar.gz`.
+        const tarUrl = source.replace(/\/telo\.yaml$/, "/module.tar.gz");
+        const res = await fetch(tarUrl);
+        if (!res.ok) {
+            throw new Error(`could not fetch bundle ${tarUrl}: ${res.status} ${res.statusText}`);
+        }
+        const files = toPayloadFiles(await readTarGz(Buffer.from(await res.arrayBuffer())));
+        // Verify the payload against the manifest's `filesIntegrity` before handing
+        // it back — a mismatch is terminal (a tampered bundle must never be used).
+        // The manifest that carries the hash is itself pinned by the inline hash.
+        if (meta.filesIntegrity) {
+            const actual = await computeFilesIntegrity(files);
+            if (actual !== meta.filesIntegrity) {
+                throw new IntegrityError(`Integrity check failed for bundle ${tarUrl}: filesIntegrity expected ` +
+                    `${meta.filesIntegrity}, got ${actual}. The payload does not match the recorded ` +
+                    `hash — the module may have been tampered with or republished.`);
+            }
+        }
+        return { manifest, files };
+    }
+    async publish(destination, bundle, opts = {}) {
+        // Pin the payload in the manifest before it enters the tarball, then choose
+        // the artifact body: a `module.tar.gz` when there are files, else raw YAML.
+        let manifest = bundle.manifest;
+        let body = manifest;
+        let contentType = "text/yaml";
+        let urlSuffix = "";
+        if (bundle.files.length > 0) {
+            manifest = injectFilesIntegrity(manifest, await computeFilesIntegrity(bundle.files));
+            const entries = [
+                { name: DEFAULT_MANIFEST_FILENAME, content: manifest },
+                ...bundle.files.map((f) => ({ name: f.name, content: Buffer.from(f.content) })),
+            ];
+            body = await makeTarGz(entries);
+            contentType = "application/gzip";
+            urlSuffix = "/module.tar.gz";
+        }
+        const { namespace, name, version } = readOwnerManifest(manifest);
+        if (!namespace || !name || !version) {
+            throw new Error("metadata must include namespace, name, and version.");
+        }
+        const identity = { namespace, name, version };
+        const base = `${destination.replace(/\/+$/, "")}/${identity.namespace}/${identity.name}/${identity.version}`;
+        const url = `${base}${urlSuffix}`;
+        const label = `${identity.namespace}/${identity.name}@${identity.version}`;
+        const headers = { "content-type": contentType };
+        if (opts.token)
+            headers.authorization = `Bearer ${opts.token}`;
+        let res = null;
+        let networkErr = null;
+        for (let attempt = 1; attempt <= MAX_PUSH_ATTEMPTS; attempt++) {
+            networkErr = null;
+            try {
+                res = await fetch(url, { method: "PUT", headers, body });
+            }
+            catch (err) {
+                networkErr = err;
+                res = null;
+            }
+            const transient = networkErr != null || (res != null && isRetryableStatus(res.status));
+            if (!transient)
+                break;
+            if (attempt === MAX_PUSH_ATTEMPTS)
+                break;
+            const reason = networkErr
+                ? `network error: ${networkErr instanceof Error ? networkErr.message : String(networkErr)}`
+                : `HTTP ${res.status}`;
+            // Drain the body so the underlying connection can be reused for the retry.
+            if (res)
+                await res.text().catch(() => { });
+            const delayMs = PUSH_BASE_DELAY_MS * 2 ** (attempt - 1) + Math.floor(Math.random() * 250);
+            opts.onRetry?.({ reason, attempt, maxAttempts: MAX_PUSH_ATTEMPTS, delayMs });
+            await sleep(delayMs);
+        }
+        if (networkErr) {
+            throw new Error(`Network error: ${networkErr instanceof Error ? networkErr.message : String(networkErr)} ` +
+                `(after ${MAX_PUSH_ATTEMPTS} attempts)`);
+        }
+        if (!res.ok) {
+            const ct = res.headers.get("content-type") ?? "";
+            const errBody = ct.includes("application/json") ? await res.json() : await res.text();
+            throw new Error(`Push failed (${res.status}): ${JSON.stringify(errBody)}`);
+        }
+        return { label, url };
+    }
+    canonicalizeSiblingRef(_destination, _relativeSource, sibling) {
+        // An HTTP registry path defaults to the sibling's own `<namespace>/<name>`.
+        if (!sibling.namespace || !sibling.name) {
+            throw new Error("a relative import canonicalized to an HTTP registry needs the sibling's metadata.namespace and metadata.name.");
+        }
+        return `${sibling.namespace}/${sibling.name}@${sibling.version}`;
+    }
+}
+//# sourceMappingURL=registry-transport.js.map

package/dist/transports/registry-transport.js.map

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

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

@@ -0,0 +1,40 @@
+import type { ManifestSource } from "@telorun/analyzer";
+import type { FetchedArtifact, PublishBundle, PublishOptions, PublishResult, Transport } from "./transport.js";
+/** 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. */
+export declare class TransportRegistry {
+    private readonly transports;
+    constructor(transports: Transport[]);
+    /** The transport that owns `ref`, or `undefined` if none does. */
+    forRef(ref: string): Transport | undefined;
+    /** The resolution `ManifestSource`s of every registered transport, in order —
+     *  the browser-safe subset the loader appends to its source chain. */
+    sources(): ManifestSource[];
+    /** Cache-path segments for `ref`, from its owning transport; `null` when no
+     *  transport owns it or the ref is not cacheable. */
+    cacheLocation(ref: string): string[] | null;
+    /** Published versions for `ref` via its owning transport; `null` when the
+     *  module is unpublished. Throws when no transport owns the ref. */
+    listVersions(ref: string): Promise<string[] | null>;
+    /** Full artifact for `ref` via its owning transport. Throws when no transport
+     *  owns the ref. */
+    fetchArtifact(ref: string): Promise<FetchedArtifact>;
+    /** Publish `bundle` to `destination` via the transport its scheme selects.
+     *  Throws when no transport owns the destination. */
+    publish(destination: string, bundle: PublishBundle, opts?: PublishOptions): Promise<PublishResult>;
+    private require;
+}
+/** 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 declare function defaultTransports(registryUrl?: string): Transport[];
+/** A `TransportRegistry` seeded with {@link defaultTransports}, memoized per
+ *  `registryUrl`. The default transports are stateless config (a fresh
+ *  `OciClient` with its own token cache is created per OCI operation), so one
+ *  shared instance per registry URL is safe — and avoids re-instantiating the
+ *  whole set on hot paths like `cachePathForCanonical`. */
+export declare function defaultTransportRegistry(registryUrl?: string): TransportRegistry;
+//# sourceMappingURL=transport-registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transport-registry.d.ts","sourceRoot":"","sources":["../../src/transports/transport-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAIxD,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EACb,cAAc,EACd,aAAa,EACb,SAAS,EACV,MAAM,gBAAgB,CAAC;AAExB;;;;2EAI2E;AAC3E,qBAAa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,EAAE,SAAS,EAAE;IAEpD,kEAAkE;IAClE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAI1C;0EACsE;IACtE,OAAO,IAAI,cAAc,EAAE;IAI3B;yDACqD;IACrD,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI;IAI3C;wEACoE;IACpE,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC;IAInD;wBACoB;IACpB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAIpD;yDACqD;IACrD,OAAO,CACL,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,aAAa,EACrB,IAAI,CAAC,EAAE,cAAc,GACpB,OAAO,CAAC,aAAa,CAAC;IAIzB,OAAO,CAAC,OAAO;CAOhB;AAED;;oFAEoF;AACpF,wBAAgB,iBAAiB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,EAAE,CAEnE;AAID;;;;2DAI2D;AAC3D,wBAAgB,wBAAwB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAQhF"}

package/dist/transports/transport-registry.js

@@ -0,0 +1,70 @@
+import { OciTransport } from "./oci/oci-transport.js";
+import { RegistryTransport } from "./registry-transport.js";
+/** 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. */
+export class TransportRegistry {
+    constructor(transports) {
+        this.transports = transports;
+    }
+    /** The transport that owns `ref`, or `undefined` if none does. */
+    forRef(ref) {
+        return this.transports.find((t) => t.supports(ref));
+    }
+    /** The resolution `ManifestSource`s of every registered transport, in order —
+     *  the browser-safe subset the loader appends to its source chain. */
+    sources() {
+        return this.transports.map((t) => t.source);
+    }
+    /** Cache-path segments for `ref`, from its owning transport; `null` when no
+     *  transport owns it or the ref is not cacheable. */
+    cacheLocation(ref) {
+        return this.forRef(ref)?.cacheLocation(ref) ?? null;
+    }
+    /** Published versions for `ref` via its owning transport; `null` when the
+     *  module is unpublished. Throws when no transport owns the ref. */
+    listVersions(ref) {
+        return this.require(ref).listVersions(ref);
+    }
+    /** Full artifact for `ref` via its owning transport. Throws when no transport
+     *  owns the ref. */
+    fetchArtifact(ref) {
+        return this.require(ref).fetchArtifact(ref);
+    }
+    /** Publish `bundle` to `destination` via the transport its scheme selects.
+     *  Throws when no transport owns the destination. */
+    publish(destination, bundle, opts) {
+        return this.require(destination).publish(destination, bundle, opts);
+    }
+    require(ref) {
+        const transport = this.forRef(ref);
+        if (!transport) {
+            throw new Error(`no transport owns ref '${ref}'`);
+        }
+        return transport;
+    }
+}
+/** 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) {
+    return [new OciTransport(), new RegistryTransport(registryUrl)];
+}
+const defaultRegistryCache = new Map();
+/** A `TransportRegistry` seeded with {@link defaultTransports}, memoized per
+ *  `registryUrl`. The default transports are stateless config (a fresh
+ *  `OciClient` with its own token cache is created per OCI operation), so one
+ *  shared instance per registry URL is safe — and avoids re-instantiating the
+ *  whole set on hot paths like `cachePathForCanonical`. */
+export function defaultTransportRegistry(registryUrl) {
+    const key = registryUrl ?? "";
+    let cached = defaultRegistryCache.get(key);
+    if (!cached) {
+        cached = new TransportRegistry(defaultTransports(registryUrl));
+        defaultRegistryCache.set(key, cached);
+    }
+    return cached;
+}
+//# sourceMappingURL=transport-registry.js.map

package/dist/transports/transport-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport-registry.js","sourceRoot":"","sources":["../../src/transports/transport-registry.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAS5D;;;;2EAI2E;AAC3E,MAAM,OAAO,iBAAiB;IAC5B,YAA6B,UAAuB;QAAvB,eAAU,GAAV,UAAU,CAAa;IAAG,CAAC;IAExD,kEAAkE;IAClE,MAAM,CAAC,GAAW;QAChB,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;IACtD,CAAC;IAED;0EACsE;IACtE,OAAO;QACL,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAC9C,CAAC;IAED;yDACqD;IACrD,aAAa,CAAC,GAAW;QACvB,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,aAAa,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC;IACtD,CAAC;IAED;wEACoE;IACpE,YAAY,CAAC,GAAW;QACtB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;IAC7C,CAAC;IAED;wBACoB;IACpB,aAAa,CAAC,GAAW;QACvB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;IAC9C,CAAC;IAED;yDACqD;IACrD,OAAO,CACL,WAAmB,EACnB,MAAqB,EACrB,IAAqB;QAErB,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;IACtE,CAAC;IAEO,OAAO,CAAC,GAAW;QACzB,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,0BAA0B,GAAG,GAAG,CAAC,CAAC;QACpD,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;CACF;AAED;;oFAEoF;AACpF,MAAM,UAAU,iBAAiB,CAAC,WAAoB;IACpD,OAAO,CAAC,IAAI,YAAY,EAAE,EAAE,IAAI,iBAAiB,CAAC,WAAW,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,MAAM,oBAAoB,GAAG,IAAI,GAAG,EAA6B,CAAC;AAElE;;;;2DAI2D;AAC3D,MAAM,UAAU,wBAAwB,CAAC,WAAoB;IAC3D,MAAM,GAAG,GAAG,WAAW,IAAI,EAAE,CAAC;IAC9B,IAAI,MAAM,GAAG,oBAAoB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC3C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,GAAG,IAAI,iBAAiB,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC,CAAC;QAC/D,oBAAoB,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/transports/transport.d.ts

@@ -0,0 +1,92 @@
+import type { ManifestSource } from "@telorun/analyzer";
+import type { PayloadFile } from "../bundle/files-integrity.js";
+/** The full module artifact a transport delivers: the `telo.yaml` bytes plus
+ *  the decompressed `files:` payload (empty for a manifest-only module). The
+ *  manifest is already verified against the import's inline hash; the payload
+ *  against the manifest-embedded `filesIntegrity`. */
+export interface FetchedArtifact {
+    manifest: string;
+    files: PayloadFile[];
+}
+/** The module bundle handed to a transport for publishing: the final,
+ *  already-analyzed / pinned / canonicalized `telo.yaml` bytes plus the `files:`
+ *  payload (empty for a manifest-only module). The transport is responsible for
+ *  pinning the payload (`filesIntegrity`) and for the artifact shape it writes
+ *  (HTTP: `telo.yaml` + `module.tar.gz`; OCI: a single blob). */
+export interface PublishBundle {
+    manifest: string;
+    files: PayloadFile[];
+}
+export interface PublishResult {
+    /** Human-readable `<ns>/<name>@<version>` label of what was pushed. */
+    label: string;
+    /** The location the artifact was written to. */
+    url: string;
+}
+/** Identity of a sibling library, read from its own manifest, that a relative
+ *  import canonicalizes to. `version` is always required; `namespace`/`name` are
+ *  used only by transports whose location is metadata-derived (HTTP registry). */
+export interface SiblingIdentity {
+    namespace?: string;
+    name?: string;
+    version: string;
+}
+export interface PublishOptions {
+    /** Bearer token for registries that require auth. */
+    token?: string;
+    /** Notified before each backoff sleep on a transient push failure, so the
+     *  caller can surface retry progress. */
+    onRetry?: (info: {
+        reason: string;
+        attempt: number;
+        maxAttempts: number;
+        delayMs: number;
+    }) => void;
+}
+/** A Transport owns everything ref-scheme-specific about a module's lifecycle:
+ *  resolution (through its `ManifestSource`), cache placement, version
+ *  enumeration, full-artifact fetch, and publish. Registering a transport is
+ *  the only thing needed to add a backend — the loader, cache, `upgrade`, and
+ *  `publish` never branch on scheme again; they ask the {@link TransportRegistry}
+ *  which transport owns a ref and delegate.
+ *
+ *  A Transport *composes* a resolution `ManifestSource`, it does not extend it:
+ *  `ManifestSource` is the browser-safe resolution primitive (also implemented
+ *  by the cache / local / memory sources, which have no versions and nothing to
+ *  publish), so it stays in `analyzer`, while the Node-only management methods
+ *  (`cacheLocation` and, in later phases, `listVersions` / `fetchArtifact` /
+ *  `publish`) live on the Transport here in `kernel`. */
+export interface Transport {
+    /** True when this transport owns the given ref (or publish destination). */
+    supports(ref: string): boolean;
+    /** The resolution primitive: fetch + verify `telo.yaml`, resolve relatives.
+     *  Browser-safe for a browser-reachable transport (HTTP/registry), so it can
+     *  live in `analyzer`; a Node-only transport has no browser-safe source. */
+    readonly source: ManifestSource;
+    /** Deterministic cache-path segments for a ref, joined under the cache root by
+     *  the cache source. Returns `null` when the ref is not cacheable here
+     *  (unsupported scheme, malformed ref, or path-traversal in the ref). */
+    cacheLocation(ref: string): string[] | null;
+    /** The versions published for the module `ref` names, newest-first order not
+     *  guaranteed (the caller sorts). Returns `null` when the module is not
+     *  published (e.g. a 404), distinct from `[]` (published, no versions). Used
+     *  by `telo upgrade`. */
+    listVersions(ref: string): Promise<string[] | null>;
+    /** Retrieve the full artifact for `ref` — the `telo.yaml` and its `files:`
+     *  payload — verifying the manifest against the inline hash and the payload
+     *  against the manifest's `filesIntegrity`. Used by `telo install`; subsumes
+     *  the out-of-band bundle fetch that used to sit outside the source chain. */
+    fetchArtifact(ref: string): Promise<FetchedArtifact>;
+    /** Push `bundle` to `destination` (a base ref / repo whose scheme this
+     *  transport owns), pinning the payload and writing the transport-native
+     *  artifact shape. Throws on failure. Used by `telo publish`. */
+    publish(destination: string, bundle: PublishBundle, opts?: PublishOptions): Promise<PublishResult>;
+    /** Canonicalize a relative sibling import (`../lib`) declared in a module
+     *  being published to `destination` into the absolute ref it will resolve to
+     *  once published. Owns the scheme-specific "where does a sibling land" rule —
+     *  OCI derives the repo from the destination, HTTP from the sibling's
+     *  `<namespace>/<name>` — so `telo publish` delegates instead of branching on
+     *  transport shape. */
+    canonicalizeSiblingRef(destination: string, relativeSource: string, sibling: SiblingIdentity): string;
+}
+//# sourceMappingURL=transport.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/transports/transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAEhE;;;sDAGsD;AACtD,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAED;;;;iEAIiE;AACjE,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;kFAEkF;AAClF,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;6CACyC;IACzC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE;QACf,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;KACjB,KAAK,IAAI,CAAC;CACZ;AAED;;;;;;;;;;;;yDAYyD;AACzD,MAAM,WAAW,SAAS;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAE/B;;gFAE4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAEhC;;6EAEyE;IACzE,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC;IAE5C;;;6BAGyB;IACzB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC;IAEpD;;;kFAG8E;IAC9E,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAErD;;qEAEiE;IACjE,OAAO,CACL,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,aAAa,EACrB,IAAI,CAAC,EAAE,cAAc,GACpB,OAAO,CAAC,aAAa,CAAC,CAAC;IAE1B;;;;;2BAKuB;IACvB,sBAAsB,CACpB,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,eAAe,GACvB,MAAM,CAAC;CACX"}

package/dist/transports/transport.js

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

package/dist/transports/transport.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/kernel",
-  "version": "0.41.0",
+  "version": "0.43.0",
   "description": "Telo Runtime - A lightweight, polyglot execution host.",
   "keywords": [
     "telo",
@@ -47,16 +47,18 @@
   "dependencies": {
     "@marcbachmann/cel-js": "^7.6.1",
     "@sinclair/typebox": "^0.34.48",
-    "@telorun/analyzer": "0.31.0",
+    "@telorun/analyzer": "0.33.0",
     "@telorun/glob": "0.2.0",
-    "@telorun/templating": "0.10.0",
+    "@telorun/templating": "0.10.1",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "packageurl-js": "^2.0.1",
+    "tar-stream": "^3.1.7",
     "yaml": "^2.8.3"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
+    "@types/tar-stream": "^3.1.3",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
     "@telorun/sdk": "0.41.0"
@@ -76,6 +78,7 @@
     "ajv": "$ajv",
     "ajv-formats": "$ajv-formats",
     "packageurl-js": "$packageurl-js",
+    "tar-stream": "$tar-stream",
     "yaml": "$yaml"
   },
   "scripts": {

package/src/bundle/files-integrity.ts

@@ -0,0 +1,46 @@
+import { DEFAULT_MANIFEST_FILENAME, sha256Base64Url } from "@telorun/analyzer";
+
+import { findOwnerDoc, parseManifestDocs } from "./module-manifest.js";
+
+export interface PayloadFile {
+  /** POSIX-relative path inside the bundle. */
+  name: string;
+  content: Buffer | Uint8Array;
+}
+
+/**
+ * Canonical per-file content digest of a module's `files:` payload — the value
+ * of `filesIntegrity` in a bundle's `telo.yaml`. SHA-256 over the sorted
+ * `<path>\0<sha256(content)>` lines of every payload file, `telo.yaml`
+ * excluded (the importer's `#sha256-...` hash already covers the manifest, and
+ * excluding it breaks the self-reference — the manifest embeds this value).
+ *
+ * Hashing file *contents* rather than the tar/gzip bytes makes the digest
+ * independent of archive framing, so publisher and client compute the same
+ * value from the same file set, and it can be re-derived from the extracted
+ * files on disk. Returns `sha256-<base64url>`.
+ */
+export async function computeFilesIntegrity(files: PayloadFile[]): Promise<string> {
+  const lines: string[] = [];
+  for (const file of files) {
+    if (file.name === DEFAULT_MANIFEST_FILENAME) continue;
+    const bytes = file.content instanceof Uint8Array ? file.content : new Uint8Array(file.content);
+    lines.push(`${file.name}\0${await sha256Base64Url(bytes)}`);
+  }
+  lines.sort();
+  const canonical = new TextEncoder().encode(lines.join("\n"));
+  return `sha256-${await sha256Base64Url(canonical)}`;
+}
+
+/** Write `filesIntegrity` onto the manifest's owner doc so the published
+ *  `telo.yaml` pins its payload — transitively covered by importers'
+ *  `#sha256-...` hash. The digest excludes `telo.yaml`, so injecting it does
+ *  not change the digest. Returns the manifest unchanged when it has no owner
+ *  doc. */
+export function injectFilesIntegrity(manifest: string, hash: string): string {
+  const docs = parseManifestDocs(manifest);
+  const owner = findOwnerDoc(docs);
+  if (!owner) return manifest;
+  owner.set("filesIntegrity", hash);
+  return docs.map((d) => d.toString()).join("---\n");
+}

package/src/bundle/module-manifest.ts

@@ -0,0 +1,49 @@
+import { defaultCustomTags } from "@telorun/templating";
+import { parseAllDocuments, type Document } from "yaml";
+
+const OWNER_KINDS = new Set(["Telo.Application", "Telo.Library"]);
+
+/** Parse a manifest's YAML documents, tolerating its `!cel` / `!ref` tags. */
+export function parseManifestDocs(text: string): Document[] {
+  return parseAllDocuments(text, { customTags: defaultCustomTags() });
+}
+
+/** The owner document of a manifest — the single `Telo.Application` /
+ *  `Telo.Library` doc that carries its identity, `files:`, and `filesIntegrity`.
+ *  The one place that selects it, shared by every reader/writer. */
+export function findOwnerDoc(docs: Document[]): Document | undefined {
+  return docs.find((d) => {
+    const kind = (d.toJSON() as { kind?: string } | null)?.kind;
+    return kind !== undefined && OWNER_KINDS.has(kind);
+  });
+}
+
+/** The owner-doc fields the transports read: identity for the publish location,
+ *  and payload markers for artifact fetch. */
+export interface OwnerManifest {
+  namespace?: string;
+  name?: string;
+  version?: string;
+  filesIntegrity?: string;
+  /** True when the owner doc declares a non-empty `files:` list. */
+  declaresFiles: boolean;
+}
+
+/** Read the owner doc's identity + payload fields from a manifest, parsing once
+ *  (never regex-scraping). The single source both transports call for
+ *  `<namespace>/<name>/<version>`, `filesIntegrity`, and payload detection. */
+export function readOwnerManifest(text: string): OwnerManifest {
+  const owner = findOwnerDoc(parseManifestDocs(text));
+  const parsed = owner?.toJSON() as
+    | { metadata?: Record<string, unknown>; files?: unknown; filesIntegrity?: unknown }
+    | undefined;
+  const md = parsed?.metadata ?? {};
+  const str = (v: unknown): string | undefined => (typeof v === "string" ? v : undefined);
+  return {
+    namespace: str(md.namespace),
+    name: str(md.name),
+    version: str(md.version),
+    filesIntegrity: str(parsed?.filesIntegrity),
+    declaresFiles: Array.isArray(parsed?.files) && parsed.files.length > 0,
+  };
+}