@volter/world-core 3.0.151 → 3.0.152

package/dist/src/live/segmenter.js

@@ -0,0 +1,204 @@
+import { AUDIO_TRACK, initSegment, mediaSegment, VIDEO_TIMESCALE, VIDEO_TRACK } from "./fmp4.js";
+const AAC_FRAME = 1024;
+/** The longest a stream may go without a keyframe: ten target durations, at least 20 s, past OBS's automatic interval
+ *  of 250 frames (8.3 s at 30 fps, 10.4 s at 24). */
+const MIN_KEYFRAME_CEILING_MS = 20_000;
+/** What one segment under way may hold: at a Twitch-like 8 Mbit/s, 20 s is 20 MB. */
+const MAX_SEGMENT_BYTES = 64 * 1024 * 1024;
+const MAX_SEGMENT_FRAMES = 10_000;
+/** A stream the segmenter will not hold: its publish is ended with the reason (ingest.ts). */
+export class LiveOverrun extends Error {
+}
+export class Segmenter {
+    options;
+    avc;
+    aac;
+    meta = {};
+    freshInit = true;
+    video = [];
+    audio = [];
+    start;
+    keyed = false;
+    audioNext;
+    lastVideoDuration = 33;
+    sequence = 0;
+    /** what the segment under way holds, and since when video has come with no keyframe to start on */
+    bytes = 0;
+    frames = 0;
+    unkeyedSince;
+    constructor(options) {
+        this.options = options;
+        this.sequence = options.firstSequence;
+    }
+    /** The publisher's metadata (`onMetaData`): the size and rate a stream's SPS does not say, and whether video comes. */
+    metadata(meta) { this.meta = { ...this.meta, ...meta }; }
+    videoConfig(config) {
+        if (this.avc && same(this.avc.record, config.record))
+            return [];
+        const out = this.flush();
+        this.avc = config;
+        this.freshInit = true;
+        this.keyed = false;
+        return out;
+    }
+    audioConfig(config) {
+        if (this.aac && same(this.aac.asc, config.asc))
+            return [];
+        const out = this.aac ? this.flush() : [];
+        this.aac = config;
+        this.freshInit = true;
+        return out;
+    }
+    /** A video frame at its decode time: the segment it closes, if it closes one. */
+    videoFrame(timestamp, key, cts, data) {
+        if (!this.avc)
+            return [];
+        const dts = timestamp + this.options.offsetMs;
+        const out = [];
+        if (!this.keyed) {
+            // a stream is played from a keyframe: what comes before the first is undecodable, and audio before it unheard
+            if (!key) {
+                this.unkeyedSince ??= dts;
+                if (dts - this.unkeyedSince >= this.keyframeCeiling())
+                    throw this.noKeyframe();
+                return [];
+            }
+            this.keyed = true;
+            this.unkeyedSince = undefined;
+            if (this.video.length || this.audioOnlyStarted())
+                out.push(...this.flush());
+            this.start = dts;
+            this.audio = this.audio.filter((a) => a.dts >= dts);
+        }
+        else if (key && this.start !== undefined && dts - this.start >= this.options.targetMs) {
+            const cut = this.cut(dts);
+            if (cut)
+                out.push(cut);
+            this.start = dts;
+        }
+        this.within(dts, data.length, key);
+        this.video.push({ dts, cts, key, data });
+        this.bytes += data.length;
+        this.frames += 1;
+        return out;
+    }
+    audioFrame(timestamp, data) {
+        if (!this.aac || data.length === 0)
+            return [];
+        const dts = timestamp + this.options.offsetMs;
+        if (this.expectsVideo()) {
+            if (!this.keyed)
+                return [];
+            this.within(dts, data.length);
+            this.audio.push({ dts, data });
+            this.bytes += data.length;
+            this.frames += 1;
+            return [];
+        }
+        // audio alone: cut on its own time
+        const out = [];
+        if (this.start === undefined)
+            this.start = dts;
+        else if (dts - this.start >= this.options.targetMs) {
+            const cut = this.cut(dts);
+            if (cut)
+                out.push(cut);
+            this.start = dts;
+        }
+        this.within(dts, data.length);
+        this.audio.push({ dts, data });
+        this.bytes += data.length;
+        this.frames += 1;
+        return out;
+    }
+    /** The segment under way, closed (the publish's end, or a configuration change). */
+    flush() {
+        const cut = this.cut(undefined);
+        this.video = [];
+        this.audio = [];
+        this.start = undefined;
+        this.bytes = 0;
+        this.frames = 0;
+        return cut ? [cut] : [];
+    }
+    keyframeCeiling() { return Math.max(MIN_KEYFRAME_CEILING_MS, 10 * this.options.targetMs); }
+    noKeyframe() {
+        return new LiveOverrun(`The stream sent no keyframe for ${Math.round(this.keyframeCeiling() / 1000)} s; send one at least every ${Math.round(this.options.targetMs / 1000)} s (the encoder's keyframe interval).`);
+    }
+    /** A frame the segment under way may still take, or the refusal past its ceilings. */
+    within(dts, size, key = false) {
+        if (!key && this.start !== undefined && dts - this.start >= this.keyframeCeiling())
+            throw this.noKeyframe();
+        if (this.bytes + size > MAX_SEGMENT_BYTES || this.frames + 1 > MAX_SEGMENT_FRAMES)
+            throw new LiveOverrun(`A segment passed ${MAX_SEGMENT_BYTES} bytes or ${MAX_SEGMENT_FRAMES} frames before a keyframe closed it.`);
+    }
+    expectsVideo() { return this.avc !== undefined || this.meta.videocodecid !== undefined; }
+    audioOnlyStarted() { return !this.expectsVideo() && this.audio.length > 0; }
+    cut(at) {
+        const video = this.video;
+        const audio = at === undefined ? this.audio : this.audio.filter((a) => a.dts < at);
+        this.audio = at === undefined ? [] : this.audio.filter((a) => a.dts >= at);
+        this.video = [];
+        // what the next segment already holds: the audio past the cut
+        this.bytes = this.audio.reduce((n, a) => n + a.data.length, 0);
+        this.frames = this.audio.length;
+        if (video.length === 0 && audio.length === 0)
+            return undefined;
+        const fragments = [];
+        let startMs;
+        let durationMs;
+        if (video.length) {
+            const samples = video.map((s, i) => {
+                const next = i + 1 < video.length ? video[i + 1].dts : at;
+                const ms = next === undefined ? this.lastVideoDuration : Math.max(1, next - s.dts);
+                if (next !== undefined)
+                    this.lastVideoDuration = ms;
+                return { duration: Math.round(ms * 90), data: s.data, key: s.key, cts: Math.round(s.cts * 90) };
+            });
+            startMs = video[0].dts;
+            durationMs = samples.reduce((n, s) => n + s.duration, 0) / 90;
+            fragments.push({ track: VIDEO_TRACK, baseTime: Math.round(startMs * (VIDEO_TIMESCALE / 1000)), samples });
+        }
+        else {
+            startMs = audio[0].dts;
+            durationMs = 0;
+        }
+        if (audio.length && this.aac) {
+            const rate = this.aac.sampleRate;
+            // a running sample clock, resynchronised to the publisher's timestamps when they drift past 100 ms (a gap)
+            const expected = Math.round(audio[0].dts * rate / 1000);
+            if (this.audioNext === undefined || Math.abs(this.audioNext - expected) > rate / 10)
+                this.audioNext = expected;
+            const baseTime = this.audioNext;
+            this.audioNext += AAC_FRAME * audio.length;
+            fragments.push({ track: AUDIO_TRACK, baseTime, samples: audio.map((a) => ({ duration: AAC_FRAME, data: a.data, key: true })) });
+            if (!video.length)
+                durationMs = (AAC_FRAME * audio.length * 1000) / rate;
+        }
+        const sequence = this.sequence++;
+        const cut = { sequence, bytes: mediaSegment(sequence + 1, fragments), start: startMs / 1000, duration: durationMs / 1000 };
+        if (this.freshInit) {
+            this.freshInit = false;
+            const video = this.avc ? { codec: this.avc.codec, width: this.avc.width || Number(this.meta.width) || 0, height: this.avc.height || Number(this.meta.height) || 0, ...(frameRate(this.meta) ? { frameRate: frameRate(this.meta) } : {}) } : undefined;
+            const audioInfo = this.aac ? { codec: this.aac.codec, sampleRate: this.aac.sampleRate, channels: this.aac.channels } : undefined;
+            cut.init = {
+                bytes: initSegment({ ...(this.avc ? { video: { ...this.avc, width: video.width, height: video.height } } : {}), ...(this.aac ? { audio: this.aac } : {}) }),
+                ...(video ? { video } : {}),
+                ...(audioInfo ? { audio: audioInfo } : {}),
+            };
+        }
+        return cut;
+    }
+}
+function frameRate(meta) {
+    const n = Number(meta.framerate ?? meta.fps);
+    return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+function same(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}

package/dist/src/live/types.d.ts

@@ -0,0 +1,102 @@
+/** An ingest the vendor takes (the manifest's `live`): its id, which names the engine `semantics/live.ts` exports, and
+ *  the RTMP application a publisher connects to (`app` in Twitch's `rtmp://<ingest-server>/app/<stream-key>`, `x` in an
+ *  X Media Studio Producer source's URL). */
+export type LiveDecl = {
+    id: string;
+    app: string;
+    note: string;
+    source?: string;
+};
+/** What a publisher asks: the app it connected to, the stream key it publishes (RTMP's `publish` name, its query taken
+ *  off), that query's parameters (Twitch's `bandwidthtest=true`), and who it is. */
+export type LivePublish = {
+    app: string;
+    key: string;
+    query: Record<string, string>;
+    /** the publisher's address, as the listener saw it */
+    peer: string;
+    /** the connect command's `tcUrl`, `flashVer` and the publish type (`live`, `record`, `append`), as sent */
+    tcUrl?: string;
+    flashVer?: string;
+    type?: string;
+};
+/** RTMP's refusals of a publish, sent as the publisher's `onStatus` error before the connection closes. */
+export type LiveRefusal = 'NetStream.Publish.BadName' | 'NetStream.Publish.Denied';
+/** The dialect's ruling on a publish: the recording it goes to (the pack's own id for the vendor's stream or broadcast:
+ *  letters, digits, `.`, `_`, `-`), or the vendor's refusal in its own words. */
+export type LiveAdmission = {
+    stream: string;
+    /** the target segment duration, in seconds (default 2): a segment is cut at the first keyframe after it */
+    segmentSeconds?: number;
+    /** how many segments the live playlist lists (default 6) */
+    window?: number;
+    /** how many segments the recording keeps (default all): an older one's bytes are removed and its subject deleted */
+    retain?: number;
+} | {
+    refused: LiveRefusal;
+    description: string;
+};
+export type LiveVideo = {
+    /** the RFC 6381 codec string (`avc1.64001f`) */
+    codec: string;
+    width: number;
+    height: number;
+    /** frames per second, as the publisher's metadata names it */
+    frameRate?: number;
+};
+export type LiveAudio = {
+    codec: string;
+    sampleRate: number;
+    channels: number;
+};
+/** A recording as the kernel keeps it: the stream the dialect admitted, what was published to it, and its state. */
+export type LiveRecording = {
+    stream: string;
+    /** the ingest's app and the key the last publish named */
+    app: string;
+    key: string;
+    /** `publishing` from the publish's admission until its publisher stops; `ended` after */
+    state: 'publishing' | 'ended';
+    /** World times: the first publish's admission, and the last publish's end */
+    startedAt: string;
+    endedAt?: string;
+    /** how many publishes the recording holds (a publisher that reconnected to the same stream adds one) */
+    publishes: number;
+    /** the segments kept, and the seconds of media they hold */
+    segments: number;
+    duration: number;
+    video?: LiveVideo;
+    audio?: LiveAudio;
+    /** the publisher's `onMetaData`, as sent (its encoder, bitrates, frame rate) */
+    metadata?: Record<string, unknown>;
+};
+/** An ingest's dialect (`semantics/live.ts`, one export per id the manifest's `live` declares), over the handler
+ *  contract's context. Its writes are the vendor's own moves, recorded as any write. */
+export type LiveEngine<C> = {
+    /** A publisher asks to publish `ask.key`: the stream it goes to, or the vendor's refusal. */
+    publish(ctx: C, ask: LivePublish): LiveAdmission | Promise<LiveAdmission>;
+    /** The publish's first segment is playable: the vendor's move (a stream live, a broadcast running). */
+    started?(ctx: C, recording: LiveRecording): void | Promise<void>;
+    /** The publisher stopped (unpublished, deleted its stream, or hung up), its last segment written: the vendor's move
+     *  (the stream offline, the broadcast ended). */
+    ended?(ctx: C, recording: LiveRecording): void | Promise<void>;
+};
+/** How a playlist is answered. */
+export type LiveServeOptions = {
+    /** the segments a live playlist lists: a count (the admission's window, else 6), or `all` (an event playlist) */
+    window?: number | 'all';
+    /** the URI a playlist writes for one of the recording's files (`init-0.mp4`, `seg-12.m4s`, `index.m3u8`); absent,
+     *  the file's name, relative to the playlist */
+    uri?: (file: string) => string;
+};
+/** What a handler and a screen read of the World's recordings (`ctx.live`). */
+export type LiveAccess = {
+    /** The recording `stream` names, or undefined when nothing was published to it. */
+    recording(stream: string): LiveRecording | undefined;
+    /** Every recording of this twin, in the order they were first published. */
+    recordings(): LiveRecording[];
+    /** The recording's `file` as a media host answers it: `index.m3u8` (the media playlist: the live window while it is
+     *  published, the whole recording once it ended), `master.m3u8` (a multivariant playlist naming that one rendition),
+     *  `init-<n>.mp4` or `seg-<n>.m4s`; 404 for anything else, or when the recording or the file is not there. */
+    serve(stream: string, file: string, options?: LiveServeOptions): Promise<Response>;
+};

package/dist/src/live/types.js

@@ -0,0 +1,5 @@
+// LIVE MEDIA's contract (docs/contributing/architecture.md, "Other wires": live media): what a pack declares (the
+// manifest's `live`), what its dialect writes (`semantics/live.ts`, one `LiveEngine` per ingest), and what its screens
+// read (`ctx.live`). The kernel holds the wire (RTMP in, HLS out) and the recording; the pack holds what a stream key
+// means, the vendor's stream or broadcast it opens, and the state moves when it starts and ends. Types only.
+export {};

package/dist/src/pack-fetch.d.ts

@@ -3,6 +3,7 @@ import { type DerivedFetch, type DerivedSurface, type BoardFrame } from './deriv
 import { type PackScenarioAdapter } from './scenario.js';
 import type { ApplicationStandIn } from './events.js';
 import { type SocketEngine } from './sockets.js';
+import type { LiveEngine } from './live/types.js';
 import type { WebSocketUpgrade } from './serve-http.js';
 import { type GraphqlPart } from './graphql-wire.js';
 /** What a pack declares and writes, and nothing it assembles itself. */
@@ -43,6 +44,8 @@ export type PackParts = {
     sockets?: Record<string, SocketEngine<HandlerContext>>;
     /** `semantics/board.ts`: the vendor's frames on the World's board, read from its state (`GET /twin/board`). */
     board?: (ctx: HandlerContext) => BoardFrame[] | Promise<BoardFrame[]>;
+    /** `semantics/live.ts`: each ingest's dialect, by the id the manifest's `live` gives it (live/ingest.ts). */
+    live?: Record<string, LiveEngine<HandlerContext>>;
 };
 /** A pack's scenario (`semantics/scenario.ts` exports `scenario`): the adapter the kernel's engine reads the World's
  *  scenario document with, the operations it decides a turn of, and the request an operation is to it (undefined when
@@ -61,6 +64,7 @@ export type LanePart = {
         /** the hosts the lane's built content screens name: its vendor's router sends `<base>/@<host>/` there */
         contentHosts?: ReadonlyArray<string>;
         upgrade?: WebSocketUpgrade;
+        ingest?: import('./twin-fetch.js').TwinStream;
     };
     manifest: {
         doors?: ReadonlyArray<{

package/dist/src/pack-fetch.js

@@ -23,6 +23,10 @@ import { contentAddressOf } from "./content-route.js";
 import { getPack } from "./packRegistry.js";
 import { hostRules } from '../host-routing.cjs';
 import { socketUpgrade } from "./sockets.js";
+import { liveIngest } from "./live/ingest.js";
+import { readResourceBlob, removeResourceBlob, writeResourceBlob } from "./resource-blob.js";
+import { resourcesOfType } from "./derived-core.js";
+import { worldNow } from "./world-clock.js";
 import { MACHINE_POOL, POOL_KINDS, resetFakePool } from "./machines.js";
 import { applyTwinWrite } from "./serve.js";
 import { graphqlEndpoint } from "./graphql-wire.js";
@@ -609,6 +613,22 @@ export function createPackFetch(parts, options = {}) {
     // a turn a session speaks (a voice agent's reply) is the World's scenario's, as a turn over HTTP is
     async (asked) => engineOf()?.serve(asked)) : undefined;
     const upgrade = laneUpgrades(parts.lanes ?? {}, ownUpgrade);
+    // the broadcasts the vendor takes over RTMP: a publisher's connection, its publish ruled by the pack's dialect over a
+    // context of its own (operation `live:<id>`), its recording kept as the World's bookkeeping and blobs (live/ingest.ts)
+    const ownIngest = m.live?.length ? liveIngest({
+        world: `${m.service}\u0000${options.root ?? ''}`, decls: m.live, engines: parts.live ?? {}, readOnly: options.readOnly ?? false,
+        open: (decl, ask) => open(new Request(`http://live.${m.vendor}.invalid/${encodeURIComponent(decl.app)}`, { method: 'POST', headers: { 'x-forwarded-for': ask.peer } }), `live:${decl.id}`, 'POST', `/${decl.app}`, {}),
+        run: (fn) => runWithCorrelationId(`live_${globalThis.crypto.randomUUID()}`, () => runAsVendorMove(fn)),
+        store: {
+            rows: (type) => resourcesOfType(m.service, type, options.root),
+            blob: (key) => readResourceBlob(m.service, key, options.root),
+            putBlob: (key, bytes) => writeResourceBlob(m.service, key, bytes, options.root),
+            removeBlob: (key) => removeResourceBlob(m.service, key, options.root),
+            now: () => (options.clock ?? worldNow)(),
+            record: async (type, id, fields, operation) => { await applyTwinWrite(m.service, { operation, subjectType: type, subjectId: id, fields, occurredAt: (options.clock ?? worldNow)(), actor: { kind: 'system' } }, options.root); },
+        },
+    }) : undefined;
+    const ingest = ownIngest ?? Object.values(parts.lanes ?? {}).find((l) => l.fetch.ingest)?.fetch.ingest;
     // what serves each operation: the pack's own, and each lane's, each unit's under its own name
     const ownersByUnit = () => ({
         '': {
@@ -618,7 +638,7 @@ export function createPackFetch(parts, options = {}) {
         ...lanesOwners(parts.lanes ?? {}),
     });
     const owners = () => flatOwners(ownersByUnit());
-    return derivedRequestScopes(m, Object.assign(served, { owners, ownersByUnit, serves, advanceClock, workspaces, boards: Boolean(parts.board), maxRequestBodySize: m.descriptor?.maxRequestBodySize, draws: drawsUrl, contentHosts, ...(upgrade ? { upgrade } : {}) }), options.readOnly);
+    return derivedRequestScopes(m, Object.assign(served, { owners, ownersByUnit, serves, advanceClock, workspaces, boards: Boolean(parts.board), maxRequestBodySize: m.descriptor?.maxRequestBodySize, draws: drawsUrl, contentHosts, ...(upgrade ? { upgrade } : {}), ...(ingest ? { ingest } : {}) }), options.readOnly);
 }
 /** The vendor's gateway over its lanes: the lane a request goes to (a door to the lane that declares it, then the first
  *  route whose conditions all hold, then the default), behind the gateway's CORS; undefined when none takes it. */
@@ -715,6 +735,8 @@ function laneUpgrades(lanes, own) {
 }
 export function createVendorFetch(manifest, lanes) {
     const upgrade = laneUpgrades(lanes);
+    // a lane's live ingest is the vendor's (one RTMP listener beside the vendor's HTTP host)
+    const ingest = Object.values(lanes).find((l) => l.fetch.ingest)?.fetch.ingest;
     const lane = laneRouter(manifest.vendor, manifest.lanes, lanes);
     return Object.assign(async (request) => {
         for (const part of Object.values(lanes))
@@ -749,5 +771,5 @@ export function createVendorFetch(manifest, lanes) {
         }
         const to = lane(request);
         return to ? to(request) : Response.json({ error: `${manifest.vendor}: no lane serves ${request.method} ${path}` }, { status: 404 });
-    }, { maxRequestBodySize: manifest.descriptor?.maxRequestBodySize, owners: () => flatOwners(lanesOwners(lanes)), ownersByUnit: () => lanesOwners(lanes), workspaces: () => lanesWorkspaces(lanes), ...(upgrade ? { upgrade } : {}) });
+    }, { maxRequestBodySize: manifest.descriptor?.maxRequestBodySize, owners: () => flatOwners(lanesOwners(lanes)), ownersByUnit: () => lanesOwners(lanes), workspaces: () => lanesWorkspaces(lanes), ...(upgrade ? { upgrade } : {}), ...(ingest ? { ingest } : {}) });
 }

package/dist/src/packRegistry.d.ts

@@ -237,6 +237,7 @@ export type TwinPack = {
         option: string;
         flag: string;
         path?: string;
+        scheme?: string;
         note: string;
     }>;
     stateSystem?: StateSystemAdapters;

package/dist/src/serve-http.d.ts

@@ -50,13 +50,19 @@ export declare function serveHttp(options: ServeHttpOptions): Promise<HttpServer
  *  module that also rides into a browser bundle reaches `node:crypto` with. A bare `require()`
  *  is Bun's alone; Node's ESM has none (found 2026-09-07 by the pages running under node). */
 export declare function nodeBuiltin<T = unknown>(name: string): T;
+/** What `serveStream` throws when the runtime has no TCP layer to listen with at all (no `process.getBuiltinModule`, or
+ *  no `node:net` behind it), as opposed to a listen that failed (EADDRINUSE, EACCES), which it throws as it came. A
+ *  server that can serve without its byte-stream listener (a live ingest beside its HTTP host) falls back on this alone. */
+export declare class StreamListenerUnavailable extends Error {
+}
 /** A raw-TCP twin's listener (the seam's byte-stream half): its `create<Name>TwinStream` served on a TCP port, each
  *  socket one connection, on loopback unless the caller names a hostname. Runtime-neutral, as `serveHttp` is: Node's
- *  `net` reached at call time, never imported. */
+ *  `net` reached at call time, never imported. A stream that declares `maxConnections` (a live ingest) is held to it. */
 export declare function serveStream(options: {
     port?: number;
     hostname?: string;
     stream: TwinStream;
+    maxConnections?: number;
 }): Promise<{
     port: number;
     stop: () => void;

package/dist/src/serve-http.js

@@ -68,14 +68,47 @@ export async function serveHttp(options) {
  *  module that also rides into a browser bundle reaches `node:crypto` with. A bare `require()`
  *  is Bun's alone; Node's ESM has none (found 2026-09-07 by the pages running under node). */
 export function nodeBuiltin(name) { return builtin(name); }
+/** What `serveStream` throws when the runtime has no TCP layer to listen with at all (no `process.getBuiltinModule`, or
+ *  no `node:net` behind it), as opposed to a listen that failed (EADDRINUSE, EACCES), which it throws as it came. A
+ *  server that can serve without its byte-stream listener (a live ingest beside its HTTP host) falls back on this alone. */
+export class StreamListenerUnavailable extends Error {
+}
+/** A stream connection's backlog (whole messages waiting for the twin's work) past which its socket is paused. */
+const STREAM_HIGH_WATER = 4 * 1024 * 1024;
 /** A raw-TCP twin's listener (the seam's byte-stream half): its `create<Name>TwinStream` served on a TCP port, each
  *  socket one connection, on loopback unless the caller names a hostname. Runtime-neutral, as `serveHttp` is: Node's
- *  `net` reached at call time, never imported. */
+ *  `net` reached at call time, never imported. A stream that declares `maxConnections` (a live ingest) is held to it. */
 export async function serveStream(options) {
-    const net = builtin('node:net');
+    const get = process.getBuiltinModule;
+    const net = typeof get === 'function' ? get('node:net') : undefined;
+    if (!net || typeof net.createServer !== 'function')
+        throw new StreamListenerUnavailable('this runtime has no TCP listener (node:net)');
+    const cap = options.maxConnections ?? options.stream.maxConnections;
+    let open = 0;
     const server = net.createServer((socket) => {
+        // past its cap a connection is closed before the stream sees it, so connections that never get anywhere cannot pile up
+        if (cap !== undefined && open >= cap) {
+            socket.destroy();
+            return;
+        }
+        open += 1;
+        socket.once('close', () => { open -= 1; });
         const conn = options.stream({ write: (bytes) => { socket.write(bytes); }, end: () => { socket.end(); } }, socket.remoteAddress ?? '127.0.0.1');
-        socket.on('data', (chunk) => conn.data(new Uint8Array(chunk)));
+        // a connection that says what waits (`backlog`: whole messages its work has not reached) is read no further past the
+        // high-water mark until that work has settled, so a peer faster than the twin (a live ingest pushed faster than real
+        // time) waits in TCP, not here. It is read again once settled, whatever else it holds: only more bytes can finish an
+        // unfinished message, and settling resolves once, so nothing re-arms in a loop
+        let paused = false;
+        const resume = () => { paused = false; if (!socket.destroyed)
+            socket.resume(); };
+        socket.on('data', (chunk) => {
+            conn.data(new Uint8Array(chunk));
+            if (!paused && conn.backlog && conn.backlog() > STREAM_HIGH_WATER) {
+                paused = true;
+                socket.pause();
+                void conn.settled().then(resume, resume);
+            }
+        });
         socket.on('close', () => conn.close());
         socket.on('error', () => conn.close());
     });

package/dist/src/twin-fetch.d.ts

@@ -32,7 +32,9 @@ export declare function twinVendorUrl(request: Request, vendorUrl: string): stri
  *  it over whatever carries the bytes — a local listener's socket, or a WebSocket to a hosted World.
  *  The pack owns framing and protocol; the host owns the transport. `open` greets through the sink;
  *  `data` hands the connection bytes in arrival order; `settled` resolves when every byte handed so
- *  far has been answered; `close` is the peer going away. */
+ *  far has been answered; `close` is the peer going away. A connection whose work can fall behind its bytes (a live
+ *  ingest writing segments) says how many bytes wait in `backlog`, and a listener that can pause its transport does so
+ *  past a high-water mark until `settled` (serve-http.ts, `serveStream`). */
 export type TwinStreamSink = {
     write(bytes: Uint8Array): void;
     end(): void;
@@ -41,6 +43,7 @@ export type TwinStreamConnection = {
     data(chunk: Uint8Array): void;
     settled(): Promise<void>;
     close(): void;
+    backlog?(): number;
 };
 export type TwinStream = (sink: TwinStreamSink, peer: string) => TwinStreamConnection;
 /** The request scopes a pack wrapped in `withRequestScopes` enforces, advertised on its `GET /twin` as

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-core",
-  "version": "3.0.151",
+  "version": "3.0.152",
   "description": "The kernel of Volter World: one log per twin, branches as pointers, checkpoints, the fold that keeps a twin current, the head that performs a write against the vendor, references, and the git plane. A twin package builds on it; the runtime serves it.",
   "keywords": [
     "twin",
@@ -124,6 +124,10 @@
       "types": "./dist/src/mysql/index.d.ts",
       "default": "./dist/src/mysql/index.js"
     },
+    "./live": {
+      "types": "./dist/src/live/index.d.ts",
+      "default": "./dist/src/live/index.js"
+    },
     "./clickhouse": {
       "types": "./dist/src/clickhouse/index.d.ts",
       "default": "./dist/src/clickhouse/index.js"

package/src/derived-core.ts

@@ -16,6 +16,8 @@ import { GitRefs } from './git/refs.ts';
 import { worldNow } from './world-clock.ts';
 import { worldEnvValue } from './world-env.ts';
 import { openSessions, socketWrite, type SocketDecl, type SocketSession } from './sockets.ts';
+import { liveAccess } from './live/access.ts';
+import type { LiveAccess, LiveDecl } from './live/types.ts';
 import { awaitWrite, awaitCondition, heldReadsWrite } from './held-reads.ts';
 import { MACHINE_POOL, poolFor, guardedMachinePool, type MachinePool, type MachineHttpReply, type LightPoolOptions } from './machines.ts';
 import { askApplication, deliverEvents, type ApplicationAnswer, type ApplicationStandIn, type EventRender, type EventScheme, type EventsDecl, type EventValues } from './events.ts';
@@ -520,6 +522,10 @@ export type DerivedManifest = {
   /** The persistent wires the vendor's clients hold open (sockets.ts: Discord's Gateway): each served at its path by
    *  the pack's `semantics/sockets.ts`, which the kernel offers every write after its webhooks. */
   sockets?: ReadonlyArray<SocketDecl>;
+  /** The broadcasts the vendor takes over RTMP (architecture, "Other wires": live media): each ingest's id, which names
+   *  its engine in the pack's `semantics/live.ts`, and the RTMP app it answers. The pack's fetch carries the ingest
+   *  (`fetch.ingest`), which its server serves on a side port. */
+  live?: ReadonlyArray<LiveDecl>;
   /** The vendor speaks gRPC (architecture, "Other wires": gRPC): its server answers HTTP/2 and HTTP/1 on one port, each
    *  rpc (by its proto unit's schema, `src/generated/proto.gen.json`) through the pack's own fetch. */
   grpc?: true;
@@ -1773,6 +1779,9 @@ export type SemanticsContext = {
   issue(resource: string): Promise<string>;
   /** The vendor's open sessions of one of its sockets in this World (a request answered by a session: sockets.ts). */
   sockets(id: string): SocketSession[];
+  /** The World's recordings of what was broadcast to this twin (live media, live/access.ts): a recording's facts, and its
+   *  playlists, init and segments answered as the vendor's media host answers them. */
+  live: LiveAccess;
   /** Hold this read until the World writes (held-reads.ts: HTTP long polling): true when a write of one of the named
    *  resources lands in this World, false when `ms` pass or the client hangs up; at once false in a read-only World. */
   awaitWrite(resources: ReadonlyArray<string>, ms: number): Promise<boolean>;
@@ -2139,6 +2148,7 @@ export async function contextFor(m: DerivedManifest, call: DerivedCall, scope: C
       ...(options.database === undefined ? {} : { database: options.database }),
       ...(options.transaction === undefined ? {} : { transaction: options.transaction }),
     }),
+    live: liveAccess({ rows: (type) => resourcesOfType(m.service, type, root) as unknown as Array<Record<string, unknown>>, blob: (key) => readResourceBlob(m.service, key, root) }, call.request),
     blobs: {
       put: (key, bytes) => writeResourceBlob(m.service, key, bytes, root),
       get: (key) => readResourceBlob(m.service, key, root),

package/src/derived.ts

@@ -7,6 +7,7 @@ import { parseExactJson } from './exact-json.ts';
 // as the `/twin` door). `owners` says, per operation, which of the two serves it: the count a pack's
 // move is measured by. Workerd-clean: no fs, no clock, nothing at import.
 import type { WebSocketUpgrade } from './serve-http.ts';
+import type { TwinStream } from './twin-fetch.ts';
 import { runWithRequestTrace } from './trace-context.ts';
 
 /** The slice of a generated surface the dispatch reads. */
@@ -214,6 +215,9 @@ export type DerivedFetch = ((request: Request) => Promise<Response>) & {
   ownersByUnit?(): Record<string, Record<string, DerivedOwner>>;
   /** The vendor's sockets (sockets.ts), for the serve seam to upgrade to, when its manifest declares any. */
   upgrade?: WebSocketUpgrade;
+  /** The vendor's RTMP ingest (live/ingest.ts), for its server to serve on its side port (`serveStream`), when its
+   *  manifest declares `live`. */
+  ingest?: TwinStream;
   maxRequestBodySize?: number;
   /** The workspace screens it draws, its lanes' too (`GET /twin`'s `screens`). */
   workspaces?(): Workspace[];

package/src/index.ts

@@ -29,6 +29,8 @@ export { verifyEvent } from './events.ts';
 export { deriveStateSystem, deriveVendorStateSystem } from './derived-real.ts';
 export type { IngestDecl } from './derived-core.ts';
 export type { SocketDecl, SocketEngine, SocketSession } from './sockets.ts';
+// live media (architecture, "Other wires": live media): an ingest's declaration, its dialect and what a screen reads
+export type { LiveAccess, LiveAdmission, LiveAudio, LiveDecl, LiveEngine, LivePublish, LiveRecording, LiveRefusal, LiveServeOptions, LiveVideo } from './live/types.ts';
 export { machinePool, isMachineCapabilityGap, type ExecSpec, type MachinePool, type MachineProcess, type MachineRun, type MachineSpec, type MachineStatus, type MachineFiles, type MachineFileStat } from './machines.ts';
 export type { CorsDecl } from './cors.ts';
 
@@ -51,7 +53,7 @@ export { VendorUnreachableError } from './vendor-call.ts';
 export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER } from './request-scope.ts';
 
 // ── the serve factory ──────────────────────────────────────────────────────────────────────────
-export { serveHttp, serveStream, type HttpHandler, type HttpServer, type ServeHttpOptions } from './serve-http.ts';
+export { serveHttp, serveStream, StreamListenerUnavailable, type HttpHandler, type HttpServer, type ServeHttpOptions } from './serve-http.ts';
 export type { TwinStream, TwinStreamConnection, TwinStreamSink } from './twin-fetch.ts';
 export { privateTransportKey } from './private-transport.ts';
 // where a page links a hostname its twin answers, inside the World that shows it
@@ -88,6 +90,7 @@ export { placeholderPng } from './placeholder-image.ts';
 export { presignSigV4, signSigV4, verifySigV4, type SigV4Verdict } from './sigv4.ts';
 export * as redis from './redis/index.ts';
 export * as mysql from './mysql/index.ts';
+export * as live from './live/index.ts';
 export * as git from './git/index.ts';
 
 // ── the scenario grammar (architecture, "Behaviour") ───────────────────────────────────────────