@nodetool-ai/runtime 0.7.0-rc.23 → 0.8.1

package/dist/media-ref-bytes.js

@@ -0,0 +1,181 @@
+import { isPackageAssetUri, isRawRgbaImage } from "@nodetool-ai/protocol";
+import { getNodeBuiltinSync } from "@nodetool-ai/config";
+import { fetchExternalMedia } from "./external-media-fetch.js";
+import { encodeRawRgbaToPng } from "./image-codec.js";
+import { isNonEmptyString } from "@nodetool-ai/protocol";
+const _nodeFsP = getNodeBuiltinSync("node:fs/promises");
+const _nodeUrl = getNodeBuiltinSync("node:url");
+const readFile = (...args) => _nodeFsP
+    ? _nodeFsP.readFile(...args)
+    : Promise.reject(new Error("node:fs/promises.readFile requires Node"));
+const fileURLToPath = (u) => {
+    if (!_nodeUrl)
+        throw new Error("node:url.fileURLToPath requires Node");
+    return _nodeUrl.fileURLToPath(u);
+};
+/**
+ * Decode base64 → bytes without requiring the `Buffer` global. This module is
+ * shared with the browser bundle (the in-browser runner loads it inside a Web
+ * Worker, which has no `Buffer`), so prefer `Buffer` on Node for speed and fall
+ * back to `atob` everywhere else.
+ */
+function decodeBase64(b64) {
+    if (typeof Buffer !== "undefined") {
+        return new Uint8Array(Buffer.from(b64, "base64"));
+    }
+    const binary = atob(b64);
+    const out = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1)
+        out[i] = binary.charCodeAt(i);
+    return out;
+}
+/** Encode bytes → base64 without requiring the `Buffer` global. */
+export function encodeBase64(bytes) {
+    if (typeof Buffer !== "undefined") {
+        return Buffer.from(bytes).toString("base64");
+    }
+    const chunks = [];
+    const CHUNK = 0x8000;
+    for (let i = 0; i < bytes.length; i += CHUNK) {
+        chunks.push(String.fromCharCode(...bytes.subarray(i, i + CHUNK)));
+    }
+    return btoa(chunks.join(""));
+}
+/** Encode a UTF-8 string → bytes without requiring the `Buffer` global. */
+function encodeUtf8(text) {
+    if (typeof Buffer !== "undefined") {
+        return new Uint8Array(Buffer.from(text, "utf-8"));
+    }
+    return new TextEncoder().encode(text);
+}
+const ASSET_ID_EXTENSION_CANDIDATES = {
+    image: ["png", "jpg", "jpeg", "webp", "gif", "bmp", "svg"],
+    audio: ["wav", "mp3", "ogg", "m4a", "aac", "flac"],
+    video: ["mp4", "webm", "mov", "avi", "mpeg", "mkv"],
+    model3d: ["glb", "gltf", "obj", "fbx"]
+};
+export function isAbsoluteFilePath(uri) {
+    return (/^[A-Za-z]:[\\/]/.test(uri) || uri.startsWith("\\\\") || uri.startsWith("/"));
+}
+/** Decode a `data:` URI's payload, honoring the `;base64` header flag. */
+function decodeDataUri(uri) {
+    // Split on the FIRST comma only: the header ends there and everything after
+    // is payload. `split(",", 2)` would discard payload past a second comma,
+    // corrupting non-base64 data (SVG path data, CSV, text) that contains commas.
+    const comma = uri.indexOf(",");
+    if (comma < 0) {
+        return null;
+    }
+    const header = uri.slice(0, comma);
+    const data = uri.slice(comma + 1);
+    try {
+        // decodeURIComponent throws URIError on a malformed percent-escape; the
+        // resolver contract is null-on-failure, so never let that escape.
+        return header.includes(";base64")
+            ? decodeBase64(data)
+            : encodeUtf8(decodeURIComponent(data));
+    }
+    catch {
+        return null;
+    }
+}
+async function readUriBytes(uri) {
+    if (uri.startsWith("data:")) {
+        return decodeDataUri(uri);
+    }
+    if (uri.startsWith("file://")) {
+        try {
+            return await readFile(fileURLToPath(uri));
+        }
+        catch {
+            return null;
+        }
+    }
+    if (isAbsoluteFilePath(uri)) {
+        try {
+            return await readFile(uri);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+/**
+ * Resolve bytes for an image/audio/video/model ref.
+ * Shared by the Python bridge and TS nodes (e.g. Save Image).
+ */
+export async function loadMediaRefBytes(value, context) {
+    if (isRawRgbaImage(value)) {
+        return encodeRawRgbaToPng(value.data, value.width, value.height);
+    }
+    const data = value.data;
+    if (isNonEmptyString(data)) {
+        return data.startsWith("data:") ? decodeDataUri(data) : decodeBase64(data);
+    }
+    if (data instanceof Uint8Array && data.length > 0) {
+        return data;
+    }
+    const uri = value.uri;
+    if (!uri && !value.asset_id) {
+        return null;
+    }
+    if (uri && (uri.startsWith("asset://") || isPackageAssetUri(uri)) && context) {
+        const { bytes } = await context.resolveAssetBytes(uri);
+        if (bytes) {
+            return bytes;
+        }
+    }
+    // No usable uri but an asset_id is present: resolve the asset directly by id.
+    // The early-return above only bails when both uri and asset_id are absent, so
+    // an empty-uri ref like `{ asset_id, uri: "" }` still reaches this path.
+    if (!uri && value.asset_id && context) {
+        const { bytes } = await context.resolveAssetBytes(`asset://${value.asset_id}`);
+        if (bytes) {
+            return bytes;
+        }
+    }
+    if (context?.storage) {
+        const candidates = new Set();
+        if (uri) {
+            candidates.add(uri);
+        }
+        if (value.asset_id) {
+            const refType = (value.type ?? "").toLowerCase();
+            const extensions = ASSET_ID_EXTENSION_CANDIDATES[refType] ?? ["bin"];
+            for (const extension of extensions) {
+                candidates.add(`/api/storage/${value.asset_id}.${extension}`);
+            }
+        }
+        for (const candidate of candidates) {
+            const stored = await context.storage.retrieve(candidate);
+            if (stored !== null) {
+                return stored;
+            }
+        }
+    }
+    if (!uri) {
+        return null;
+    }
+    const fromUri = await readUriBytes(uri);
+    if (fromUri !== null) {
+        return fromUri;
+    }
+    if (uri.startsWith("http://") || uri.startsWith("https://")) {
+        // Last resort, and the only branch that opens a socket: the uri is caller
+        // data, so it goes through the media-ref egress policy rather than a bare
+        // fetch. A refusal throws and lands in the catch, which is this function's
+        // contract for "no bytes" either way.
+        try {
+            const response = await fetchExternalMedia(uri);
+            if (response.ok) {
+                return new Uint8Array(await response.arrayBuffer());
+            }
+        }
+        catch {
+            // fall through
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=media-ref-bytes.js.map

package/dist/media-ref-bytes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-ref-bytes.js","sourceRoot":"","sources":["../src/media-ref-bytes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD,MAAM,QAAQ,GAAG,kBAAkB,CACjC,kBAAkB,CACnB,CAAC;AACF,MAAM,QAAQ,GAAG,kBAAkB,CAA4B,UAAU,CAAC,CAAC;AAC3E,MAAM,QAAQ,GAAG,CACf,GAAG,IAA4D,EAC9C,EAAE,CACnB,QAAQ;IACN,CAAC,CAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAqB;IACjD,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC,CAAC;AAC3E,MAAM,aAAa,GAAG,CAAC,CAAe,EAAU,EAAE;IAChD,IAAI,CAAC,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IACvE,OAAO,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;AACnC,CAAC,CAAC;AAEF;;;;;GAKG;AACH,SAAS,YAAY,CAAC,GAAW;IAC/B,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QAClC,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC;IACpD,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;IACzB,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC1C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC;QAAE,GAAG,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IACzE,OAAO,GAAG,CAAC;AACb,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,YAAY,CAAC,KAAiB;IAC5C,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QAClC,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC/C,CAAC;IACD,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,KAAK,GAAG,MAAM,CAAC;IACrB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC;QAC7C,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACpE,CAAC;IACD,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;AAC/B,CAAC;AAED,2EAA2E;AAC3E,SAAS,UAAU,CAAC,IAAY;IAC9B,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QAClC,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;IACpD,CAAC;IACD,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AACxC,CAAC;AAYD,MAAM,6BAA6B,GAA6B;IAC9D,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC;IAC1D,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC;IAClD,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC;IACnD,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC;CACvC,CAAC;AAEF,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,OAAO,CACL,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAC7E,CAAC;AACJ,CAAC;AAED,0EAA0E;AAC1E,SAAS,aAAa,CAAC,GAAW;IAChC,4EAA4E;IAC5E,yEAAyE;IACzE,8EAA8E;IAC9E,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACd,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IACnC,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;IAClC,IAAI,CAAC;QACH,wEAAwE;QACxE,kEAAkE;QAClE,OAAO,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC;YAC/B,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC;YACpB,CAAC,CAAC,UAAU,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,KAAK,UAAU,YAAY,CAAC,GAAW;IACrC,IAAI,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,OAAO,aAAa,CAAC,GAAG,CAAC,CAAC;IAC5B,CAAC;IAED,IAAI,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC9B,IAAI,CAAC;YACH,OAAO,MAAM,QAAQ,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC;QAC5C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,IAAI,kBAAkB,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5B,IAAI,CAAC;YACH,OAAO,MAAM,QAAQ,CAAC,GAAG,CAAC,CAAC;QAC7B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,KAAoB,EACpB,OAA2B;IAE3B,IAAI,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,kBAAkB,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACnE,CAAC;IAED,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;IACxB,IAAI,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3B,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;IAC7E,CAAC;IACD,IAAI,IAAI,YAAY,UAAU,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC;IACtB,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;QAC5B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC,IAAI,iBAAiB,CAAC,GAAG,CAAC,CAAC,IAAI,OAAO,EAAE,CAAC;QAC7E,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,OAAO,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC;QACvD,IAAI,KAAK,EAAE,CAAC;YACV,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,8EAA8E;IAC9E,8EAA8E;IAC9E,yEAAyE;IACzE,IAAI,CAAC,GAAG,IAAI,KAAK,CAAC,QAAQ,IAAI,OAAO,EAAE,CAAC;QACtC,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,OAAO,CAAC,iBAAiB,CAC/C,WAAW,KAAK,CAAC,QAAQ,EAAE,CAC5B,CAAC;QACF,IAAI,KAAK,EAAE,CAAC;YACV,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,IAAI,OAAO,EAAE,OAAO,EAAE,CAAC;QACrB,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;QACrC,IAAI,GAAG,EAAE,CAAC;YACR,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACtB,CAAC;QAED,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;YACnB,MAAM,OAAO,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;YACjD,MAAM,UAAU,GAAG,6BAA6B,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACrE,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;gBACnC,UAAU,CAAC,GAAG,CAAC,gBAAgB,KAAK,CAAC,QAAQ,IAAI,SAAS,EAAE,CAAC,CAAC;YAChE,CAAC;QACH,CAAC;QAED,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACnC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;YACzD,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;gBACpB,OAAO,MAAM,CAAC;YAChB,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,GAAG,CAAC,CAAC;IACxC,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACrB,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,IAAI,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5D,0EAA0E;QAC1E,0EAA0E;QAC1E,2EAA2E;QAC3E,sCAAsC;QACtC,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,kBAAkB,CAAC,GAAG,CAAC,CAAC;YAC/C,IAAI,QAAQ,CAAC,EAAE,EAAE,CAAC;gBAChB,OAAO,IAAI,UAAU,CAAC,MAAM,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;YACtD,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,eAAe;QACjB,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/node-executor.d.ts

@@ -6,28 +6,126 @@
  * interface for backward compatibility.
  */
 import type { ProcessingContext } from "./context.js";
+import type { CorrelationLineage } from "@nodetool-ai/protocol";
 /**
  * Read-side interface for streaming input nodes.
  * Nodes call stream() or any() to consume incoming data.
+ *
+ * The `*WithEnvelope` variants expose correlation lineage and source edge
+ * ids; explicit join nodes (Zip/Cross) and forwarding nodes use them to
+ * preserve §3 lineage downstream.
  */
 export interface StreamingInputs {
     /** Yield items for a single handle until EOS. */
     stream(name: string): AsyncGenerator<unknown>;
+    /** Yield MessageEnvelopes for a single handle until EOS. §5. */
+    streamWithEnvelope(name: string): AsyncGenerator<MessageEnvelopeLike>;
     /** Yield [handle, item] tuples in arrival order across all handles. */
     any(): AsyncGenerator<[string, unknown]>;
-    /** Return the first available item for a handle, or default if EOS. */
+    /** Yield [handle, MessageEnvelope] tuples in arrival order. */
+    anyWithEnvelope(): AsyncGenerator<[string, MessageEnvelopeLike]>;
+    /**
+     * Return the first available item for a handle, or default if EOS.
+     *
+     * HOLDOUT (anti-slop/no-unknown-returns): the item is an arbitrary workflow
+     * value, the same open domain `stream()` and `any()` yield.
+     */
     first(name: string, defaultValue?: unknown): Promise<unknown>;
+    /**
+     * Static scope (ordered iteration roots, outermost first) for a connected
+     * input handle. Returns `[]` if the handle has no static scope (constant /
+     * config edge), or if correlation analysis was not run.
+     *
+     * Used by join nodes (§7) to identify each side's differing iteration root
+     * and project to the common parent prefix.
+     */
+    scopeFor(handle: string): ReadonlyArray<string>;
+    /**
+     * The node's invocation scope — the largest non-empty input scope under the
+     * legacy comparable-prefix rule, or the longest common parent prefix on
+     * join nodes (§7). `[]` when analysis is off or the node has no inputs.
+     */
+    invocationScope(): ReadonlyArray<string>;
+    /**
+     * True if the handle has at least one open upstream source. Distinguishes
+     * patched from unpatched optional streaming inputs (upstream counts are
+     * registered before actors start, so this is race-free at the top of
+     * `run()`).
+     */
+    hasStream(name: string): boolean;
+    /**
+     * True if the handle has items already queued and not yet consumed.
+     * Optional: the kernel's `NodeInputs` implements it, hand-rolled test
+     * doubles need not. Together with {@link hasStream} it answers "could a
+     * take on this handle still produce a value?" — what the Code node's
+     * `stream.open(name)` reports to the guest.
+     */
+    hasBuffered?(name: string): boolean;
+    /**
+     * Aborted when the run is cancelled. Producers that emit without waiting
+     * on inputs (generators, wall-clock pacers) must observe it — inbox
+     * closure only unblocks consumers, it does not stop a producing loop.
+     */
+    readonly signal: AbortSignal;
+}
+/**
+ * Minimal MessageEnvelope shape visible to nodes. Mirrors
+ * `kernel/inbox.MessageEnvelope` without forcing runtime to import kernel
+ * (kernel depends on runtime, not the other way around).
+ */
+export interface MessageEnvelopeLike {
+    data: unknown;
+    metadata: Record<string, unknown>;
+    timestamp: number;
+    event_id: string;
+    correlation_lineage: CorrelationLineage;
+    source_edge_id: string;
 }
 /**
  * Write-side interface for streaming output from within a run() method.
  * Nodes call emit() to push partial results downstream immediately.
+ *
+ * `forward` copies an envelope's correlation lineage onto the emitted value
+ * — essential for stream nodes that act as filters/passthroughs. `drop`
+ * sends `lineage_done` for the source key so downstream joins do not wait
+ * on a key that was deliberately not emitted. §5.
  */
 export interface StreamingOutputs {
     /** Emit a value to a named output slot. */
-    emit(slot: string, value: unknown): Promise<void>;
+    emit(slot: string, value: unknown, opts?: {
+        lineage?: CorrelationLineage;
+    }): Promise<void>;
+    /**
+     * Emit a frame of grouped values atomically. Every sibling handle that
+     * shares an iteration group (same root id) receives the **same** minted
+     * token, so a Zip pair (`{ left, right, index }`) is one logical item
+     * downstream — not three independent items with different tokens. §1.
+     *
+     * Non-iteration handles in `values` inherit the supplied `opts.lineage`
+     * (or the actor's ambient invocation lineage if omitted).
+     */
+    emitGroup(values: Record<string, unknown>, opts?: {
+        lineage?: CorrelationLineage;
+    }): Promise<void>;
+    /** Forward an envelope's lineage to `slot`. §5. */
+    forward(slot: string, envelope: MessageEnvelopeLike, ...overrideValue: [] | [unknown]): Promise<void>;
+    /** Send `lineage_done` for `slot` at the envelope's projected key. §5. */
+    drop(slot: string, envelope: MessageEnvelopeLike): Promise<void>;
     /** Signal early end-of-stream for a specific output slot. */
     complete(slot: string): void;
 }
+/**
+ * A durably stored trigger input delivered into a run. Mirrors
+ * `RunJobRequest.trigger_event` and `ProcessingContext.triggerEvent`.
+ * `node_id` names the trigger node the event targets; `payload` is the
+ * adapter-captured event data; `input_id` is the idempotency key of the
+ * `trigger_inputs` row that produced this run.
+ */
+export interface TriggerEvent {
+    node_id: string;
+    payload: unknown;
+    input_id: string;
+}
 export interface NodeExecutor {
     /** One-shot processing (buffered mode). */
     process(inputs: Record<string, unknown>, context?: ProcessingContext): Promise<Record<string, unknown>>;
@@ -43,11 +141,24 @@ export interface NodeExecutor {
      * pushes results via `outputs.emit()`.
      */
     run?(inputs: StreamingInputs, outputs: StreamingOutputs, context?: ProcessingContext): Promise<void>;
+    /**
+     * Apply property updates to a live executor instance. Long-running
+     * streaming nodes (synth generators, realtime effects) that read their
+     * properties per chunk pick the new values up on the next chunk —
+     * the basis for live parameter changes while a patch is running.
+     */
+    applyProperties?(properties: Record<string, unknown>): void;
     /** Called before process/genProcess. */
     preProcess?(): Promise<void>;
     /** Called after process/genProcess completes. */
     finalize?(): Promise<void>;
     /** Called once during graph initialization. */
     initialize?(): Promise<void>;
+    /**
+     * Trigger entry point. Called instead of genProcess()/run() when the run
+     * carries a `trigger_event` targeting this node: emit the event payload
+     * on the declared output slots and return — no live listening.
+     */
+    emitTriggerEvent?(event: TriggerEvent, outputs: StreamingOutputs): Promise<void>;
 }
 //# sourceMappingURL=node-executor.d.ts.map

package/dist/node-executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node-executor.d.ts","sourceRoot":"","sources":["../src/node-executor.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAMtD;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,iDAAiD;IACjD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IAC9C,uEAAuE;IACvE,GAAG,IAAI,cAAc,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACzC,uEAAuE;IACvE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC/D;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,2CAA2C;IAC3C,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAMD,MAAM,WAAW,YAAY;IAC3B,2CAA2C;IAC3C,OAAO,CACL,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAEpC;;;OAGG;IACH,UAAU,CAAC,CACT,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,CAAC,EAAE,iBAAiB,GAC1B,cAAc,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAE3C;;;;;OAKG;IACH,GAAG,CAAC,CACF,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,gBAAgB,EACzB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB,wCAAwC;IACxC,UAAU,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7B,iDAAiD;IACjD,QAAQ,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3B,+CAA+C;IAC/C,UAAU,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B"}
+{"version":3,"file":"node-executor.d.ts","sourceRoot":"","sources":["../src/node-executor.ts"],"names":[],"mappings":"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"}

package/dist/permission-gate.d.ts

@@ -0,0 +1,152 @@
+/**
+ * The permission gate contract: the mode, the category, the decision matrix,
+ * the approval callback, and the context key a host publishes its gate under.
+ *
+ * It lives here rather than in `@nodetool-ai/agents` because the hosts that
+ * run a workflow (`@nodetool-ai/execution`, the headless job runner) sit
+ * below `agents` in the package graph and still have to set a gate on the
+ * context they build. The ladder that reads the gate, the classification of
+ * tool names, and the loops that gate through it stay in `agents`; this is
+ * only what a host needs to say "this run is headless".
+ *
+ * Design: docs/AGENTS.md § "The permission gate",
+ * packages/agents/AGENTS.md § "Where the permission gate is set".
+ */
+/**
+ * ProcessingContext variable key under which a host publishes the
+ * `PermissionGateOptions` every loop under it must gate through.
+ *
+ * The gate has to reach loops the host never constructs: an `AgentNode` a chat
+ * turn started through `run_node`, a JS script, a sub-agent several levels
+ * down. The context bag is the one channel all of them already carry, and
+ * `ProcessingContext.copy()` shallow-copies it, so a child context shares the
+ * host's gate object rather than a clone — which is what makes
+ * `set_permission_mode` mid-turn reach a node that started before it
+ * (invariant I-1).
+ *
+ * Read it with `gateFromContext` in `@nodetool-ai/agents`, never directly: a
+ * context with no gate on it is a host that forgot to set one, and the answer
+ * there is a gate that denies every call past read, not "ungated".
+ */
+export declare const PERMISSION_GATE_CONTEXT_KEY = "nodetool_permission_gate";
+/** How risky a tool is, independent of the active mode. */
+export type PermissionCategory = "read" | "write" | "execute" | "external";
+/** The user-selected permission mode for a chat turn. */
+export type PermissionMode = "plan" | "default" | "auto";
+/** What the gate decides to do with a single call before any user prompt. */
+export type PermissionDecision = "allow" | "ask" | "block";
+/** The user's answer to an approval prompt. */
+export type ApprovalDecision = "allow" | "allow_for_chat" | "deny";
+/**
+ * The matrix: `read` always runs; in `auto` everything runs; in `plan`
+ * anything actionable is blocked; in `default` actionable calls ask.
+ */
+export declare function decidePermission(mode: PermissionMode, category: PermissionCategory): PermissionDecision;
+export interface ApprovalRequest {
+    toolName: string;
+    category: PermissionCategory;
+    /** Tool arguments, with the reserved `_message` field stripped. */
+    args: Record<string, unknown>;
+    /** Resolved user-facing status (LLM `_message` or the tool's template). */
+    message: string;
+    /**
+     * What the call will do, in plain sentences, for the approval dialog to ask
+     * about. A high-risk code action supplies one (`execute_code`'s
+     * `description`); most calls have none and the dialog shows `message`.
+     */
+    description?: string;
+}
+export type RequestApproval = (request: ApprovalRequest) => Promise<ApprovalDecision>;
+/**
+ * One actionable call, as the security monitor sees it. Structurally the
+ * `PendingAction` the monitor in `@nodetool-ai/agents` evaluates; declared
+ * here so the gate carries no dependency on the monitor.
+ */
+export interface PermissionGateAction {
+    /** Tool name about to run. */
+    name: string;
+    /** Permission category of the tool. */
+    category: PermissionCategory;
+    /** Tool arguments (with the reserved `_message` field already stripped). */
+    args: Record<string, unknown>;
+    /** Recent transcript text, used to evaluate user-intent clearing of SOFT blocks. */
+    transcript?: string;
+}
+/**
+ * What the monitor answers. The ladder reads `block`, `reason`, and the two
+ * labels it prints; the monitor's own narrower unions satisfy this shape.
+ */
+export interface PermissionGateVerdict {
+    block: boolean;
+    reason: string;
+    severity: string;
+    tier: string;
+}
+/**
+ * A guest clock the gate can stop while a prompt is open. Structurally the
+ * sandbox's `SandboxClock`; declared here so the gate carries no dependency
+ * on the sandbox.
+ */
+export interface PermissionGateClock {
+    /** Stop the guest's budget until the returned function is called. */
+    suspend(): () => void;
+    /** Milliseconds suspended so far, including a suspension still open. */
+    suspendedMs(): number;
+}
+export interface PermissionGateOptions {
+    mode: PermissionMode;
+    /**
+     * Tool names the user has approved for the rest of the chat. Shared (by
+     * reference) across a thread so "Allow for this chat" sticks between turns.
+     */
+    sessionAllow: Set<string>;
+    /** Round-trips an approval prompt to the UI and resolves with the answer. */
+    requestApproval: RequestApproval;
+    /**
+     * Opt-in LLM-judge consult. When set, every actionable (non-read) tool call
+     * that the mode/approval logic would otherwise run is first vetted by the
+     * monitor; a `block` verdict stops execution with a structured error. This
+     * is a plain callback (NOT the monitor class) so the gate carries no
+     * provider/LLM dependency. Default undefined → the gate behaves exactly as
+     * before, byte-for-byte. Read-class tools are NEVER consulted, even when set.
+     */
+    securityMonitor?: (action: PermissionGateAction) => Promise<PermissionGateVerdict>;
+    /**
+     * The sandbox clock a code action runs on, when the call comes from one. The
+     * gate stops it for the length of an approval prompt or a monitor consult:
+     * that wait is the user's (or another model's), not the guest program's, and
+     * charging it to the action's wall clock kills the program that asked.
+     */
+    clock?: PermissionGateClock;
+    /**
+     * Optional accessor for the recent transcript text, forwarded into the
+     * monitor's {@link PermissionGateAction.transcript} so SOFT-block
+     * user-intent clearing has evidence to reason over. Defaults to undefined →
+     * empty transcript. Only invoked when {@link securityMonitor} is set.
+     */
+    recentTranscript?: () => string;
+}
+/**
+ * Why a headless host refuses an escalation, in one sentence naming it.
+ *
+ * Exported because two callers need the same words: the gate reports it when
+ * it denies, and a host that runs headless on purpose (the CLI behind a pipe)
+ * prints it once up front so the user is not left guessing why a later call
+ * was refused.
+ */
+export declare function headlessDenialReason(hostName: string): string;
+/**
+ * The gate for a host with nobody to ask: `auto`, denying every escalation.
+ *
+ * `decidePermission` allows read, write, execute and external outright in
+ * `auto`, so this approver is reached only by a request the ladder itself
+ * raises — a security-monitor consult, or a category that starts asking in
+ * `auto` later. Denying is the only answer a host with no user can give
+ * honestly: resolving `"allow"` would grant exactly what the escalation was
+ * raised to withhold, and never resolving would hang the run (invariant I-4).
+ *
+ * `hostName` names the caller so the refusal says which host had no one to
+ * ask, rather than only that something was refused.
+ */
+export declare function headlessGate(hostName: string): PermissionGateOptions;
+//# sourceMappingURL=permission-gate.d.ts.map

package/dist/permission-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-gate.d.ts","sourceRoot":"","sources":["../src/permission-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,2BAA2B,6BAA6B,CAAC;AAEtE,2DAA2D;AAC3D,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,UAAU,CAAC;AAE3E,yDAAyD;AACzD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;AAEzD,6EAA6E;AAC7E,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,KAAK,GAAG,OAAO,CAAC;AAE3D,+CAA+C;AAC/C,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,gBAAgB,GAAG,MAAM,CAAC;AAEnE;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,cAAc,EACpB,QAAQ,EAAE,kBAAkB,GAC3B,kBAAkB,CAWpB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,eAAe,GAAG,CAC5B,OAAO,EAAE,eAAe,KACrB,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAE/B;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,oFAAoF;IACpF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,OAAO,IAAI,MAAM,IAAI,CAAC;IACtB,wEAAwE;IACxE,WAAW,IAAI,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,cAAc,CAAC;IACrB;;;OAGG;IACH,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1B,6EAA6E;IAC7E,eAAe,EAAE,eAAe,CAAC;IACjC;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,CAChB,MAAM,EAAE,oBAAoB,KACzB,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACpC;;;;;OAKG;IACH,KAAK,CAAC,EAAE,mBAAmB,CAAC;IAC5B;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,MAAM,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAK7D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,qBAAqB,CAapE"}

package/dist/permission-gate.js

@@ -0,0 +1,87 @@
+/**
+ * The permission gate contract: the mode, the category, the decision matrix,
+ * the approval callback, and the context key a host publishes its gate under.
+ *
+ * It lives here rather than in `@nodetool-ai/agents` because the hosts that
+ * run a workflow (`@nodetool-ai/execution`, the headless job runner) sit
+ * below `agents` in the package graph and still have to set a gate on the
+ * context they build. The ladder that reads the gate, the classification of
+ * tool names, and the loops that gate through it stay in `agents`; this is
+ * only what a host needs to say "this run is headless".
+ *
+ * Design: docs/AGENTS.md § "The permission gate",
+ * packages/agents/AGENTS.md § "Where the permission gate is set".
+ */
+/**
+ * ProcessingContext variable key under which a host publishes the
+ * `PermissionGateOptions` every loop under it must gate through.
+ *
+ * The gate has to reach loops the host never constructs: an `AgentNode` a chat
+ * turn started through `run_node`, a JS script, a sub-agent several levels
+ * down. The context bag is the one channel all of them already carry, and
+ * `ProcessingContext.copy()` shallow-copies it, so a child context shares the
+ * host's gate object rather than a clone — which is what makes
+ * `set_permission_mode` mid-turn reach a node that started before it
+ * (invariant I-1).
+ *
+ * Read it with `gateFromContext` in `@nodetool-ai/agents`, never directly: a
+ * context with no gate on it is a host that forgot to set one, and the answer
+ * there is a gate that denies every call past read, not "ungated".
+ */
+export const PERMISSION_GATE_CONTEXT_KEY = "nodetool_permission_gate";
+/**
+ * The matrix: `read` always runs; in `auto` everything runs; in `plan`
+ * anything actionable is blocked; in `default` actionable calls ask.
+ */
+export function decidePermission(mode, category) {
+    if (category === "read") {
+        return "allow";
+    }
+    if (mode === "auto") {
+        return "allow";
+    }
+    if (mode === "plan") {
+        return "block";
+    }
+    return "ask";
+}
+/**
+ * Why a headless host refuses an escalation, in one sentence naming it.
+ *
+ * Exported because two callers need the same words: the gate reports it when
+ * it denies, and a host that runs headless on purpose (the CLI behind a pipe)
+ * prints it once up front so the user is not left guessing why a later call
+ * was refused.
+ */
+export function headlessDenialReason(hostName) {
+    return (`${hostName} runs without a user to ask, so calls the permission ladder ` +
+        `escalates are denied.`);
+}
+/**
+ * The gate for a host with nobody to ask: `auto`, denying every escalation.
+ *
+ * `decidePermission` allows read, write, execute and external outright in
+ * `auto`, so this approver is reached only by a request the ladder itself
+ * raises — a security-monitor consult, or a category that starts asking in
+ * `auto` later. Denying is the only answer a host with no user can give
+ * honestly: resolving `"allow"` would grant exactly what the escalation was
+ * raised to withhold, and never resolving would hang the run (invariant I-4).
+ *
+ * `hostName` names the caller so the refusal says which host had no one to
+ * ask, rather than only that something was refused.
+ */
+export function headlessGate(hostName) {
+    const reason = headlessDenialReason(hostName);
+    const headlessDeny = async (request) => {
+        // Loud on the refusal (I-4): a denial nobody can see reads as a tool that
+        // silently did nothing.
+        console.warn(`Denied \`${request.toolName}\` without asking: ${reason}`);
+        return "deny";
+    };
+    return {
+        mode: "auto",
+        sessionAllow: new Set(),
+        requestApproval: headlessDeny
+    };
+}
+//# sourceMappingURL=permission-gate.js.map

package/dist/permission-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-gate.js","sourceRoot":"","sources":["../src/permission-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,0BAA0B,CAAC;AActE;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,IAAoB,EACpB,QAA4B;IAE5B,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;QACxB,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAgGD;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAgB;IACnD,OAAO,CACL,GAAG,QAAQ,8DAA8D;QACzE,uBAAuB,CACxB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,QAAgB;IAC3C,MAAM,MAAM,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IAC9C,MAAM,YAAY,GAAoB,KAAK,EAAE,OAAO,EAAE,EAAE;QACtD,0EAA0E;QAC1E,wBAAwB;QACxB,OAAO,CAAC,IAAI,CAAC,YAAY,OAAO,CAAC,QAAQ,sBAAsB,MAAM,EAAE,CAAC,CAAC;QACzE,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;IACF,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,YAAY,EAAE,IAAI,GAAG,EAAU;QAC/B,eAAe,EAAE,YAAY;KAC9B,CAAC;AACJ,CAAC"}

package/dist/prefixed-storage-adapter.d.ts

@@ -0,0 +1,33 @@
+import { type StorageAdapter, type StorageListResult, type StorageStat } from "./context.js";
+/**
+ * A `StorageAdapter` that carves a key prefix out of another one.
+ *
+ * Cloud deployments keep one bucket. Giving each user a workspace inside it
+ * means their keys have to be namespaced, and the namespacing has to be
+ * invisible to whatever holds the adapter — a caller that stores `notes.md`
+ * must read it back as `notes.md`, not as `workspaces/u1/notes.md`. Every key
+ * going in gains the prefix and every key coming out loses it again.
+ *
+ * The prefix is applied to *keys*, never to URIs: a URI is opaque and already
+ * carries the full key, so it passes through untouched.
+ */
+export declare class PrefixedStorageAdapter implements StorageAdapter {
+    private readonly inner;
+    /** Normalized prefix with no trailing slash. */
+    readonly prefix: string;
+    constructor(inner: StorageAdapter, prefix: string);
+    private scope;
+    /** Strip the prefix from a key the inner adapter reported. */
+    private unscope;
+    store(key: string, data: Uint8Array, contentType?: string): Promise<string>;
+    retrieve(uri: string): Promise<Uint8Array | null>;
+    exists(uri: string): Promise<boolean>;
+    uriForKey(key: string): string;
+    list(prefix: string, opts?: {
+        delimiter?: string;
+    }): Promise<StorageListResult>;
+    delete(uri: string): Promise<boolean>;
+    stat(uri: string): Promise<StorageStat | null>;
+    localPath(uri: string): Promise<string | null>;
+}
+//# sourceMappingURL=prefixed-storage-adapter.d.ts.map

package/dist/prefixed-storage-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefixed-storage-adapter.d.ts","sourceRoot":"","sources":["../src/prefixed-storage-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EACjB,MAAM,cAAc,CAAC;AAEtB;;;;;;;;;;;GAWG;AACH,qBAAa,sBAAuB,YAAW,cAAc;IAKzD,OAAO,CAAC,QAAQ,CAAC,KAAK;IAJxB,gDAAgD;IAChD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,YACmB,KAAK,EAAE,cAAc,EACtC,MAAM,EAAE,MAAM,EAGf;IAED,OAAO,CAAC,KAAK;IAIb,8DAA8D;IAC9D,OAAO,CAAC,OAAO;IAKf,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAE1E;IAED,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAEhD;IAED,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAEpC;IAED,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7B;IAEK,IAAI,CACR,MAAM,EAAE,MAAM,EACd,IAAI,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GAChC,OAAO,CAAC,iBAAiB,CAAC,CAe5B;IAED,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAEpC;IAEK,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAKnD;IAED,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAE7C;CACF"}