@entrinsik/vite-plugin-informer 2.11.0 → 2.12.0

package/src/dev-channels.js

@@ -18,9 +18,10 @@ import { EventEmitter } from 'node:events';
 // plus the subscribe-side wildcard `rooms/*` (an ordinary name whose LAST
 // segment is `*`; `*` alone is not a name). Everything after `@user/` is one
 // username, verbatim — the server compares the whole remainder to the
-// socket's own — so `@user/*` is refused rather than read as a wildcard.
+// socket's own — so `@user/*` is a valid name for a user called `*`, refused
+// on subscribe as someone else's channel rather than read as a wildcard.
 export const USER_CHANNEL_PREFIX = '@user/';
-export const CHANNEL_NAME = /^(@user\/(?!\*$)\S+|[\w.-]+(\/[\w.-]+)*(\/\*)?)$/;
+export const CHANNEL_NAME = /^(@user\/\S+|[\w.-]+(\/[\w.-]+)*(\/\*)?)$/;
 export const CHANNEL_NAME_MAX_LENGTH = 128;
 // `created`, `order_created`
 export const EVENT_NAME = /^[\w.-]+$/;
@@ -31,8 +32,10 @@ export const EVENT_NAME_MAX_LENGTH = 64;
 export const RESERVED_EVENTS = Object.freeze(['error', 'connected']);
 // config-factory.js app.channels.maxFrameBytes default
 export const MAX_FRAME_BYTES = 65536;
-// Frames kept per channel for `replay(channel, since)`.
+// Frames kept per channel for `replay(channel, since)`, and for how long after
+// the channel's last write (config-factory.js app.channels.replay defaults).
 export const REPLAY_FRAMES = 50;
+export const REPLAY_TTL_MS = 60000;
 // deploy.js CHANNELS_SCHEMA description cap
 const DESCRIPTION_MAX_LENGTH = 500;
 
@@ -59,9 +62,9 @@ export function isChannelName(name) {
     return typeof name === 'string' && name.length <= CHANNEL_NAME_MAX_LENGTH && CHANNEL_NAME.test(name);
 }
 
-/** `rooms/*`: a subscribe-only name covering every channel one level under `rooms/`. */
+/** `rooms/*`: a subscribe-only name covering every channel under `rooms/`. Any trailing `/*` counts, as on the server (`@user/*` too, so nothing can broadcast to it). */
 export function isWildcardName(name) {
-    return isChannelName(name) && !name.startsWith(USER_CHANNEL_PREFIX) && name.endsWith('/*');
+    return typeof name === 'string' && name.endsWith('/*');
 }
 
 export function isEventName(name) {
@@ -156,23 +159,32 @@ export function validateChannels(block) {
  * @param {string} [opts.tenant] - frame tenant (the plugin knows none; defaults to 'dev')
  * @param {string} [opts.appId] - the dev app id (the mocked `report.id`)
  * @param {string} [opts.logPrefix] - console prefix
+ * @param {Function} [opts.now] - clock in ms (tests)
  * @returns {{ emitter: EventEmitter, broadcast: Function, relay: Function, replay: Function, tenant: string, appId: string }}
  */
-export function createDevChannels({ tenant = DEV_TENANT, appId = 'dev-local', logPrefix = '[app-channel]' } = {}) {
+export function createDevChannels({ tenant = DEV_TENANT, appId = 'dev-local', logPrefix = '[app-channel]', now = Date.now } = {}) {
     const emitter = new EventEmitter();
-    // channel name → { seq, frames }: the monotonic counter and the last
-    // REPLAY_FRAMES frames, oldest first.
+    // channel name → { seq, frames, writtenAt }: the monotonic counter and the
+    // last REPLAY_FRAMES frames, oldest first, with the time of the last write.
     const buffers = new Map();
 
     function bufferFor(channel) {
         let buffer = buffers.get(channel);
         if (!buffer) {
-            buffer = { seq: 0, frames: [] };
+            buffer = { seq: 0, frames: [], writtenAt: 0 };
             buffers.set(channel, buffer);
         }
         return buffer;
     }
 
+    // The server's PEXPIRE on the buffer key: the whole buffer goes
+    // REPLAY_TTL_MS after its last write, while the seq counter stays (it has
+    // its own, far longer life).
+    function liveFrames(buffer) {
+        if (buffer.frames.length && now() - buffer.writtenAt >= REPLAY_TTL_MS) buffer.frames = [];
+        return buffer.frames;
+    }
+
     // Validate and publish one §1.1 frame. Synchronous so the manifest relay
     // can run inside a synchronous emit(); throws the server's error codes.
     // `replay: false` keeps the frame out of the channel's replay buffer (it
@@ -196,10 +208,13 @@ export function createDevChannels({ tenant = DEV_TENANT, appId = 'dev-local', lo
 
         const buffer = bufferFor(channel);
         buffer.seq += 1;
-        const frame = { tenant, appId, channel, event, payload: message, seq: buffer.seq, at: Date.now() };
+        const at = now();
+        const frame = { tenant, appId, channel, event, payload: message, seq: buffer.seq, at };
         if (replay !== false) {
-            buffer.frames.push(frame);
-            if (buffer.frames.length > REPLAY_FRAMES) buffer.frames.shift();
+            const frames = liveFrames(buffer);
+            frames.push(frame);
+            if (frames.length > REPLAY_FRAMES) frames.shift();
+            buffer.writtenAt = at;
         }
         emitter.emit(BROADCAST_EVENT, frame);
         return frame;
@@ -241,7 +256,9 @@ export function createDevChannels({ tenant = DEV_TENANT, appId = 'dev-local', lo
      * first, with the smallest seq still buffered (null when nothing is) and
      * the channel's current seq (0 before its first frame), so the page can
      * tell a gap from a quiet channel. Dev counters never restart, so
-     * `current >= since` for any seq the page has seen.
+     * `current >= since` for any seq the page has seen. An expired buffer
+     * answers no frames and no oldest with the counter intact, which a page
+     * that saw an earlier seq reads as a gap.
      *
      * @param {string} channel
      * @param {number} [since] - the last seq the page has seen
@@ -250,10 +267,11 @@ export function createDevChannels({ tenant = DEV_TENANT, appId = 'dev-local', lo
     function replay(channel, since = 0) {
         const buffer = buffers.get(channel);
         if (!buffer) return { frames: [], oldest: null, current: 0 };
+        const frames = liveFrames(buffer);
         const from = Number(since) || 0;
         return {
-            frames: buffer.frames.filter(f => f.seq > from),
-            oldest: buffer.frames.length ? buffer.frames[0].seq : null,
+            frames: frames.filter(f => f.seq > from),
+            oldest: frames.length ? frames[0].seq : null,
             current: buffer.seq
         };
     }

package/src/dev-dependencies.js

@@ -1,3 +1,4 @@
+import { isStreamRef } from './dev-streams.js';
 import { readFile, access } from 'node:fs/promises';
 import { join } from 'node:path';
 import crypto from 'node:crypto';
@@ -387,7 +388,14 @@ export function resolveAppBinding(binding) {
  * @returns {Object} An object keyed by dependency name, values are typed
  *   proxies with methods matching the target's production method surface.
  */
-export function buildDevContext({ deps, apiFetch, devBindings = {}, appFetch = null }) {
+// The integration request route carries a base64 body of at most 50 MB
+// (integration/routes/request.js REQUEST_MAX_BYTES), so a staged stream the dev
+// proxy forwards through it can be at most this many raw bytes — a little less
+// in practice, since the envelope also carries url, headers and params. Pinned
+// to the server constant by test/streams-parity.test.js.
+export const DEV_FORWARD_MAX_BYTES = Math.floor(52428800 * 3 / 4);
+
+export function buildDevContext({ deps, apiFetch, devBindings = {}, appFetch = null, forwarding = null }) {
     const context = {};
     for (const [name, decl] of Object.entries(deps || {})) {
         if (!decl || typeof decl !== 'object') continue;
@@ -417,7 +425,7 @@ export function buildDevContext({ deps, apiFetch, devBindings = {}, appFetch = n
             : null;
 
         context[name] = targetId
-            ? makeDevProxy({ name, target, targetId, apiFetch })
+            ? makeDevProxy({ name, target, targetId, apiFetch, forwarding })
             : makeUnboundDevProxy({ name, target });
     }
     return context;
@@ -518,7 +526,7 @@ function makeAppDevProxy({ name, binding, appFetch, kind = 'app' }) {
     };
 }
 
-function makeDevProxy({ name, target, targetId, apiFetch }) {
+function makeDevProxy({ name, target, targetId, apiFetch, forwarding = null }) {
     switch (target) {
         case 'dataset':
             return {
@@ -544,7 +552,75 @@ function makeDevProxy({ name, target, targetId, apiFetch }) {
         case 'integration':
             return {
                 async request(payload) {
-                    return await devCall(apiFetch, 'POST', `integrations/${targetId}/request`, payload || {}, name, 'integration');
+                    const { data, form, into, ...rest } = payload || {};
+                    const wantsBody = isStreamRef(data, 'upload');
+                    const wantsForm = Boolean(form) && typeof form === 'object' && !Array.isArray(form);
+                    const wantsInto = into !== undefined && into !== null;
+                    // Ahead of the plain-call shortcut below: on its own a
+                    // download handle leaves every flag false, and falling
+                    // through would JSON-POST the handle to the third party as
+                    // the request body. Prod refuses it (app-stream-forwarding.js).
+                    if (isStreamRef(data, 'download')) {
+                        throw dependencyError('request(): only an upload handle can be sent as the body; a download is what a route produces, not what it forwards', 400, { dependencyName: name, resourceType: 'integration' });
+                    }
+                    if (!wantsBody && !wantsForm && !wantsInto) {
+                        return await devCall(apiFetch, 'POST', `integrations/${targetId}/request`, payload || {}, name, 'integration');
+                    }
+                    // Staged streams as bodies (I5-13030). Prod streams them
+                    // through the proxy; dev rides the route's base64 envelope
+                    // with the same request shape, so anything an author sees
+                    // here, deployed code sees too — except the envelope's cap.
+                    if (!forwarding) {
+                        throw dependencyError(`Dependency "${name}" (integration): staged streams are unavailable in this context`, 400, { dependencyName: name, resourceType: 'integration' });
+                    }
+                    if (wantsBody && wantsForm) {
+                        throw dependencyError('request(): use either `data` or `form` for the body, not both', 400, { dependencyName: name, resourceType: 'integration' });
+                    }
+                    // A `data` that is not a stream handle is the caller's own
+                    // body: keep it. Mirrors app-stream-forwarding.js — without
+                    // it, request({ data: { q }, into: dl }) sends nothing.
+                    let body = (!wantsBody && !wantsForm && data !== undefined) ? { ...rest, data } : rest;
+                    if (wantsForm && data !== undefined) {
+                        throw dependencyError('request(): use either `data` or `form` for the body, not both', 400, { dependencyName: name, resourceType: 'integration' });
+                    }
+                    if (wantsBody) {
+                        const upload = forwarding.body(data);
+                        assertForwardable(name, upload.size);
+                        // content-length describes bytes only this side counted;
+                        // content-type stays the caller's to relabel, as in prod.
+                        assertStreamOwnedHeaders(rest.headers, { 'content-length': upload.size }, name);
+                        body = { ...rest, data: upload.bytes.toString('base64'), encoding: 'base64', headers: withDefaultHeader(rest.headers, 'content-type', upload.contentType) };
+                    } else if (wantsForm) {
+                        const { bytes, contentType } = multipart(form, forwarding, name);
+                        assertForwardable(name, bytes.length);
+                        // The boundary is generated in multipart() and nowhere
+                        // else, so content-type is the stream's here; a caller's
+                        // `multipart/form-data` would drop it.
+                        assertStreamOwnedHeaders(rest.headers, { 'content-type': contentType, 'content-length': bytes.length }, name);
+                        body = { ...rest, data: bytes.toString('base64'), encoding: 'base64', headers: withDefaultHeader(rest.headers, 'content-type', contentType) };
+                    }
+                    if (!wantsInto) {
+                        return await devCall(apiFetch, 'POST', `integrations/${targetId}/request`, body, name, 'integration');
+                    }
+                    // `into` is claimed before the call, as prod does, so a bad
+                    // target fails without an upstream round trip — and is given
+                    // back on every path that does not deliver a body.
+                    const receiver = forwarding.receiver(into, rest.url);
+                    let answer;
+                    try {
+                        answer = await apiFetch(`integrations/${targetId}/request`, { method: 'POST', body, raw: true });
+                    } catch (err) {
+                        receiver.release();
+                        throw err;
+                    }
+                    const { status, bytes, headers, body: parsed } = answer;
+                    // Prod gates the fill on < 300 (request.js); a 3xx that axios
+                    // did not follow must not be sealed as the file here either.
+                    if (status >= 300) {
+                        receiver.release();
+                        throw dependencyCallError(name, 'integration', status, parsed);
+                    }
+                    return receiver.fill(bytes, headers);
                 }
             };
         default:
@@ -634,6 +710,66 @@ function isBinaryContentType(contentType) {
     return Boolean(ct) && !ct.startsWith('text/') && !ct.includes('json') && !ct.includes('event-stream');
 }
 
+function assertForwardable(name, size) {
+    if (size > DEV_FORWARD_MAX_BYTES) {
+        throw new Error(
+            `Dependency "${name}" (integration): the dev proxy forwards a staged stream through the request route's base64 envelope, which holds at most ${DEV_FORWARD_MAX_BYTES} bytes (this one is ${size}). A deployed app streams it without the cap — test files this size against a deployment.`
+        );
+    }
+}
+
+/**
+ * Refuse a caller-declared header that describes the staged stream, the way
+ * prod's applyStreamHeaders does (modules/integration/routes/request.js).
+ *
+ * Dev sends the body as a base64 envelope and never ships these names, so
+ * without the refusal an author learns a contract that 400s on deploy — or
+ * worse, ships a boundary-less multipart body no upstream can parse.
+ */
+function assertStreamOwnedHeaders(headers, owned, name) {
+    for (const [ownedName, value] of Object.entries(owned)) {
+        const declared = Object.keys(headers || {}).find(k => k.toLowerCase() === ownedName);
+        if (declared && String(headers[declared]) !== String(value)) {
+            throw dependencyError(
+                `request(): \`${declared}\` describes the staged stream and cannot be set by the caller (you sent "${headers[declared]}", the stream is "${value}")`,
+                400, { dependencyName: name, resourceType: 'integration' }
+            );
+        }
+    }
+}
+
+function withDefaultHeader(headers, name, value) {
+    const out = { ...(headers || {}) };
+    if (!Object.keys(out).some(k => k.toLowerCase() === name)) out[name] = value;
+    return out;
+}
+
+/** A multipart/form-data body built here — the plugin ships without form-data. */
+function multipart(form, forwarding, name) {
+    const boundary = `----InformerDevForm${Math.random().toString(16).slice(2)}${Date.now().toString(16)}`;
+    const parts = [];
+    for (const [field, value] of Object.entries(form)) {
+        if (value === undefined || value === null) continue;
+        if (isStreamRef(value, 'download')) {
+            throw dependencyError(`request(): form field "${field}" is a download handle; only uploads can be sent`, 400, { dependencyName: name, resourceType: 'integration' });
+        }
+        if (isStreamRef(value, 'upload')) {
+            const upload = forwarding.body(value);
+            // filenameSchema permits a double quote, which would close the
+            // disposition early and let a filename inject its own part headers.
+            // form-data escapes this for us in prod; here it is hand-rolled.
+            const filename = String(upload.filename || 'upload').replace(/["\r\n]/g, '_');
+            parts.push(Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="${field}"; filename="${filename}"\r\nContent-Type: ${upload.contentType}\r\n\r\n`), upload.bytes, Buffer.from('\r\n'));
+        } else if (typeof value === 'object') {
+            parts.push(Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="${field}"\r\nContent-Type: application/json\r\n\r\n${JSON.stringify(value)}\r\n`));
+        } else {
+            parts.push(Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="${field}"\r\n\r\n${String(value)}\r\n`));
+        }
+    }
+    parts.push(Buffer.from(`--${boundary}--\r\n`));
+    return { bytes: Buffer.concat(parts), contentType: `multipart/form-data; boundary=${boundary}` };
+}
+
 async function devCall(apiFetch, method, path, body, depName, resourceType) {
     const opts = { method };
     if (body !== null && body !== undefined) opts.body = body;

package/src/dev-platform.js

@@ -3,13 +3,14 @@
  * the server injects on `window.__INFORMER__.platform` and on the server
  * handler / tool bag: the Informer build version and the capability flags.
  *
- * Every capability the dev server mirrors is on. `embeddings` is off: the
- * pump and query-time `embed()` need a real Informer, so an app that
- * feature-detects on it sees locally exactly what it sees on an install
- * without the feature. `version` is `'dev'` (not semver) so a floor check
- * treats the dev mirror as "unknown" rather than as any particular release.
- * `originMode` is on: the dev server behaves like an app served from its own
- * origin, where live channels work.
+ * Every capability the dev server mirrors is on. `embeddings` is off by
+ * default: the pump needs a real Informer, so an app that feature-detects on
+ * it sees locally exactly what it sees on an install without the feature.
+ * Turning it on binds query-time `embed()` to a deployed app's `_embed` route
+ * (see createDevEmbed); the pump itself is still not mirrored. `version` is
+ * `'dev'` (not semver) so a floor check treats the dev mirror as "unknown"
+ * rather than as any particular release. `originMode` is on: the dev server
+ * behaves like an app served from its own origin, where live channels work.
  *
  * Override any of it per project with `informer({ mock: { platform: {…} } })`.
  */
@@ -42,3 +43,75 @@ export function devPlatform(overrides = {}) {
         capabilities: { ...DEV_CAPABILITIES, ...capabilities }
     };
 }
+
+/**
+ * Whatever the response carries by way of an explanation.
+ *
+ * fetchAs returns a parsed JSON body when it can and the raw text when it
+ * cannot (an auth-bounce HTML page, a proxy error page). Boom answers put the
+ * sentence on `message`; fetchAs's own invalid-path synthetic uses `error`.
+ * Reading only `message` drops both of the others and leaves the tautology
+ * `failed (502): HTTP 502` with the text that explained the failure thrown
+ * away.
+ */
+function failureReason(body, status) {
+    if (typeof body === 'string') return body.trim().slice(0, 200) || `HTTP ${status}`;
+    return (body && (body.message || body.error)) || `HTTP ${status}`;
+}
+
+/**
+ * The dev bag's `embed(name, text)`, shared by the server-routes and agent
+ * mirrors so the two cannot drift.
+ *
+ * Off by default: the same written explanation a real install gives an app
+ * type without the capability, so the dev failure reads as the deployed
+ * lesson instead of a bare "embed is not a function".
+ *
+ * Opted in — `informer({ mock: { platform: { capabilities: { embeddings: true } } } })`
+ * — it posts to the deployed app's `_embed` route on the configured server.
+ * That route runs the same host function a deployed handler's `embed()`
+ * runs, so the vector, the revision and the billing are the deployed ones.
+ * The corpus is not: `query()` still goes to the dev workspace datasource,
+ * which the pump never writes to, so a search route compares a deployed
+ * vector against local rows.
+ *
+ * It addresses the app by package.json `informer.id`. `informer-init`
+ * generates that id locally and the first deploy creates the app under it, so
+ * for a scaffolded project it is always set and the question is whether THIS
+ * server has ever had a deploy of it — a 404, answered below with what to do
+ * about it.
+ */
+export function createDevEmbed({ platform, apiFetch, appId }) {
+    if (!(platform && platform.capabilities && platform.capabilities.embeddings)) {
+        return async () => {
+            throw new Error('embed() is not available in the dev mirror: the embeddings capability needs a real Informer (platform.capabilities.embeddings is false)');
+        };
+    }
+    return async (name, text) => {
+        if (!appId) {
+            throw new Error('embed() in dev needs an app id to address: set informer.id in package.json (informer-init writes it) and deploy once');
+        }
+        const { status, body } = await apiFetch(`apps/${appId}/embeddings/${encodeURIComponent(String(name))}/_embed`, {
+            method: 'POST',
+            body: { text }
+        });
+
+        if (status === 404) {
+            throw new Error(`embed('${name}') failed (404): the configured server has no app ${appId} with an embeddings use case "${name}". Deploy this project there (npm run deploy) and declare the use case in embeddings/${name}.js.`);
+        }
+        if (status < 200 || status >= 300) {
+            throw new Error(`embed('${name}') failed (${status}): ${failureReason(body, status)}`);
+        }
+        // A 2xx is not yet an answer. globalThis.fetch FOLLOWS redirects, so
+        // an expired INFORMER_API_KEY or an SSO proxy in front of the server
+        // answers 200 with a sign-in page, and a 204 answers nothing at all.
+        // Returned as-is, `result.embedding` is undefined and the failure
+        // surfaces much later as a Postgres parameter-type error inside the
+        // app's own SQL — sending the developer to debug their query for what
+        // is an auth failure.
+        if (!body || !Array.isArray(body.embedding)) {
+            throw new Error(`embed('${name}') got ${status} but no embedding vector — the response did not come from the _embed route. An expired INFORMER_API_KEY or a sign-in proxy in front of the server both answer 200 with a page. Response: ${failureReason(body, status)}`);
+        }
+        return body;
+    };
+}

package/src/dev-streams.js

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { extname } from 'node:path';
+import { extname, basename } from 'node:path';
 
 /**
  * Dev-mode app streams (I5-12979) — the local stand-in for the production
@@ -151,6 +151,47 @@ export function createStreamStore(limits = LIMITS) {
     return { create, get, bytes, remove, reserve, seal, sweep, touch, items, limits };
 }
 
+/**
+ * The staged streams of one type, oldest first (I5-13030). Dev has a single
+ * user, so the store IS their ledger — no per-user filter to apply.
+ */
+export function listStreams(store, type) {
+    store.sweep();
+    return [...store.items.values()].filter(item => item.type === type).sort((a, b) => a.createdAt - b.createdAt);
+}
+
+/** Where the dev origin serves a download: the same shape the bag's download.url takes. */
+export function downloadUrl(item, base = '') {
+    return `${base}/_downloads/${encodeURIComponent(item.id)}${item.filename ? `/${encodeURIComponent(item.filename)}` : ''}`;
+}
+
+/**
+ * MIRRORED from modules/app/lib/app-stream-forwarding.js (I5-13030) and pinned
+ * by the parity test: how a filled stream is named when the guest did not
+ * name it — the upstream's Content-Disposition, else the request path.
+ */
+export function filenameFromDisposition(header) {
+    if (typeof header !== 'string') return null;
+    const utf8 = /filename\*\s*=\s*(?:UTF-8|utf-8)''([^;]+)/.exec(header);
+    if (utf8) {
+        try { return decodeURIComponent(utf8[1].trim()); } catch { /* fall through to the plain form */ }
+    }
+    const plain = /filename\s*=\s*"?([^";]+)"?/.exec(header);
+    return plain ? plain[1].trim() : null;
+}
+
+export function filenameFor(headers, url) {
+    const named = filenameFromDisposition(headers && headers['content-disposition']);
+    if (named) return basename(named);
+    if (typeof url === 'string') {
+        try {
+            const last = basename(new URL(url, 'http://upstream.invalid').pathname);
+            if (last && last !== '/') return last;
+        } catch { /* not a URL we can name a file after */ }
+    }
+    return 'download';
+}
+
 /** Guest-facing handle: never the store item itself. */
 export function toHandle(item, extra = {}) {
     return {
@@ -402,35 +443,38 @@ export function createStreamServices({ store, query, base = '' }) {
         return { rowCount };
     }
 
+    /** A live upload handle — what uploads.get() and a filled `into: 'upload'` both hand out. */
+    function uploadHandle(item) {
+        return {
+            ...toHandle(item),
+            text: async (encoding) => {
+                if (encoding !== undefined && encoding !== null && !Buffer.isEncoding(encoding)) throw httpError(422, `Unknown text encoding "${encoding}"`);
+                return inline(item).toString(encoding || 'utf8');
+            },
+            json: async () => {
+                const text = inline(item).toString('utf8');
+                try {
+                    return JSON.parse(text);
+                } catch (err) {
+                    throw httpError(422, `Upload is not valid JSON: ${err.message}`);
+                }
+            },
+            base64: async () => inline(item).toString('base64'),
+            extractText: async () => { throw httpError(501, 'upload.extractText() is not available in dev — the platform text extractor runs on the Informer server; test it against a deployed app'); },
+            copyInto: async (table, opts) => await copyInto(item, table, opts || {}),
+            discard: async () => { store.remove(item.id); return true; }
+        };
+    }
+
     const uploads = {
         async get(id) {
-            const item = ownedUpload(id);
-            return {
-                ...toHandle(item),
-                text: async (encoding) => {
-                    if (encoding !== undefined && encoding !== null && !Buffer.isEncoding(encoding)) throw httpError(422, `Unknown text encoding "${encoding}"`);
-                    return inline(item).toString(encoding || 'utf8');
-                },
-                json: async () => {
-                    const text = inline(item).toString('utf8');
-                    try {
-                        return JSON.parse(text);
-                    } catch (err) {
-                        throw httpError(422, `Upload is not valid JSON: ${err.message}`);
-                    }
-                },
-                base64: async () => inline(item).toString('base64'),
-                extractText: async () => { throw httpError(501, 'upload.extractText() is not available in dev — the platform text extractor runs on the Informer server; test it against a deployed app'); },
-                copyInto: async (table, opts) => await copyInto(item, table, opts || {}),
-                discard: async () => { store.remove(item.id); return true; }
-            };
+            return uploadHandle(ownedUpload(id));
         }
     };
 
     function downloadHandle(item) {
-        const url = `${base}/_downloads/${encodeURIComponent(item.id)}${item.filename ? `/${encodeURIComponent(item.filename)}` : ''}`;
         const handle = {
-            ...toHandle(item, { url }),
+            ...toHandle(item, { url: downloadUrl(item, base) }),
             async write(chunk) {
                 writableDownload(item.id);
                 const buf = toBytes(chunk);
@@ -504,7 +548,93 @@ export function createStreamServices({ store, query, base = '' }) {
         }
     }
 
-    return { uploads, downloads, resolveQueryParams, endDownload, finalize };
+    /**
+     * Forwarding to an integration (I5-13030). Prod streams the bytes between
+     * the staging store and the upstream; the dev proxy reaches the real
+     * request route over HTTP with a JSON body, so here the bytes ride that
+     * route's base64 envelope instead — the same semantics, under the
+     * envelope's own cap (dev-dependencies.js names the gap when a file is
+     * over it). What the store does is identical: an outbound handle is read,
+     * an `into` target is claimed before the call and filled after it.
+     */
+    const forwarding = {
+        /** The bytes behind an owned, sealed upload reference, with what describes them. */
+        body(ref) {
+            const item = ownedUpload(ref.id);
+            return { bytes: store.bytes(item), contentType: item.contentType || 'application/octet-stream', filename: item.filename, size: item.size };
+        },
+        /**
+         * Claim an `into` target now — a download the guest created (unsealed,
+         * unwritten) or 'upload' for a fresh one — and return fill(), which
+         * lands the upstream body and seals it. Over the byte cap, fill() fails
+         * 413 and leaves a download empty and unsealed, a fresh upload gone.
+         */
+        receiver(target, url) {
+            if (target === 'upload') {
+                store.reserve(limits.maxUploadBytes);
+                const item = store.create('upload', { filename: null, contentType: null, size: 0, chunks: 0, reserved: limits.maxUploadBytes });
+                let settled = false;
+                return {
+                    // Prod's appStream.release: the upstream delivered no body,
+                    // so give the claim back rather than leaving an upload
+                    // nobody holds a handle to until the TTL.
+                    release() {
+                        if (settled) return;
+                        settled = true;
+                        store.remove(item.id);
+                    },
+                    fill(bytes, headers = {}) {
+                        settled = true;
+                        if (bytes.length > limits.maxUploadBytes) {
+                            store.remove(item.id);
+                            throw httpError(413, `The upstream body exceeds the ${limits.maxUploadBytes} byte limit`, { maxUploadBytes: limits.maxUploadBytes });
+                        }
+                        item.contentType = (headers['content-type'] || 'application/octet-stream').split(';')[0].trim();
+                        item.filename = filenameFor(headers, url);
+                        // An `into` fill is the append producer, which never sets
+                        // a chunk size — prod reports null, and so must the
+                        // listing below, not just the handle returned here.
+                        item.chunkSize = null;
+                        item.chunks = 1;
+                        item.chunkData.set(1, Buffer.from(bytes));
+                        item.size = bytes.length;
+                        item.complete = true;
+                        store.seal(item);
+                        // The same extra KEYS prod's handle carries for a filled
+                        // upload. Dev is one in-memory buffer, so chunks is always
+                        // 1 where prod reports the real append-producer count.
+                        return { ...uploadHandle(item), complete: true, chunks: 1, chunkSize: null };
+                    }
+                };
+            }
+            if (isStreamRef(target, 'download')) {
+                const item = writableDownload(target.id);
+                if (item.parts.length) throw httpError(409, 'Download already has bytes; `into` fills a download from empty and seals it');
+                return {
+                    // The guest still owns this one, so there is nothing to
+                    // reclaim — it stays empty and unsealed, as prod leaves it.
+                    release() {},
+                    fill(bytes, headers = {}) {
+                        if (bytes.length > limits.maxUploadBytes) {
+                            item.parts = [];
+                            item.size = 0;
+                            throw httpError(413, `The upstream body exceeds the ${limits.maxUploadBytes} byte limit`, { maxUploadBytes: limits.maxUploadBytes });
+                        }
+                        if (!item.contentType) item.contentType = (headers['content-type'] || 'application/octet-stream').split(';')[0].trim();
+                        if (!item.filename) item.filename = filenameFor(headers, url);
+                        item.parts = [Buffer.from(bytes)];
+                        item.size = bytes.length;
+                        pending.delete(item.id);
+                        store.seal(item);
+                        return { ...downloadHandle(item), complete: true };
+                    }
+                };
+            }
+            throw httpError(400, `request(): \`into\` must be a download handle or 'upload'`);
+        }
+    };
+
+    return { uploads, downloads, resolveQueryParams, endDownload, finalize, forwarding };
 }
 
 // What a guest hands write(): a string or bytes. Anything else is a 422 in
@@ -591,7 +721,7 @@ async function readBody(req) {
 
 function uploadSummary(item) {
     const { received, missing } = missingChunks(item);
-    return toHandle(item, { chunkSize: item.chunkSize, chunks: item.chunks, complete: item.complete, received, missing });
+    return toHandle(item, { chunkSize: Number(item.chunkSize) || null, chunks: item.chunks, complete: item.complete, received, missing });
 }
 
 /**
@@ -612,6 +742,11 @@ export function createUploadsMiddleware(store) {
                 res.setHeader('Location', `/_uploads/${item.id}`);
                 return sendJson(res, 201, uploadSummary(item));
             }
+            // GET /_uploads — what is staged (I5-13030). Dev has one user, so
+            // the store's uploads are all theirs, oldest first like prod.
+            if (parts.length === 0 && method === 'GET') {
+                return sendJson(res, 200, listStreams(store, 'upload').map(item => toHandle(item, { chunkSize: Number(item.chunkSize) || null, chunks: item.chunks, complete: item.complete })));
+            }
             if (parts.length === 0) return next();
 
             const item = store.get('upload', parts[0]);
@@ -639,14 +774,28 @@ export function createUploadsMiddleware(store) {
     };
 }
 
-/** Connect middleware for GET /_downloads/{id}/{filename?}?keep&inline. */
+/**
+ * Connect middleware for GET /_downloads/{id}/{filename?}?keep&inline, plus
+ * (I5-13030) GET /_downloads to list what is staged and DELETE /_downloads/{id}
+ * to drop one unserved.
+ */
 export function createDownloadsMiddleware(store) {
     return function downloadsMiddleware(req, res, next) {
         try {
-            if (req.method.toUpperCase() !== 'GET') return next();
+            const method = req.method.toUpperCase();
             const url = new URL(req.url, 'http://dev.local');
             const [id] = url.pathname.split('/').filter(Boolean);
+            if (!id && method === 'GET') {
+                return sendJson(res, 200, listStreams(store, 'download').map(item => toHandle(item, { complete: item.complete, url: downloadUrl(item) })));
+            }
             if (!id) return next();
+            if (method === 'DELETE') {
+                if (!store.get('download', id)) throw httpError(404, 'Not Found');
+                store.remove(id);
+                res.statusCode = 204;
+                return res.end();
+            }
+            if (method !== 'GET') return next();
             const item = store.get('download', id);
             if (!item || !item.complete) throw httpError(404, 'Not Found');
             return serveDownload(store, item, res, {