@volter/world-core 3.0.151 → 3.0.153

package/src/live/segmenter.ts

@@ -0,0 +1,218 @@
+// A publish's media cut into HLS segments (RFC 8216 §3: each segment begins with a keyframe, so a player can start at
+// any one): a segment closes at the first video keyframe at or after the target duration from its start; audio follows
+// the video's cuts. A stream with no video is cut on its audio's time. Every timestamp is the publisher's (milliseconds)
+// plus the recording's offset, so a recording a publisher continues keeps its timeline. A change of encoder
+// configuration closes the segment under way and opens a new init. What a segment under way may hold is bounded: a
+// stream that sends no keyframe within the ceiling (no periodic IDR: intra-refresh, an endless GOP), or whose segment
+// passes its byte or frame ceiling (stalled timestamps), is refused (`LiveOverrun`), never held without end. Pure: bytes
+// in, segments out.
+import type { LiveAudio, LiveVideo } from './types.ts';
+import { type AacConfig, type AvcConfig } from './flv.ts';
+import { AUDIO_TRACK, type Fragment, initSegment, mediaSegment, VIDEO_TIMESCALE, VIDEO_TRACK } from './fmp4.ts';
+
+type VideoSample = { dts: number; cts: number; key: boolean; data: Uint8Array };
+type AudioSample = { dts: number; data: Uint8Array };
+
+/** A segment closed: its bytes, its media start and duration (seconds), and, when it opens a new init, that init. */
+export type Cut = {
+  /** the segment's number in its recording */
+  sequence: number;
+  bytes: Uint8Array;
+  start: number;
+  duration: number;
+  init?: { bytes: Uint8Array; video?: LiveVideo; audio?: LiveAudio };
+};
+
+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 {
+  private avc?: AvcConfig;
+  private aac?: AacConfig;
+  private meta: Record<string, unknown> = {};
+  private freshInit = true;
+  private video: VideoSample[] = [];
+  private audio: AudioSample[] = [];
+  private start?: number;
+  private keyed = false;
+  private audioNext?: number;
+  private lastVideoDuration = 33;
+  private sequence = 0;
+  /** what the segment under way holds, and since when video has come with no keyframe to start on */
+  private bytes = 0;
+  private frames = 0;
+  private unkeyedSince?: number;
+
+  constructor(private readonly options: { targetMs: number; offsetMs: number; firstSequence: number }) {
+    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: Record<string, unknown>): void { this.meta = { ...this.meta, ...meta }; }
+
+  videoConfig(config: AvcConfig): Cut[] {
+    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: AacConfig): Cut[] {
+    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: number, key: boolean, cts: number, data: Uint8Array): Cut[] {
+    if (!this.avc) return [];
+    const dts = timestamp + this.options.offsetMs;
+    const out: Cut[] = [];
+    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: number, data: Uint8Array): Cut[] {
+    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: Cut[] = [];
+    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(): Cut[] {
+    const cut = this.cut(undefined);
+    this.video = [];
+    this.audio = [];
+    this.start = undefined;
+    this.bytes = 0;
+    this.frames = 0;
+    return cut ? [cut] : [];
+  }
+
+  private keyframeCeiling(): number { return Math.max(MIN_KEYFRAME_CEILING_MS, 10 * this.options.targetMs); }
+  private noKeyframe(): LiveOverrun {
+    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. */
+  private within(dts: number, size: number, key = false): void {
+    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.`);
+  }
+
+  private expectsVideo(): boolean { return this.avc !== undefined || this.meta.videocodecid !== undefined; }
+  private audioOnlyStarted(): boolean { return !this.expectsVideo() && this.audio.length > 0; }
+
+  private cut(at: number | undefined): Cut | undefined {
+    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: Fragment[] = [];
+    let startMs: number;
+    let durationMs: number;
+    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: 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: Record<string, unknown>): number | undefined {
+  const n = Number(meta.framerate ?? meta.fps);
+  return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+
+function same(a: Uint8Array, b: Uint8Array): boolean {
+  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/src/live/types.ts

@@ -0,0 +1,105 @@
+// 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.
+
+/** 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/src/pack-fetch.ts

@@ -27,6 +27,11 @@ import { hostRules } from '../host-routing.cjs';
 /** A descriptor's host rules, as data. */
 type PackDescriptorHosts = ReadonlyArray<HostRule> | undefined;
 import { socketUpgrade, type SocketEngine } from './sockets.ts';
+import { liveIngest } from './live/ingest.ts';
+import type { LiveEngine } from './live/types.ts';
+import { readResourceBlob, removeResourceBlob, writeResourceBlob } from './resource-blob.ts';
+import { resourcesOfType } from './derived-core.ts';
+import { worldNow } from './world-clock.ts';
 import type { WebSocketUpgrade, WebSocketPeer } from './serve-http.ts';
 import { MACHINE_POOL, POOL_KINDS, resetFakePool } from './machines.ts';
 import { applyTwinWrite } from './serve.ts';
@@ -71,6 +76,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
@@ -86,6 +93,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.ts').TwinStream;
   };
   manifest: { doors?: ReadonlyArray<{ method: string; path: string }> };
 };
@@ -608,6 +616,22 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     // 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<HandlerContext>({
+    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) as unknown as Array<Record<string, unknown>>,
+      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 = (): Record<string, Record<string, DerivedOwner>> => ({
     '': {
@@ -617,7 +641,7 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     ...lanesOwners(parts.lanes ?? {}),
   });
   const owners = (): Record<string, DerivedOwner> => 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
@@ -715,6 +739,8 @@ function laneUpgrades(lanes: Record<string, LanePart>, own?: WebSocketUpgrade):
 
 export function createVendorFetch(manifest: VendorManifest, lanes: Record<string, LanePart>): DerivedFetch {
   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: Request): Promise<Response> => {
     for (const part of Object.values(lanes)) await (part.fetch as typeof part.fetch & { advanceClock?: (request: Request) => Promise<void> }).advanceClock?.(request);
@@ -744,5 +770,5 @@ export function createVendorFetch(manifest: VendorManifest, lanes: Record<string
     }
     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/src/packRegistry.ts

@@ -239,7 +239,7 @@ export type TwinPack = {
   prismaAdapter?: { adapter: string; export: string; urlEnv: string };
   managedService?: { kind: 'redis' | 'mongodb'; scheme: string; note: string };
   managedDatabase?: { kind: 'postgres'; arg: string; note: string };
-  sidePorts?: Array<{ name: string; option: string; flag: string; path?: string; note: string }>;
+  sidePorts?: Array<{ name: string; option: string; flag: string; path?: string; scheme?: string; note: string }>;
   stateSystem?: StateSystemAdapters;
   /** The pack has no vendor-backed half, and why (copied from the manifest by packOf). */
   vendorBacked?: { none: string };

package/src/serve-http.ts

@@ -114,14 +114,39 @@ type NodeStream = typeof import('node:stream');
  *  is Bun's alone; Node's ESM has none (found 2026-09-07 by the pages running under node). */
 export function nodeBuiltin<T = unknown>(name: string): T { return builtin<T>(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. */
-export async function serveStream(options: { port?: number; hostname?: string; stream: TwinStream }): Promise<{ port: number; stop: () => void }> {
-  const net = builtin<typeof import('node:net')>('node:net');
+ *  `net` reached at call time, never imported. A stream that declares `maxConnections` (a live ingest) is held to it. */
+export async function serveStream(options: { port?: number; hostname?: string; stream: TwinStream; maxConnections?: number }): Promise<{ port: number; stop: () => void }> {
+  const get = (process as { getBuiltinModule?: (id: string) => unknown }).getBuiltinModule;
+  const net = typeof get === 'function' ? get('node:net') as typeof import('node:net') | undefined : undefined;
+  if (!net || typeof net.createServer !== 'function') throw new StreamListenerUnavailable('this runtime has no TCP listener (node:net)');
+  const cap = options.maxConnections ?? (options.stream as { maxConnections?: number }).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: Buffer) => 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 = (): void => { paused = false; if (!socket.destroyed) socket.resume(); };
+    socket.on('data', (chunk: Buffer) => {
+      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/src/twin-fetch.ts

@@ -100,9 +100,11 @@ export function twinVendorUrl(request: Request, vendorUrl: string): string {
  *  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 };
-export type TwinStreamConnection = { data(chunk: Uint8Array): void; settled(): Promise<void>; close(): void };
+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