@playola-radio/slipstream 0.1.0

package/dist/sibling-module.js

@@ -0,0 +1,10 @@
+/**
+ * URL of a sibling module (given without extension) that a worker or child
+ * process will load. Source runs as `.ts`; the published package ships compiled
+ * `.js`, and `tsc` does not rewrite extensions inside `new URL(...)`, so the
+ * extension is taken from the calling module's own URL.
+ */
+export function siblingModuleUrl(name, callerUrl) {
+    const ext = callerUrl.endsWith('.ts') ? '.ts' : '.js';
+    return new URL(`./${name}${ext}`, callerUrl);
+}

package/dist/snapshot.js

@@ -0,0 +1,15 @@
+/**
+ * True when two *consecutive* observations carry the same information and the
+ * later one should be suppressed. This is deliberately not global content
+ * dedup: an A -> B -> A cycle produces two real transitions because each
+ * comparison is only against the immediately preceding committed state.
+ */
+export function snapshotsEqual(a, b) {
+    if (a.kind !== b.kind)
+        return false;
+    if (a.kind === 'content' && b.kind === 'content')
+        return a.sha256 === b.sha256;
+    if (a.kind === 'unavailable' && b.kind === 'unavailable')
+        return a.reason === b.reason;
+    return true; // absent === absent
+}

package/dist/storage.js

@@ -0,0 +1,111 @@
+import { access, lstat, mkdir, open } from 'node:fs/promises';
+import { dirname } from 'node:path';
+/** Owner-only permissions for everything Slipstream writes (captured source bytes). */
+export const DIR_MODE = 0o700;
+export const FILE_MODE = 0o600;
+/**
+ * A storage-layer failure (ENOSPC, quota, permission, I/O). Distinct from a
+ * source-file read problem: a full or broken *store* must never be laundered
+ * into an `unavailable` snapshot — that would fabricate a coverage claim. The
+ * `code` mirrors the OS errno so callers can single out ENOSPC/EDQUOT.
+ */
+export class StorageError extends Error {
+    code;
+    operation;
+    constructor(operation, cause) {
+        const code = cause?.code;
+        super(`storage ${operation} failed${code ? ` (${code})` : ''}`, { cause });
+        this.name = 'StorageError';
+        this.code = code;
+        this.operation = operation;
+    }
+}
+/** fsync a directory so a newly created/renamed entry within it is durable. */
+export async function fsyncDir(dir) {
+    let handle;
+    try {
+        handle = await open(dir, 'r');
+        await handle.sync();
+    }
+    catch (err) {
+        throw new StorageError(`fsync-dir(${dir})`, err);
+    }
+    finally {
+        await handle?.close();
+    }
+}
+/**
+ * Write the whole buffer, looping on short writes. A single `handle.write` may
+ * commit fewer bytes than requested under storage pressure; a truncated line
+ * would corrupt every record after it, so the loop is not optional.
+ */
+export async function writeAll(handle, buf) {
+    let offset = 0;
+    while (offset < buf.length) {
+        const { bytesWritten } = await handle.write(buf, offset, buf.length - offset);
+        if (bytesWritten <= 0)
+            throw new Error('write made no progress');
+        offset += bytesWritten;
+    }
+}
+/**
+ * Create `dir` and any missing ancestors 0700, fsyncing each newly-created
+ * directory's parent so the new entry is durable. `mkdir(recursive)` alone does
+ * not flush parent directory entries — a crash could lose an acknowledged blob
+ * or leave a surviving event pointing at a directory that never made it to disk.
+ */
+export async function mkdirpDurable(dir) {
+    const missing = [];
+    let cur = dir;
+    for (;;) {
+        try {
+            await access(cur);
+            break;
+        }
+        catch {
+            missing.push(cur);
+        }
+        const parent = dirname(cur);
+        if (parent === cur)
+            break;
+        cur = parent;
+    }
+    try {
+        for (const d of missing.reverse()) {
+            try {
+                await mkdir(d, { mode: DIR_MODE });
+            }
+            catch (err) {
+                if (err.code !== 'EEXIST')
+                    throw err;
+                continue; // a concurrent creator won; nothing new to flush here
+            }
+            await fsyncDir(dirname(d)); // persist the new entry in its parent
+        }
+    }
+    catch (err) {
+        throw err instanceof StorageError ? err : new StorageError(`mkdirp(${dir})`, err);
+    }
+}
+/**
+ * Reject a storage path that is not exclusively the owner's: a symlink (could
+ * redirect writes outside the store), group/other-accessible modes, or a
+ * different owner. The store holds real captured source bytes, so lax
+ * permissions on an *existing* path are a hard startup error (Q5).
+ */
+export async function assertOwnerOnly(path, kind) {
+    const st = await lstat(path);
+    if (st.isSymbolicLink()) {
+        throw new StorageError(`insecure-path(${path})`, new Error('storage path is a symlink'));
+    }
+    if (kind === 'dir' ? !st.isDirectory() : !st.isFile()) {
+        throw new StorageError(`insecure-path(${path})`, new Error(`storage path is not a ${kind}`));
+    }
+    if ((st.mode & 0o077) !== 0) {
+        throw new StorageError(`insecure-path(${path})`, new Error('storage path is group/other-accessible'));
+    }
+    const uid = process.getuid?.();
+    if (uid !== undefined && st.uid !== uid) {
+        throw new StorageError(`insecure-path(${path})`, new Error('storage path is owned by another user'));
+    }
+}

package/dist/store-reader.js

@@ -0,0 +1,185 @@
+import { constants } from 'node:fs';
+import { readdir, readFile, open } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { PUBLIC_EVENT_TYPES as EVENT_TYPES } from "./public-events.js";
+import { LogCorruptError } from "./log-reader.js";
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const HEX_RE = /^[0-9a-f]{64}$/;
+const SEQ_RE = /^[1-9][0-9]*$/;
+const SCHEMAS_DIR = fileURLToPath(new URL('../schemas/', import.meta.url));
+const PROJECTIONS_DIR = fileURLToPath(new URL('../schemas/projections/', import.meta.url));
+const INTERFACE_SCHEMA = fileURLToPath(new URL('../contracts/interface/v2/schema.json', import.meta.url));
+/** The published projection schemas, by projection_version. Not gated to
+ *  EVENT_TYPES: a projection is a reader-derived view, not a log event. */
+const PROJECTION_SCHEMAS = new Set(['clip.v1', 'clip.v2', 'clip.v3']);
+export function isValidSessionId(id) { return UUID_RE.test(id); }
+export function isValidHex(hex) { return HEX_RE.test(hex); }
+function sessionsDir(storeDir) { return join(storeDir, 'sessions'); }
+export function sessionLogPath(storeDir, id) {
+    return join(sessionsDir(storeDir), id, 'events.jsonl');
+}
+export function tombstonePath(storeDir, id) {
+    return join(sessionsDir(storeDir), id, 'removed.json');
+}
+export function blobPath(storeDir, hex) {
+    return join(storeDir, 'blobs', 'sha256', hex.slice(0, 2), hex);
+}
+export async function onDiskHighWater(logPath) {
+    let handle;
+    try {
+        handle = await open(logPath, 'r');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return 0n;
+        throw err;
+    }
+    let lastLine;
+    try {
+        // Scan backwards in fixed-size windows, discarding a torn tail without
+        // retaining it. Only the final complete record needs to be assembled.
+        let pos = (await handle.stat()).size;
+        let foundEnd = false;
+        const pieces = [];
+        while (pos > 0) {
+            const size = Math.min(pos, 64 * 1024);
+            pos -= size;
+            const buffer = Buffer.allocUnsafe(size);
+            const { bytesRead } = await handle.read(buffer, 0, size, pos);
+            if (bytesRead !== size)
+                throw new LogCorruptError('high-water: log truncated during read');
+            let end = size;
+            if (!foundEnd) {
+                end = buffer.lastIndexOf(0x0a);
+                if (end < 0)
+                    continue;
+                foundEnd = true;
+            }
+            const start = end > 0 ? buffer.lastIndexOf(0x0a, end - 1) : -1;
+            pieces.push(buffer.subarray(start + 1, end));
+            if (start >= 0)
+                break;
+        }
+        if (!foundEnd)
+            return 0n;
+        lastLine = Buffer.concat(pieces.reverse()).toString('utf8');
+    }
+    finally {
+        await handle.close();
+    }
+    if (lastLine === '')
+        throw new LogCorruptError('high-water: blank final record');
+    let seq;
+    try {
+        seq = JSON.parse(lastLine).seq;
+    }
+    catch {
+        throw new LogCorruptError('high-water: invalid JSON in final record');
+    }
+    if (typeof seq !== 'string' || !SEQ_RE.test(seq)) {
+        throw new LogCorruptError('high-water: final record has no valid decimal-string seq');
+    }
+    return BigInt(seq);
+}
+export async function readTombstone(storeDir, id) {
+    try {
+        const raw = await readFile(tombstonePath(storeDir, id), 'utf8');
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+        return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+            && parsed.version === 1 ? { version: 1 } : null;
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+}
+export async function listSessions(storeDir) {
+    let entries;
+    try {
+        entries = await readdir(sessionsDir(storeDir));
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    const out = [];
+    for (const id of entries) {
+        if (!isValidSessionId(id))
+            continue;
+        const removed = (await readTombstone(storeDir, id)) !== null;
+        // A removed session advertises no history. Short-circuit to 0 without reading
+        // high-water: a delete interrupted before cleanup can leave a corrupt residual
+        // log under a durable tombstone, and that must never break listing.
+        const durableSeq = removed ? 0n : await onDiskHighWater(sessionLogPath(storeDir, id));
+        out.push({ id, durableSeq, removed });
+    }
+    out.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    return out;
+}
+export async function schemaBytes(type) {
+    if (!EVENT_TYPES.includes(type))
+        return null;
+    return readFile(join(SCHEMAS_DIR, `${type}.json`));
+}
+export async function projectionSchemaBytes(version) {
+    if (version === 'interface.v2')
+        return readFile(INTERFACE_SCHEMA);
+    if (!PROJECTION_SCHEMAS.has(version))
+        return null;
+    return readFile(join(PROJECTIONS_DIR, `${version}.json`));
+}
+export async function readRuntimeDescriptor(storeDir) {
+    const dir = join(storeDir, 'runtime');
+    let files;
+    try {
+        files = (await readdir(dir)).filter((f) => f.endsWith('.json'));
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+    let newest = null;
+    let newestMs = -1;
+    for (const f of files) {
+        // Validate the same fd we read; never follow symlinks or block on a FIFO.
+        let handle;
+        try {
+            handle = await open(join(dir, f), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+            const info = await handle.stat();
+            if (!info.isFile() || (info.mode & 0o077) !== 0
+                || (process.getuid && info.uid !== process.getuid()))
+                continue;
+            const parsed = JSON.parse(await handle.readFile('utf8'));
+            if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+                continue;
+            const { url, token } = parsed;
+            if (typeof url !== 'string' || typeof token !== 'string')
+                continue;
+            const origin = new URL(url);
+            if (origin.protocol !== 'http:' || !['127.0.0.1', '[::1]', 'localhost'].includes(origin.hostname)
+                || origin.username || origin.password || origin.pathname !== '/' || origin.search || origin.hash)
+                continue;
+            if (info.mtimeMs > newestMs) {
+                newestMs = info.mtimeMs;
+                newest = { url, token };
+            }
+        }
+        catch {
+            // A stale, inaccessible or malformed candidate must not hide a usable one.
+        }
+        finally {
+            await handle?.close();
+        }
+    }
+    return newest;
+}

package/dist/swift-grammar.js

@@ -0,0 +1,268 @@
+/**
+ * Loads the pinned Swift Tree-sitter grammar through the existing web-tree-sitter
+ * runtime and reports parse diagnostics with UTF-8 byte spans. This is the
+ * T5a.3 feasibility loader (STAGE-T-PREREQS 3.3): it proves the bundled artifact
+ * loads and parses; it does NOT extract declarations or make any comparison
+ * claim (that is T5a.4).
+ *
+ * IMPORTANT: loading + parsing this grammar deterministically aborts a default
+ * Node process a second or two later, inside V8's optimizing WASM compiler
+ * (turboshaft) with `Fatal process out of memory: Zone`. The only mitigation
+ * found is launching the host process with `node --liftoff-only` (single-tier
+ * baseline WASM); workers inherit it. So `loadSwiftLanguage`/`parseSwiftSource`
+ * must only ever execute inside such a process (see src/swift-parse-host.ts).
+ * Merely importing this module is safe — nothing here initializes eagerly, not
+ * even resolving the artifact path — and `loadSwiftLanguage` refuses to run
+ * outside a `--liftoff-only` process so an accidental in-process load fails loud
+ * instead of aborting the host a second later.
+ */
+import { createRequire } from 'node:module';
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { Parser, Language, LANGUAGE_VERSION, MIN_COMPATIBLE_VERSION } from 'web-tree-sitter';
+import { buildUtf16ToByteTable, utf16RangeToByteRange } from "./swift-spans.js";
+const require = createRequire(import.meta.url);
+/** Package specifier for the bundled artifact, resolved lazily (see
+ * `swiftWasmPath`) so importing this module never touches the filesystem. */
+const SWIFT_WASM_SPECIFIER = 'tree-sitter-wasms/out/tree-sitter-swift.wasm';
+/** Env escape that lets a NON-`--liftoff-only` process load the grammar anyway.
+ * Set by ONLY the OOM negative control (src/swift-parse.ts), which must reach
+ * the load to prove the default launch aborts. Nothing else should set it. */
+export const SWIFT_UNISOLATED_ENV = 'SLIPSTREAM_SWIFT_ALLOW_UNISOLATED';
+/** sha256 of the pinned WASM — the artifact's exact identity. The npm range the
+ * wrapper declares (`^0.4.0`) is not an exact grammar revision, so this hash,
+ * not a version string, is the real pin. */
+export const EXPECTED_SHA256 = '41c4fdb2249a3aa6d87eed0d383081ff09725c2248b4977043a43825980ffcc7';
+/** ABI version the pinned artifact must report. */
+export const EXPECTED_ABI = 13;
+/** Static provenance. The grammar and its wrapper carry DIFFERENT licenses and
+ * must not be conflated. The exact grammar revision that produced this WASM is
+ * not recoverable from the distributed artifact (the wrapper ships only `/out`,
+ * no lockfile), so it is honestly recorded as "unknown". */
+export const GRAMMAR = {
+    package: 'tree-sitter-swift',
+    repo: 'https://github.com/alex-pinkus/tree-sitter-swift',
+    versionRange: '^0.4.0',
+    revision: 'unknown',
+    license: 'MIT',
+};
+export const WRAPPER = {
+    package: 'tree-sitter-wasms',
+    license: 'Unlicense',
+};
+/** A load/verification failure with the full context needed to diagnose it.
+ * Never caught-and-ignored: the loader never silently falls back. */
+export class SwiftArtifactError extends Error {
+    detail;
+    constructor(message, detail, options) {
+        super(message, options);
+        this.name = 'SwiftArtifactError';
+        this.detail = detail;
+    }
+}
+/** Resolve the bundled WASM path lazily, wrapping a resolution failure as a
+ * `SwiftArtifactError` (never a raw `MODULE_NOT_FOUND`). Memoized. Called only
+ * from `loadSwiftLanguage`, so a missing install surfaces as the host's exit-2
+ * artifact failure rather than an uncaught throw during module import. */
+let wasmPathCache;
+export function swiftWasmPath() {
+    if (wasmPathCache)
+        return wasmPathCache;
+    try {
+        wasmPathCache = require.resolve(SWIFT_WASM_SPECIFIER);
+    }
+    catch (error) {
+        throw new SwiftArtifactError('pinned Swift WASM not found', {
+            specifier: SWIFT_WASM_SPECIFIER,
+        }, { cause: error });
+    }
+    return wasmPathCache;
+}
+/** Refuse to load the grammar outside a `--liftoff-only` process. Loading here
+ * would abort the process a second later inside V8's WASM tier-up (see the file
+ * header); failing fast keeps the boundary real instead of by convention. The
+ * `--liftoff-only` flag is inherited by worker threads (verified). */
+function assertIsolatedProcess() {
+    if (process.execArgv.includes('--liftoff-only'))
+        return;
+    if (process.env[SWIFT_UNISOLATED_ENV] === '1')
+        return;
+    throw new SwiftArtifactError('refusing to load the Swift grammar outside a --liftoff-only process', {
+        execArgv: process.execArgv,
+        hint: 'load via runSwiftParseChild (src/swift-parse.ts), which spawns the isolated host',
+    });
+}
+/** Fail loudly if the bytes on disk are not the pinned artifact. Pure so the
+ * mismatch path is unit-testable without touching the WASM runtime. */
+export function verifyArtifactHash(actualSha, expectedSha, path) {
+    if (actualSha !== expectedSha) {
+        throw new SwiftArtifactError('Swift WASM sha256 mismatch', {
+            path,
+            expectedSha256: expectedSha,
+            actualSha256: actualSha,
+        });
+    }
+}
+/** Fail loudly on an ABI outside the runtime's supported range, or not exactly
+ * the pinned ABI. Pure so both failure paths are unit-testable. */
+export function checkAbi(actual, expected, supported, ctx) {
+    if (actual < supported.min || actual > supported.max) {
+        throw new SwiftArtifactError('Swift grammar ABI outside runtime compatibility range', {
+            ...ctx,
+            actualAbi: actual,
+            supportedAbi: supported,
+        });
+    }
+    if (actual !== expected) {
+        throw new SwiftArtifactError('Swift grammar ABI is not the pinned version', {
+            ...ctx,
+            actualAbi: actual,
+            expectedAbi: expected,
+            supportedAbi: supported,
+        });
+    }
+}
+function installedVersion(pkg) {
+    // Some packages (web-tree-sitter) block `./package.json` in their exports map,
+    // so resolve the package entry and walk up to the nearest package.json instead.
+    try {
+        return readVersionAt(require.resolve(`${pkg}/package.json`));
+    }
+    catch {
+        try {
+            let dir = dirname(require.resolve(pkg));
+            for (;;) {
+                const candidate = join(dir, 'package.json');
+                if (existsSync(candidate)) {
+                    const v = readVersionAt(candidate);
+                    if (v !== 'unknown')
+                        return v;
+                }
+                const parent = dirname(dir);
+                if (parent === dir)
+                    break;
+                dir = parent;
+            }
+        }
+        catch {
+            // fall through to 'unknown'
+        }
+        return 'unknown';
+    }
+}
+function readVersionAt(pkgJsonPath) {
+    const json = JSON.parse(readFileSync(pkgJsonPath, 'utf8'));
+    return json.version ?? 'unknown';
+}
+let initPromise;
+/** Cache the one web-tree-sitter runtime init, matching the clip parser's
+ * pattern. Swift runs isolated in its own process, so there is no in-process
+ * clip parser to double-init with. */
+function ensureInit() {
+    initPromise ??= Parser.init().catch((error) => {
+        initPromise = undefined;
+        throw error;
+    });
+    return initPromise;
+}
+/** Read → hash → verify → load the SAME bytes → verify ABI. Hashing the bytes
+ * that are actually loaded (rather than hashing a path and re-reading it) closes
+ * the verification gap Codex flagged. */
+export async function loadSwiftLanguage() {
+    assertIsolatedProcess();
+    const path = swiftWasmPath();
+    const bytes = readFileSync(path);
+    const sha256 = createHash('sha256').update(bytes).digest('hex');
+    verifyArtifactHash(sha256, EXPECTED_SHA256, path);
+    await ensureInit();
+    const supported = { min: MIN_COMPATIBLE_VERSION, max: LANGUAGE_VERSION };
+    let language;
+    try {
+        language = await Language.load(bytes);
+    }
+    catch (error) {
+        throw new SwiftArtifactError('Language.load failed for the Swift WASM', {
+            path,
+            sha256,
+            supportedAbi: supported,
+        }, { cause: error });
+    }
+    const abiVersion = language.abiVersion;
+    // The compatibility-range check lives in setLanguage(); run it explicitly so
+    // an incompatible grammar fails here with full context, never at first parse.
+    const probe = new Parser();
+    try {
+        probe.setLanguage(language);
+    }
+    catch (error) {
+        probe.delete();
+        throw new SwiftArtifactError('Parser.setLanguage rejected the Swift grammar ABI', {
+            path,
+            sha256,
+            abiVersion,
+            supportedAbi: supported,
+        }, { cause: error });
+    }
+    probe.delete();
+    checkAbi(abiVersion, EXPECTED_ABI, supported, { path, sha256 });
+    return {
+        language,
+        provenance: {
+            path,
+            sha256,
+            abiVersion,
+            supportedAbi: supported,
+            grammar: GRAMMAR,
+            wrapper: { package: WRAPPER.package, version: installedVersion(WRAPPER.package), license: WRAPPER.license },
+            webTreeSitter: { package: 'web-tree-sitter', version: installedVersion('web-tree-sitter') },
+        },
+    };
+}
+/** Parse Swift source and collect its ERROR/MISSING diagnostics with byte spans.
+ * Visits EVERY node (including anonymous missing tokens), so no nested defect is
+ * hidden. `clean` is true only when the whole tree is free of ERROR/MISSING. */
+export function parseSwiftSource(language, source) {
+    const parser = new Parser();
+    let tree = null;
+    try {
+        parser.setLanguage(language);
+        tree = parser.parse(source);
+        if (!tree)
+            throw new Error('parser returned no tree');
+        const table = buildUtf16ToByteTable(source);
+        const diagnostics = [];
+        const stack = [tree.rootNode];
+        while (stack.length) {
+            const node = stack.pop();
+            if (node.isError || node.isMissing) {
+                const { byteStart, byteEnd } = utf16RangeToByteRange(table, node.startIndex, node.endIndex);
+                diagnostics.push({
+                    kind: node.isMissing ? 'missing' : 'error',
+                    nodeType: node.type,
+                    byteStart,
+                    byteEnd,
+                    startRow: node.startPosition.row,
+                    startColumn: node.startPosition.column,
+                    endRow: node.endPosition.row,
+                    endColumn: node.endPosition.column,
+                });
+            }
+            for (let i = node.childCount - 1; i >= 0; i--) {
+                const child = node.child(i);
+                if (child)
+                    stack.push(child);
+            }
+        }
+        diagnostics.sort((a, b) => a.byteStart - b.byteStart || a.byteEnd - b.byteEnd || a.kind.localeCompare(b.kind) || a.nodeType.localeCompare(b.nodeType));
+        const rootType = tree.rootNode.type;
+        const hasError = tree.rootNode.hasError;
+        // clean requires BOTH signals to agree; disagreement is a defect, not "clean".
+        const clean = diagnostics.length === 0 && !hasError;
+        return { rootType, clean, diagnostics, byteLength: table.bytes[table.length] };
+    }
+    finally {
+        tree?.delete();
+        parser.delete();
+    }
+}