@volter/world-core 3.0.151 → 3.0.153

package/src/events.ts

@@ -7,7 +7,7 @@
 // Imports stay free of side effects: the delivery's transport (Node's http, the World's egress policy) is loaded when a
 // delivery is made, never when a browser client imports the kernel.
 import { createHash, createHmac } from 'node:crypto';
-import { applyTwinWrite, twinResources } from './serve.ts';
+import { applyTwinWrite, applyTwinWriteAtomic, twinResources } from './serve.ts';
 import { equalSecrets as same, ksuidFrom } from './signing.ts';
 import { deliveryTraceHeaders } from './trace-context.ts';
 
@@ -123,19 +123,17 @@ export type EventDelivery = { url: string; body: string; headers: Record<string,
 /** The transport a delivery is made over; the World's by default, a test's own when given. */
 export type EventTransport = (url: string, body: string, headers: Record<string, string>) => Promise<number | void>;
 
-const digest = (s: string): string => createHash('sha256').update(s).digest('hex');
-
 /** A `webhook-id` scheme's key: the base64 part of the secret, after its prefix when it carries one. */
 const webhookKey = (scheme: { secretPrefix?: string; secretKey?: 'base64' | 'utf8' }, secret: string): Buffer =>
   scheme.secretKey === 'utf8' ? Buffer.from(secret, 'utf8') : Buffer.from(scheme.secretPrefix && secret.startsWith(scheme.secretPrefix) ? secret.slice(scheme.secretPrefix.length) : secret, 'base64');
 
 /** A signature scheme's headers for one delivery: deterministic (the id is derived from the delivery itself). */
-/** `seq` tells apart two identical deliveries at one instant (a frozen World clock): the World's count of deliveries
- *  made before this one, so a receiver that deduplicates by id drops neither. */
-export function signEvent(scheme: EventScheme, secret: string, body: string, seconds: number, url: string, seq = 0): Record<string, string> {
+/** `seq` tells apart deliveries at one instant; the declared-event path reserves it durably. `identity` supplies that
+ *  occurrence's namespace. Omitted, existing direct callers retain their deterministic signing contract. */
+export function signEvent(scheme: EventScheme, secret: string, body: string, seconds: number, url: string, seq = 0, identity?: string): Record<string, string> {
   if (scheme.kind === 'webhook-id') {
     // Svix's `msg_` and a KSUID (its ids' form), derived from the delivery itself
-    const id = `msg_${ksuidFrom(seconds, seq, `${url}|${seconds}|${seq}|${body}`)}`;
+    const id = `msg_${ksuidFrom(seconds, seq, identity ?? `${url}|${seconds}|${seq}|${body}`)}`;
     const p = scheme.prefix.toLowerCase();
     const signature = createHmac('sha256', webhookKey(scheme, secret)).update(`${id}.${seconds}.${body}`, 'utf8').digest('base64');
     return { [`${p}-id`]: id, [`${p}-timestamp`]: String(seconds), [`${p}-signature`]: `v1,${signature}` };
@@ -161,8 +159,25 @@ const hmacBase = (scheme: { timestampHeader?: string; signed?: string }, seconds
   scheme.signed !== undefined ? scheme.signed.replaceAll('{t}', String(seconds)).replaceAll('{body}', body) : scheme.timestampHeader ? `${seconds}.${body}` : body;
 
 /** Every scheme's headers for one delivery, merged. */
-export function signEventAll(schemes: EventScheme | ReadonlyArray<EventScheme>, secret: string, body: string, seconds: number, url: string, seq = 0): Record<string, string> {
-  return Object.assign({}, ...(Array.isArray(schemes) ? schemes : [schemes]).map((scheme: EventScheme) => signEvent(scheme, secret, body, seconds, url, seq)));
+export function signEventAll(schemes: EventScheme | ReadonlyArray<EventScheme>, secret: string, body: string, seconds: number, url: string, seq = 0, identity?: string): Record<string, string> {
+  return Object.assign({}, ...(Array.isArray(schemes) ? schemes : [schemes]).map((scheme: EventScheme) => signEvent(scheme, secret, body, seconds, url, seq, identity)));
+}
+
+/** Reserve occurrences under the same cross-process lock that appends actions. This private retained row is never a
+ *  vendor resource. Deleted event/delivery rows, concurrent renders and restarts cannot give its ordinals back. */
+async function reserveEventOrdinals(service: string, root: string | undefined, occurredAt: string, count: number): Promise<number> {
+  const { value } = await applyTwinWriteAtomic(service, (resources) => {
+    const counter = resources.find((r) => r.type === '_world_event_sequence' && r.id === 'sequence');
+    const last = counter === undefined ? 0 : (counter as Record<string, unknown>).last_ordinal;
+    if (typeof last !== 'number' || !Number.isSafeInteger(last) || last < 0 || !Number.isSafeInteger(count) || count < 1 || !Number.isSafeInteger(last + count)) {
+      throw new Error('Invalid retained declared-event sequence; occurrence ids cannot be reused.');
+    }
+    return { kind: 'write', value: last + 1, write: {
+      operation: 'world_event_sequence.reserve', subjectType: '_world_event_sequence', subjectId: 'sequence',
+      fields: { last_ordinal: last + count }, input: { clock: true }, occurredAt, actor: { kind: 'system' },
+    } };
+  }, root);
+  return value;
 }
 
 /** A delivery's signature checked as its receiver checks it (a Standard Webhooks verifier, a timestamp-v1 verifier, a plain
@@ -386,11 +401,19 @@ async function deliverEventType(
   const seconds = Math.floor(millis / 1000);
   const eventData = await data(type);
   const extra = values ? await values(type) : {};
-  // the World's count of events kept so far tells apart two identical events at one instant (a frozen clock)
-  const kept = decl.store !== undefined ? all.filter((r) => r.type === decl.store).length : 0;
+  // Reserve one event and at most one delivery per live endpoint before assigning identities. Unused ordinals are
+  // harmless gaps; a failed render/store never gives them back. This is not an atomic originating-write outbox.
+  const ordinal = await reserveEventOrdinals(service, write.root, write.occurredAt, 1 + live.length);
+  // Fresh/forked Worlds can reserve the same ordinal at a pinned clock. Keep
+  // content binding as well as the lineage's occurrence ordinal, so different
+  // event payloads cannot reuse a receiver's event/webhook id across those Worlds.
+  const eventContent = createHash('sha256').update(JSON.stringify({
+    operation: write.operation, type, data: eventData, envelope: decl.envelope,
+    values: extra, request: requestValues(write.request),
+  }), 'utf8').digest('hex');
   const filled: Record<string, unknown> = {
     $type: type, $data: eventData,
-    $id: `evt_${ksuidFrom(seconds, kept, `${type}|${write.occurredAt}|${kept}|${JSON.stringify(eventData)}`)}`,
+    $id: `evt_${ksuidFrom(seconds, ordinal, `world-events:v1:${service}:${type}:${ordinal}:${eventContent}`)}`,
     '$time.ms': millis, '$time.s': seconds, '$time.iso': write.occurredAt,
     ...requestValues(write.request),
     ...extra,
@@ -407,18 +430,19 @@ async function deliverEventType(
   const shared = JSON.stringify(envelope);
   const each = perEndpoint(decl.envelope);
   const sent: EventDelivery[] = [];
-  const before = decl.record !== undefined ? all.filter((r) => r.type === decl.record).length : 0;
   for (const [i, { row, kind }] of endpoints.entries()) {
     const body = each ? JSON.stringify(fillEnvelope(decl.envelope, filled, row)) : shared;
     const url = String(at(row, kind.url));
-    const seq = before + i;
+    const seq = ordinal + 1 + i;
+    const deliveryContent = createHash('sha256').update(url, 'utf8').update('\0').update(body, 'utf8').digest('hex');
+    const identity = `world-events:v1:${service}:${seq}:${deliveryContent}`;
     const extraHeaders = decl.headers ? headersFor(decl.headers, filled, row) : {};
-    const headers = { ...extraHeaders, ...signEventAll(decl.scheme, String(at(row, kind.secret)), body, seconds, url, seq) };
+    const headers = { ...extraHeaders, ...signEventAll(decl.scheme, String(at(row, kind.secret)), body, seconds, url, seq, identity) };
     sent.push({ url, body, headers });
     // kept with the write, by an id of the delivery itself (two made at once never take the same one)
     if (decl.record !== undefined) {
       await applyTwinWrite(service, {
-        operation: `${decl.record.slice(1)}.record`, subjectType: decl.record, subjectId: `${decl.record.slice(1)}_${digest(`${url}|${seconds}|${seq}|${body}`).slice(0, 16)}`,
+        operation: `${decl.record.slice(1)}.record`, subjectType: decl.record, subjectId: `${decl.record.slice(1)}_v1_${seq}`,
         fields: { url, body, headers, event_type: type, sent_at: millis }, occurredAt: write.occurredAt, actor: { kind: 'system' },
       }, write.root);
     }

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") ───────────────────────────────────────────

package/src/live/access.ts

@@ -0,0 +1,89 @@
+// What a handler and a screen read of the World's recordings (`ctx.live`, architecture "Other wires": live media): a
+// recording's facts from its bookkeeping subjects, and its playlists, init and segments answered as a media host
+// answers them. The recording's rows are the tree's (`_live`, `_live_segment`); the bytes are the pack's resource blobs.
+import { bytesResponse } from '../file-response.ts';
+import { masterPlaylist, mediaPlaylist, type HlsSegment } from './hls.ts';
+import type { LiveAccess, LiveAudio, LiveRecording, LiveVideo } from './types.ts';
+
+/** The bookkeeping types a recording is kept in. */
+export const LIVE = '_live';
+export const LIVE_SEGMENT = '_live_segment';
+
+/** Where a recording's bytes are kept among the pack's resource blobs. */
+export const initBlob = (stream: string, init: number): string => `live/${stream}/init-${init}.mp4`;
+export const segmentBlob = (stream: string, seq: number): string => `live/${stream}/seg-${seq}.m4s`;
+
+type Row = Record<string, unknown>;
+export type LiveReads = {
+  rows(type: string): Row[];
+  blob(key: string): Promise<Uint8Array | null>;
+};
+
+/** A recording's kept segments, in order. */
+export function segmentsOf(reads: LiveReads, stream: string): Array<HlsSegment & { start: number; blob: string }> {
+  return reads.rows(LIVE_SEGMENT)
+    .filter((r) => r.stream === stream && r.deleted !== true)
+    .map((r) => ({ seq: Number(r.seq), init: Number(r.init), duration: Number(r.duration), size: Number(r.size), start: Number(r.start), blob: String(r.blob) }))
+    .sort((a, b) => a.seq - b.seq);
+}
+
+export function recordingOf(row: Row, segments: ReadonlyArray<HlsSegment>): LiveRecording {
+  return {
+    stream: String(row.id),
+    app: String(row.app ?? ''),
+    key: String(row.key ?? ''),
+    state: row.state === 'ended' ? 'ended' : 'publishing',
+    startedAt: String(row.startedAt ?? ''),
+    ...(typeof row.endedAt === 'string' ? { endedAt: row.endedAt } : {}),
+    publishes: Number(row.publishes ?? 1),
+    segments: segments.length,
+    duration: Math.round(segments.reduce((n, s) => n + s.duration, 0) * 1000) / 1000,
+    ...(row.video && typeof row.video === 'object' ? { video: row.video as LiveVideo } : {}),
+    ...(row.audio && typeof row.audio === 'object' ? { audio: row.audio as LiveAudio } : {}),
+    ...(row.metadata && typeof row.metadata === 'object' ? { metadata: row.metadata as Record<string, unknown> } : {}),
+  };
+}
+
+const CORS = { 'access-control-allow-origin': '*' };
+const missing = (): Response => new Response('Not Found', { status: 404, headers: { 'content-type': 'text/plain; charset=utf-8', ...CORS } });
+
+/** `ctx.live` over a request (the one a media host answers, for its Range and its method). */
+export function liveAccess(reads: LiveReads, request: Request): LiveAccess {
+  const rowOf = (stream: string): Row | undefined => reads.rows(LIVE).find((r) => r.id === stream && r.deleted !== true);
+  return {
+    recording(stream) {
+      const row = rowOf(stream);
+      return row ? recordingOf(row, segmentsOf(reads, stream)) : undefined;
+    },
+    recordings() {
+      return reads.rows(LIVE).filter((r) => r.deleted !== true).map((r) => recordingOf(r, segmentsOf(reads, String(r.id))));
+    },
+    async serve(stream, file, options = {}) {
+      const row = rowOf(stream);
+      if (!row) return missing();
+      const segments = segmentsOf(reads, stream);
+      const ended = row.state === 'ended';
+      if (file === 'index.m3u8' || file === 'master.m3u8') {
+        // a recording with nothing playable yet has no playlist: a player waits, as for a stream not yet live
+        if (!segments.length) return missing();
+        const recording = recordingOf(row, segments);
+        const uri = options.uri ?? ((f: string) => f);
+        const text = file === 'index.m3u8'
+          ? mediaPlaylist({ state: recording.state, ...(typeof row.window === 'number' ? { window: row.window } : {}) }, segments, options)
+          : masterPlaylist(recording, segments, uri('index.m3u8'));
+        return new Response(request.method === 'HEAD' ? null : text, { headers: { 'content-type': 'application/vnd.apple.mpegurl', 'cache-control': ended ? 'public, max-age=3600' : 'no-cache, no-store', ...CORS } });
+      }
+      const init = /^init-(\d{1,9})\.mp4$/.exec(file);
+      const seg = /^seg-(\d{1,12})\.m4s$/.exec(file);
+      let key: string | undefined;
+      if (init && segments.some((s) => s.init === Number(init[1]))) key = initBlob(stream, Number(init[1]));
+      else if (seg) key = segments.find((s) => s.seq === Number(seg[1]))?.blob;
+      if (!key) return missing();
+      const bytes = await reads.blob(key);
+      if (!bytes) return missing();
+      const answer = bytesResponse(request, bytes, 'video/mp4');
+      for (const [k, v] of Object.entries(CORS)) answer.headers.set(k, v);
+      return answer;
+    },
+  };
+}

package/src/live/amf0.ts

@@ -0,0 +1,80 @@
+// AMF0, the encoding of RTMP's commands and data messages (Adobe's AMF0 specification, as RTMP 1.0 §7 uses it): a
+// command is a sequence of values (its name, a transaction id, an object, its arguments). Read: number, boolean,
+// string, object, null, undefined, ECMA array, strict array, date, long string, typed object; a reference (0x07) is read
+// as undefined, never followed, so no value read is cyclic (a publisher's metadata pointing back at itself); anything
+// else stops the read where it is. Written: number, boolean, string, object (and a plain record), null, undefined.
+
+export type Amf0Value = number | boolean | string | null | undefined | Date | Amf0Value[] | { [key: string]: Amf0Value };
+
+const utf8 = new TextDecoder();
+const encoder = new TextEncoder();
+
+/** Every value in `bytes`, in order; a value of a type AMF0 commands do not carry ends the read. */
+export function decodeAmf0(bytes: Uint8Array): Amf0Value[] {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  let at = 0;
+  const str = (length: number): string => { const s = utf8.decode(bytes.subarray(at, at + length)); at += length; return s; };
+  const key = (): string => { const n = view.getUint16(at); at += 2; return str(n); };
+  const properties = (into: Record<string, Amf0Value>): Record<string, Amf0Value> => {
+    for (;;) {
+      if (at + 3 > bytes.length) return into;
+      if (view.getUint16(at) === 0 && bytes[at + 2] === 0x09) { at += 3; return into; }
+      const name = key();
+      into[name] = value();
+    }
+  };
+  const value = (): Amf0Value => {
+    const marker = bytes[at++];
+    switch (marker) {
+      case 0x00: { const n = view.getFloat64(at); at += 8; return n; }
+      case 0x01: return bytes[at++] !== 0;
+      case 0x02: return key();
+      case 0x03: return properties({});
+      case 0x05: return null;
+      case 0x06: return undefined;
+      case 0x07: at += 2; return undefined;
+      case 0x08: at += 4; return properties({});
+      case 0x0a: {
+        const n = view.getUint32(at); at += 4;
+        const list: Amf0Value[] = [];
+        for (let i = 0; i < n && at < bytes.length; i++) list.push(value());
+        return list;
+      }
+      case 0x0b: { const ms = view.getFloat64(at); at += 10; return new Date(ms); }
+      case 0x0c: { const n = view.getUint32(at); at += 4; return str(n); }
+      case 0x10: key(); return properties({});
+      default: throw new Amf0End();
+    }
+  };
+  const out: Amf0Value[] = [];
+  while (at < bytes.length) {
+    try { out.push(value()); } catch (error) { if (error instanceof Amf0End || error instanceof RangeError) break; throw error; }
+  }
+  return out;
+}
+class Amf0End extends Error {}
+
+/** `values` as AMF0, in order. */
+export function encodeAmf0(...values: Amf0Value[]): Uint8Array {
+  const parts: number[] = [];
+  const u16 = (n: number): void => { parts.push((n >> 8) & 0xff, n & 0xff); };
+  const text = (s: string): void => { const b = encoder.encode(s); u16(b.length); for (const x of b) parts.push(x); };
+  const write = (v: Amf0Value): void => {
+    if (typeof v === 'number') {
+      parts.push(0x00);
+      const b = new Uint8Array(8); new DataView(b.buffer).setFloat64(0, v);
+      for (const x of b) parts.push(x);
+    } else if (typeof v === 'boolean') parts.push(0x01, v ? 1 : 0);
+    else if (typeof v === 'string') { parts.push(0x02); text(v); }
+    else if (v === null) parts.push(0x05);
+    else if (v === undefined) parts.push(0x06);
+    else if (v instanceof Date || Array.isArray(v)) throw new Error('amf0: this writer writes no dates or arrays');
+    else {
+      parts.push(0x03);
+      for (const [k, x] of Object.entries(v)) { text(k); write(x); }
+      parts.push(0x00, 0x00, 0x09);
+    }
+  };
+  for (const v of values) write(v);
+  return Uint8Array.from(parts);
+}

package/src/live/flv.ts

@@ -0,0 +1,145 @@
+// An FLV tag's body as RTMP carries it (FLV 10.1, Annex E.4.2 and E.4.3): video as AVC (codec 7, its packet type 0 the
+// AVCDecoderConfigurationRecord, 1 length-prefixed NAL units with a composition time offset), audio as AAC (format 10, its
+// packet type 0 the AudioSpecificConfig, 1 a raw frame). Anything else is named as the codec it is and not read: other
+// codecs, and Enhanced RTMP's ex-header (its first byte's high bit), which carries HEVC, AV1 and multitrack video.
+
+export type AvcConfig = {
+  /** the AVCDecoderConfigurationRecord as sent, which an `avcC` box holds as is (ISO/IEC 14496-15 §5.3.3.1) */
+  record: Uint8Array;
+  /** the RFC 6381 codec string: `avc1.` and the profile, constraint flags and level, in hex */
+  codec: string;
+  width: number;
+  height: number;
+};
+export type AacConfig = {
+  /** the AudioSpecificConfig as sent, which an `esds` box's DecoderSpecificInfo holds as is */
+  asc: Uint8Array;
+  codec: string;
+  objectType: number;
+  sampleRate: number;
+  channels: number;
+};
+
+export type VideoTag =
+  | { kind: 'config'; config: AvcConfig }
+  | { kind: 'frame'; key: boolean; cts: number; data: Uint8Array }
+  | { kind: 'other' }
+  | { kind: 'unsupported'; codec: string };
+export type AudioTag =
+  | { kind: 'config'; config: AacConfig }
+  | { kind: 'frame'; data: Uint8Array }
+  | { kind: 'unsupported'; codec: string };
+
+const VIDEO_CODECS: Record<number, string> = { 2: 'Sorenson H.263', 3: 'Screen video', 4: 'On2 VP6', 5: 'On2 VP6 with alpha', 6: 'Screen video 2', 12: 'HEVC', 13: 'AV1' };
+const AUDIO_FORMATS: Record<number, string> = { 0: 'linear PCM', 1: 'ADPCM', 2: 'MP3', 3: 'linear PCM (little-endian)', 4: 'Nellymoser 16 kHz', 5: 'Nellymoser 8 kHz', 6: 'Nellymoser', 7: 'G.711 A-law', 8: 'G.711 mu-law', 11: 'Speex', 14: 'MP3 8 kHz', 15: 'device-specific' };
+const hex2 = (n: number): string => n.toString(16).padStart(2, '0');
+
+export function readVideoTag(p: Uint8Array): VideoTag {
+  if (p.length < 1) return { kind: 'other' };
+  if (p[0]! & 0x80) {
+    const fourcc = p.length >= 5 ? String.fromCharCode(p[1]!, p[2]!, p[3]!, p[4]!) : '?';
+    return { kind: 'unsupported', codec: `Enhanced RTMP ${fourcc}` };
+  }
+  const frameType = p[0]! >> 4;
+  const codec = p[0]! & 0x0f;
+  if (codec !== 7) return { kind: 'unsupported', codec: VIDEO_CODECS[codec] ?? `video codec ${codec}` };
+  // a video info/command frame (frame type 5) carries no picture
+  if (frameType === 5 || p.length < 5) return { kind: 'other' };
+  const packetType = p[1]!;
+  const cts = ((p[2]! << 16) | (p[3]! << 8) | p[4]!) << 8 >> 8;
+  const data = p.subarray(5);
+  if (packetType === 0) return { kind: 'config', config: avcConfig(data) };
+  if (packetType === 1) return { kind: 'frame', key: frameType === 1, cts, data };
+  return { kind: 'other' };
+}
+
+export function readAudioTag(p: Uint8Array): AudioTag {
+  if (p.length < 2) return { kind: 'frame', data: new Uint8Array(0) };
+  const format = p[0]! >> 4;
+  if (format !== 10) return { kind: 'unsupported', codec: AUDIO_FORMATS[format] ?? `audio format ${format}` };
+  if (p[1] === 0) return { kind: 'config', config: aacConfig(p.subarray(2)) };
+  return { kind: 'frame', data: p.subarray(2) };
+}
+
+function avcConfig(record: Uint8Array): AvcConfig {
+  const copy = record.slice();
+  const codec = copy.length >= 4 ? `avc1.${hex2(copy[1]!)}${hex2(copy[2]!)}${hex2(copy[3]!)}` : 'avc1.42e01e';
+  let width = 0;
+  let height = 0;
+  // the first SPS: after the version, profile, compatibility, level, length size and SPS count
+  if (copy.length > 8 && (copy[5]! & 0x1f) > 0) {
+    const length = (copy[6]! << 8) | copy[7]!;
+    try { ({ width, height } = spsSize(copy.subarray(8, 8 + length))); } catch { /* the metadata's size stands in */ }
+  }
+  return { record: copy, codec, width, height };
+}
+
+function aacConfig(asc: Uint8Array): AacConfig {
+  const copy = asc.slice();
+  const RATES = [96000, 88200, 64000, 48000, 44100, 32000, 24000, 22050, 16000, 12000, 11025, 8000, 7350];
+  const bits = new Bits(copy);
+  let objectType = bits.u(5);
+  if (objectType === 31) objectType = 32 + bits.u(6);
+  const index = bits.u(4);
+  const sampleRate = index === 15 ? bits.u(24) : RATES[index] ?? 44100;
+  const channels = bits.u(4);
+  return { asc: copy, codec: `mp4a.40.${objectType}`, objectType, sampleRate, channels };
+}
+
+/** A bit reader over bytes, MSB first; a read past the end reads zeros. */
+class Bits {
+  private at = 0;
+  constructor(private readonly bytes: Uint8Array) {}
+  bit(): number { const byte = this.bytes[this.at >> 3] ?? 0; const v = (byte >> (7 - (this.at & 7))) & 1; this.at++; return v; }
+  u(n: number): number { let v = 0; for (let i = 0; i < n; i++) v = v * 2 + this.bit(); return v; }
+  ue(): number { let zeros = 0; while (this.bit() === 0) { if (++zeros > 31) throw new Error('exp-Golomb code too long'); } return 2 ** zeros - 1 + this.u(zeros); }
+  se(): number { const k = this.ue(); return k % 2 ? (k + 1) / 2 : -(k / 2); }
+}
+
+/** A sequence parameter set's picture size (H.264 §7.3.2.1.1), its cropping applied. */
+function spsSize(nal: Uint8Array): { width: number; height: number } {
+  // the NAL unit's RBSP: its header byte off, each emulation-prevention byte (00 00 03) removed
+  const rbsp: number[] = [];
+  for (let i = 1; i < nal.length; i++) {
+    if (i >= 3 && nal[i] === 3 && nal[i - 1] === 0 && nal[i - 2] === 0) continue;
+    rbsp.push(nal[i]!);
+  }
+  const b = new Bits(Uint8Array.from(rbsp));
+  const profile = b.u(8);
+  b.u(16);
+  b.ue();
+  let chroma = 1;
+  if ([100, 110, 122, 244, 44, 83, 86, 118, 128, 138, 139, 134, 135].includes(profile)) {
+    chroma = b.ue();
+    if (chroma === 3) b.bit();
+    b.ue(); b.ue(); b.bit();
+    if (b.bit()) {
+      for (let i = 0; i < (chroma === 3 ? 12 : 8); i++) {
+        if (!b.bit()) continue;
+        let last = 8; let next = 8;
+        for (let j = 0; j < (i < 6 ? 16 : 64); j++) {
+          if (next !== 0) next = (last + b.se() + 256) % 256;
+          last = next === 0 ? last : next;
+        }
+      }
+    }
+  }
+  b.ue();
+  const poc = b.ue();
+  if (poc === 0) b.ue();
+  else if (poc === 1) { b.bit(); b.se(); b.se(); const n = b.ue(); for (let i = 0; i < n; i++) b.se(); }
+  b.ue(); b.bit();
+  const widthMbs = b.ue() + 1;
+  const heightUnits = b.ue() + 1;
+  const frameMbsOnly = b.bit();
+  if (!frameMbsOnly) b.bit();
+  b.bit();
+  let crop = [0, 0, 0, 0];
+  if (b.bit()) crop = [b.ue(), b.ue(), b.ue(), b.ue()];
+  const unitX = chroma === 1 || chroma === 2 ? 2 : 1;
+  const unitY = (chroma === 1 ? 2 : 1) * (2 - frameMbsOnly);
+  return {
+    width: widthMbs * 16 - (crop[0]! + crop[1]!) * unitX,
+    height: (2 - frameMbsOnly) * heightUnits * 16 - (crop[2]! + crop[3]!) * unitY,
+  };
+}

package/src/live/fmp4.ts

@@ -0,0 +1,102 @@
+// Fragmented MP4, as HLS plays it (RFC 8216 §3.3) and Media Source Extensions append it (W3C's ISO BMFF byte stream
+// format): an init segment (`ftyp`, `moov` with each track's sample description and `mvex`), then media segments, each
+// one `moof` (a `traf` per track: its decode time and its samples' durations, sizes, flags and composition offsets) and
+// one `mdat`. Video is track 1 at 90 kHz with the publisher's avcC as is; audio is track 2 at its sample rate with its
+// AudioSpecificConfig in an `esds`. Boxes per ISO/IEC 14496-12 and -14 and -15.
+import type { AacConfig, AvcConfig } from './flv.ts';
+
+export const VIDEO_TRACK = 1;
+export const AUDIO_TRACK = 2;
+export const VIDEO_TIMESCALE = 90_000;
+
+const ascii = (s: string): number[] => Array.from(s, (c) => c.charCodeAt(0));
+const u16 = (n: number): number[] => [(n >> 8) & 0xff, n & 0xff];
+const u32 = (n: number): number[] => [(n >>> 24) & 0xff, (n >>> 16) & 0xff, (n >>> 8) & 0xff, n & 0xff];
+const u64 = (n: number): number[] => [...u32(Math.floor(n / 2 ** 32)), ...u32(n % 2 ** 32)];
+const zeros = (n: number): number[] => new Array<number>(n).fill(0);
+
+type Part = number[] | Uint8Array;
+function box(type: string, ...parts: Part[]): Uint8Array {
+  const size = 8 + parts.reduce((n, p) => n + p.length, 0);
+  const out = new Uint8Array(size);
+  out.set(u32(size), 0);
+  out.set(ascii(type), 4);
+  let at = 8;
+  for (const p of parts) { out.set(p, at); at += p.length; }
+  return out;
+}
+const full = (type: string, version: number, flags: number, ...parts: Part[]): Uint8Array => box(type, [version, (flags >> 16) & 0xff, (flags >> 8) & 0xff, flags & 0xff], ...parts);
+const MATRIX = [...u32(0x00010000), ...u32(0), ...u32(0), ...u32(0), ...u32(0x00010000), ...u32(0), ...u32(0), ...u32(0), ...u32(0x40000000)];
+
+function descriptor(tag: number, ...parts: Part[]): number[] {
+  const body = parts.flatMap((p) => Array.from(p));
+  // the size as four bytes of seven bits, as MP4 writers write it
+  const n = body.length;
+  return [tag, 0x80 | ((n >> 21) & 0x7f), 0x80 | ((n >> 14) & 0x7f), 0x80 | ((n >> 7) & 0x7f), n & 0x7f, ...body];
+}
+
+function trak(id: number, kind: 'video' | 'audio', timescale: number, width: number, height: number, entry: Uint8Array): Uint8Array {
+  const tkhd = full('tkhd', 0, 3, u32(0), u32(0), u32(id), u32(0), u32(0), zeros(8), u16(0), u16(0), u16(kind === 'audio' ? 0x0100 : 0), u16(0), MATRIX, u32(width * 65536), u32(height * 65536));
+  const mdhd = full('mdhd', 0, 0, u32(0), u32(0), u32(timescale), u32(0), u16(0x55c4), u16(0));
+  const hdlr = full('hdlr', 0, 0, u32(0), ascii(kind === 'video' ? 'vide' : 'soun'), zeros(12), [...ascii(kind === 'video' ? 'VideoHandler' : 'SoundHandler'), 0]);
+  const header = kind === 'video' ? full('vmhd', 0, 1, u16(0), zeros(6)) : full('smhd', 0, 0, u16(0), u16(0));
+  const dinf = box('dinf', full('dref', 0, 0, u32(1), full('url ', 0, 1)));
+  const stbl = box('stbl', full('stsd', 0, 0, u32(1), entry), full('stts', 0, 0, u32(0)), full('stsc', 0, 0, u32(0)), full('stsz', 0, 0, u32(0), u32(0)), full('stco', 0, 0, u32(0)));
+  return box('trak', tkhd, box('mdia', mdhd, hdlr, box('minf', header, dinf, stbl)));
+}
+
+/** The init segment for the tracks a publish carries. */
+export function initSegment(tracks: { video?: AvcConfig & { width: number; height: number }; audio?: AacConfig }): Uint8Array {
+  const traks: Uint8Array[] = [];
+  const trex: Uint8Array[] = [];
+  const brands = ['isom', 'iso6', ...(tracks.video ? ['avc1'] : []), 'mp41'];
+  if (tracks.video) {
+    const v = tracks.video;
+    const avc1 = box('avc1', zeros(6), u16(1), u16(0), u16(0), zeros(12), u16(v.width), u16(v.height), u32(0x00480000), u32(0x00480000), u32(0), u16(1), zeros(32), u16(0x0018), u16(0xffff), box('avcC', v.record));
+    traks.push(trak(VIDEO_TRACK, 'video', VIDEO_TIMESCALE, v.width, v.height, avc1));
+    trex.push(full('trex', 0, 0, u32(VIDEO_TRACK), u32(1), u32(0), u32(0), u32(0)));
+  }
+  if (tracks.audio) {
+    const a = tracks.audio;
+    const esds = full('esds', 0, 0, descriptor(3, u16(0), [0], descriptor(4, [0x40, 0x15], zeros(3), u32(0), u32(0), descriptor(5, a.asc)), descriptor(6, [0x02])));
+    const mp4a = box('mp4a', zeros(6), u16(1), zeros(8), u16(Math.max(1, a.channels)), u16(16), u16(0), u16(0), u32((a.sampleRate > 0xffff ? 0 : a.sampleRate) * 65536), esds);
+    traks.push(trak(AUDIO_TRACK, 'audio', a.sampleRate, 0, 0, mp4a));
+    trex.push(full('trex', 0, 0, u32(AUDIO_TRACK), u32(1), u32(0), u32(0), u32(0)));
+  }
+  const mvhd = full('mvhd', 0, 0, u32(0), u32(0), u32(1000), u32(0), u32(0x00010000), u16(0x0100), u16(0), zeros(8), MATRIX, zeros(24), u32(3));
+  const ftyp = box('ftyp', ascii('isom'), u32(0x200), ...brands.map(ascii));
+  const moov = box('moov', mvhd, ...traks, box('mvex', ...trex));
+  const out = new Uint8Array(ftyp.length + moov.length);
+  out.set(ftyp, 0); out.set(moov, ftyp.length);
+  return out;
+}
+
+export type Sample = { duration: number; data: Uint8Array; key: boolean; cts?: number };
+export type Fragment = { track: number; baseTime: number; samples: Sample[] };
+
+/** A media segment: one `moof` over the fragments, then their samples in one `mdat`, video's first. */
+export function mediaSegment(sequence: number, fragments: Fragment[]): Uint8Array {
+  const present = fragments.filter((f) => f.samples.length > 0);
+  const moofOf = (offsets: number[]): Uint8Array => box('moof', full('mfhd', 0, 0, u32(sequence)), ...present.map((f, i) => {
+    const video = f.track === VIDEO_TRACK;
+    // data offset, duration, size, flags and (video) composition offset per sample; version 1 for signed offsets
+    const flags = video ? 0x000f01 : 0x000301;
+    const rows = f.samples.flatMap((s) => [
+      ...u32(s.duration), ...u32(s.data.length),
+      ...(video ? [...u32(s.key ? 0x02000000 : 0x01010000), ...u32((s.cts ?? 0) | 0)] : []),
+    ]);
+    return box('traf', full('tfhd', 0, 0x020000, u32(f.track)), full('tfdt', 1, 0, u64(f.baseTime)), full('trun', video ? 1 : 0, flags, u32(f.samples.length), u32(offsets[i]! | 0), rows));
+  }));
+  const sized = moofOf(present.map(() => 0)).length;
+  const offsets: number[] = [];
+  let at = sized + 8;
+  for (const f of present) { offsets.push(at); at += f.samples.reduce((n, s) => n + s.data.length, 0); }
+  const moof = moofOf(offsets);
+  // one buffer for the whole segment, the samples written straight into its mdat: a segment's bytes are copied once
+  const out = new Uint8Array(at);
+  out.set(moof, 0);
+  out.set([...u32(at - moof.length), ...ascii('mdat')], moof.length);
+  let to = moof.length + 8;
+  for (const f of present) for (const s of f.samples) { out.set(s.data, to); to += s.data.length; }
+  return out;
+}

package/src/live/hls.ts

@@ -0,0 +1,59 @@
+// A recording's HLS playlists (RFC 8216): the media playlist over its fragmented-MP4 segments (§4.3: EXT-X-MAP names
+// each segment's init, EXT-X-DISCONTINUITY where the init changes, EXT-X-ENDLIST once the recording ended) and a
+// multivariant playlist naming that one rendition (§4.3.4.2: its bandwidth, codecs, resolution and frame rate). Pure.
+import type { LiveAudio, LiveVideo } from './types.ts';
+
+/** A segment as the recording keeps it. */
+export type HlsSegment = { seq: number; init: number; duration: number; size: number };
+
+const DEFAULT_WINDOW = 6;
+
+/** The media playlist: the last `window` segments while the recording is published, every segment once it ended (or
+ *  with `window: 'all'`, an event playlist). */
+export function mediaPlaylist(
+  recording: { state: 'publishing' | 'ended'; window?: number },
+  segments: ReadonlyArray<HlsSegment>,
+  options: { window?: number | 'all'; uri?: (file: string) => string } = {},
+): string {
+  const uri = options.uri ?? ((file: string) => file);
+  const ended = recording.state === 'ended';
+  const window = options.window ?? recording.window ?? DEFAULT_WINDOW;
+  const listed = ended || window === 'all' ? [...segments] : segments.slice(Math.max(0, segments.length - Math.max(1, window)));
+  // every EXTINF, rounded, is at most the target (§4.3.3.1)
+  const target = Math.max(1, ...segments.map((s) => Math.round(s.duration)));
+  const first = listed[0];
+  const lines = ['#EXTM3U', '#EXT-X-VERSION:7', `#EXT-X-TARGETDURATION:${target}`, `#EXT-X-MEDIA-SEQUENCE:${first?.seq ?? 0}`];
+  // each init after the recording's first is one discontinuity: those before the window are its sequence (§4.3.3.3)
+  if (first && first.init > 0) lines.push(`#EXT-X-DISCONTINUITY-SEQUENCE:${first.init}`);
+  if (ended) lines.push('#EXT-X-PLAYLIST-TYPE:VOD');
+  else if (window === 'all') lines.push('#EXT-X-PLAYLIST-TYPE:EVENT');
+  lines.push('#EXT-X-INDEPENDENT-SEGMENTS');
+  let init: number | undefined;
+  for (const s of listed) {
+    if (s.init !== init) {
+      if (init !== undefined) lines.push('#EXT-X-DISCONTINUITY');
+      lines.push(`#EXT-X-MAP:URI="${uri(`init-${s.init}.mp4`)}"`);
+      init = s.init;
+    }
+    lines.push(`#EXTINF:${s.duration.toFixed(3)},`, uri(`seg-${s.seq}.m4s`));
+  }
+  if (ended) lines.push('#EXT-X-ENDLIST');
+  return `${lines.join('\n')}\n`;
+}
+
+/** The multivariant playlist naming the recording's one rendition, its peak bandwidth measured from its segments. */
+export function masterPlaylist(
+  recording: { video?: LiveVideo; audio?: LiveAudio },
+  segments: ReadonlyArray<HlsSegment>,
+  media: string,
+): string {
+  const peak = Math.max(1, ...segments.filter((s) => s.duration > 0).map((s) => Math.ceil((s.size * 8) / s.duration)));
+  const codecs = [recording.video?.codec, recording.audio?.codec].filter(Boolean).join(',');
+  const attributes = [
+    `BANDWIDTH=${peak}`,
+    ...(codecs ? [`CODECS="${codecs}"`] : []),
+    ...(recording.video && recording.video.width && recording.video.height ? [`RESOLUTION=${recording.video.width}x${recording.video.height}`] : []),
+    ...(recording.video?.frameRate ? [`FRAME-RATE=${recording.video.frameRate.toFixed(3)}`] : []),
+  ];
+  return `#EXTM3U\n#EXT-X-VERSION:7\n#EXT-X-INDEPENDENT-SEGMENTS\n#EXT-X-STREAM-INF:${attributes.join(',')}\n${media}\n`;
+}

package/src/live/index.ts

@@ -0,0 +1,13 @@
+// @volter/world-core/live — live media (docs/contributing/architecture.md, "Other wires": live media): RTMP ingest as
+// OBS and ffmpeg publish, recorded in the World, played back as HLS over fragmented MP4. A pack declares an ingest in its
+// manifest's `live`, writes its dialect in `semantics/live.ts` (a `LiveEngine` per ingest), serves its fetch's `ingest`
+// on a side port, and answers its media host with `ctx.live.serve`. The root exports this module as `live`.
+export type { LiveAccess, LiveAdmission, LiveAudio, LiveDecl, LiveEngine, LivePublish, LiveRecording, LiveRefusal, LiveServeOptions, LiveVideo } from './types.ts';
+export { liveIngest, type LiveIngestOptions, type LiveWorld } from './ingest.ts';
+export { liveAccess, LIVE, LIVE_SEGMENT, type LiveReads } from './access.ts';
+export { masterPlaylist, mediaPlaylist, type HlsSegment } from './hls.ts';
+export { rtmpSession, type RtmpPublisher } from './rtmp.ts';
+export { decodeAmf0, encodeAmf0, type Amf0Value } from './amf0.ts';
+export { readAudioTag, readVideoTag, type AacConfig, type AudioTag, type AvcConfig, type VideoTag } from './flv.ts';
+export { initSegment, mediaSegment, type Fragment, type Sample } from './fmp4.ts';
+export { Segmenter, type Cut } from './segmenter.ts';