@playola-radio/slipstream 0.1.0

package/dist/http-security.js

@@ -0,0 +1,50 @@
+import { randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+import { open, rename } from 'node:fs/promises';
+import { join } from 'node:path';
+import { mkdirpDurable, writeAll, fsyncDir, FILE_MODE } from "./storage.js";
+export function generateToken() { return randomBytes(32).toString('hex'); }
+export async function publishDescriptor(storeDir, descriptor) {
+    const dir = join(storeDir, 'runtime');
+    await mkdirpDurable(dir);
+    const path = join(dir, `${randomUUID()}.json`);
+    const tmp = `${path}.tmp`;
+    const body = Buffer.from(JSON.stringify(descriptor), 'utf8');
+    const handle = await open(tmp, 'wx', FILE_MODE);
+    try {
+        await writeAll(handle, body);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await rename(tmp, path);
+    await fsyncDir(dir);
+    return path;
+}
+export function checkAuth(header, token) {
+    if (typeof header !== 'string')
+        return false;
+    const prefix = 'Bearer ';
+    if (!header.startsWith(prefix))
+        return false;
+    const got = Buffer.from(header.slice(prefix.length));
+    const want = Buffer.from(token);
+    if (got.length !== want.length)
+        return false;
+    return timingSafeEqual(got, want);
+}
+export function checkHostOrigin(headers, expectedHostPort, hostCount = 1) {
+    // Node collapses duplicate Host headers to the first in `headers.host`; reject
+    // if the client actually sent more than one (mirrors the Origin handling).
+    if (hostCount > 1)
+        return false;
+    const host = headers.host;
+    if (typeof host !== 'string' || host !== expectedHostPort)
+        return false;
+    const origin = headers.origin;
+    if (origin === undefined)
+        return true;
+    if (typeof origin !== 'string')
+        return false;
+    return origin === `http://${expectedHostPort}`;
+}

package/dist/interface-projection.js

@@ -0,0 +1,243 @@
+/**
+ * The language-neutral core of the `interface.v1` projection: the declaration /
+ * identity model, the D3 correspondence algorithm, the D10 status-precedence
+ * table, D8 row ordering, and the response-envelope builder.
+ *
+ * This module is pure and has **zero imports** — no parser, no tree-sitter, no
+ * worker, no I/O, and zero language branches. Per-language extraction feeds it
+ * `Declaration`s and dispositions; how those are produced is not its concern.
+ * See INTERFACE-PROJECTION.md for the full contract.
+ */
+const INTERFACE_PROJECTION_VERSION = 'interface.v1';
+// ---- Keys ------------------------------------------------------------------
+/**
+ * A collision-free string for an identity. Uses `JSON.stringify` over a
+ * fixed-order structure so distinct identities never alias (JSON quoting makes
+ * the encoding injective — unlike a delimiter join).
+ */
+function groupingKey(id) {
+    return JSON.stringify([
+        id.kind,
+        id.scope.map((s) => [s.kind, s.name]),
+        id.name,
+        id.guards,
+    ]);
+}
+/** Identity plus signature: two declarations "are the same" iff these match. */
+function exactKey(d) {
+    return JSON.stringify([groupingKey(d.identity), d.signature]);
+}
+export function hasDuplicate(decls) {
+    const seen = new Set();
+    for (const d of decls) {
+        const k = exactKey(d);
+        if (seen.has(k))
+            return true;
+        seen.add(k);
+    }
+    return false;
+}
+/**
+ * Correspond two declaration lists. Callers must have already ruled out
+ * per-side duplicates (status precedence 3); this assumes each `exactKey`
+ * occurs at most once per side.
+ */
+export function compare(before, after) {
+    const beforeExact = new Set(before.map(exactKey));
+    const afterExact = new Set(after.map(exactKey));
+    const unmatchedBefore = before.filter((d) => !afterExact.has(exactKey(d)));
+    const unmatchedAfter = after.filter((d) => !beforeExact.has(exactKey(d)));
+    const groups = new Map();
+    const groupOf = (d) => {
+        const k = groupingKey(d.identity);
+        let g = groups.get(k);
+        if (!g)
+            groups.set(k, (g = { before: [], after: [] }));
+        return g;
+    };
+    for (const d of unmatchedBefore)
+        groupOf(d).before.push(d);
+    for (const d of unmatchedAfter)
+        groupOf(d).after.push(d);
+    const changes = [];
+    for (const { before: b, after: a } of groups.values()) {
+        if (b.length > 0 && a.length > 0) {
+            if (b.length === 1 && a.length === 1) {
+                changes.push(signatureChangedRow(b[0], a[0]));
+            }
+            else {
+                return { ambiguous: true };
+            }
+        }
+        else if (b.length > 0) {
+            for (const d of b)
+                changes.push(removedRow(d));
+        }
+        else {
+            for (const d of a)
+                changes.push(addedRow(d));
+        }
+    }
+    changes.sort(compareRows);
+    return { ambiguous: false, changes };
+}
+function outDecl(d) {
+    return {
+        kind: d.identity.kind,
+        display_name: d.displayName,
+        signature: d.signature,
+        span: { byte_start: d.span.byteStart, byte_end: d.span.byteEnd },
+    };
+}
+function outIdentity(id) {
+    return {
+        kind: id.kind,
+        scope: id.scope.map((s) => ({ kind: s.kind, name: s.name })),
+        name: id.name,
+        guards: [...id.guards],
+    };
+}
+function removedRow(d) {
+    return { kind: 'removed', identity: outIdentity(d.identity), before: outDecl(d), after: null };
+}
+function addedRow(d) {
+    return { kind: 'added', identity: outIdentity(d.identity), before: null, after: outDecl(d) };
+}
+function signatureChangedRow(b, a) {
+    return {
+        kind: 'signatureChanged',
+        identity: outIdentity(b.identity),
+        before: outDecl(b),
+        after: outDecl(a),
+    };
+}
+/** UTF-16 code-unit strings, numeric offsets, lexicographic arrays (shorter
+ * prefix first). No normalization, no locale. */
+function cmp(a, b) {
+    if (typeof a === 'string' && typeof b === 'string')
+        return a < b ? -1 : a > b ? 1 : 0;
+    if (typeof a === 'number' && typeof b === 'number')
+        return a < b ? -1 : a > b ? 1 : 0;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        const n = Math.min(a.length, b.length);
+        for (let i = 0; i < n; i++) {
+            const c = cmp(a[i], b[i]);
+            if (c !== 0)
+                return c;
+        }
+        return a.length - b.length;
+    }
+    throw new Error('interface projection: cmp type mismatch');
+}
+const KIND_RANK = { removed: 0, signatureChanged: 1, added: 2 };
+/** The D(d) ordering tuple for one output declaration. */
+function orderTuple(d, id) {
+    const scopePairs = id.scope.flatMap((s) => [s.kind, s.name]);
+    return [
+        d.display_name,
+        d.signature,
+        id.kind,
+        scopePairs,
+        id.name,
+        id.guards,
+        d.span.byte_start,
+        d.span.byte_end,
+    ];
+}
+function anchor(row) {
+    return row.kind === 'added' ? row.after : row.before;
+}
+function counterpart(row) {
+    return row.kind === 'signatureChanged' ? row.after : null;
+}
+function compareRows(x, y) {
+    const byKind = KIND_RANK[x.kind] - KIND_RANK[y.kind];
+    if (byKind !== 0)
+        return byKind;
+    const byAnchor = cmp(orderTuple(anchor(x), x.identity), orderTuple(anchor(y), y.identity));
+    if (byAnchor !== 0)
+        return byAnchor;
+    const cx = counterpart(x);
+    const cy = counterpart(y);
+    if (cx === null && cy === null)
+        return 0;
+    if (cx === null)
+        return -1; // null counterpart sorts first
+    if (cy === null)
+        return 1;
+    return cmp(orderTuple(cx, x.identity), orderTuple(cy, y.identity));
+}
+// ---- Status precedence (D10) + envelope ------------------------------------
+function coverageSide(side, input) {
+    switch (side.status) {
+        case 'complete':
+            return { state: 'complete' };
+        case 'absent':
+            return { state: 'absent' };
+        case 'incomplete':
+            return { state: 'incomplete', reason: side.reason };
+        case 'unavailable':
+            return { state: 'unavailable', reason: side.reason };
+        case 'notEvaluated':
+            if (!input.admission && input.language === null)
+                return { state: 'unsupported' };
+            return { state: 'notEvaluated' };
+    }
+}
+function classify(input) {
+    const { before, after } = input;
+    if (before.status === 'incomplete')
+        return { status: 'incomplete', reason: before.reason, changes: [] };
+    if (after.status === 'incomplete')
+        return { status: 'incomplete', reason: after.reason, changes: [] };
+    if (before.status === 'complete' && hasDuplicate(before.declarations)) {
+        return { status: 'incomplete', reason: 'duplicate-declaration', changes: [] };
+    }
+    if (after.status === 'complete' && hasDuplicate(after.declarations)) {
+        return { status: 'incomplete', reason: 'duplicate-declaration', changes: [] };
+    }
+    // Ambiguity outranks unavailable/unsupported/admission, but it can only be
+    // judged when both sides are comparable; compute the correspondence here and
+    // hold its rows for the ready fallback, which is the lowest-precedence outcome.
+    const bComparable = before.status === 'complete' || before.status === 'absent';
+    const aComparable = after.status === 'complete' || after.status === 'absent';
+    let ready = null;
+    if (bComparable && aComparable) {
+        const bd = before.status === 'complete' ? before.declarations : [];
+        const ad = after.status === 'complete' ? after.declarations : [];
+        const result = compare(bd, ad);
+        if (result.ambiguous)
+            return { status: 'incomplete', reason: 'ambiguous-correspondence', changes: [] };
+        ready = result.changes;
+    }
+    if (before.status === 'unavailable')
+        return { status: 'unavailable', reason: before.reason, changes: [] };
+    if (after.status === 'unavailable')
+        return { status: 'unavailable', reason: after.reason, changes: [] };
+    if (input.language === null)
+        return { status: 'unsupported', reason: 'unsupported-language', changes: [] };
+    if (input.admission)
+        return { status: 'skipped', reason: input.admission, changes: [] };
+    // ready is last: a successful comparison is only reported when nothing else applied.
+    if (ready !== null)
+        return { status: 'ready', changes: ready };
+    throw new Error('interface projection: incoherent disposition inputs');
+}
+export function buildInterfaceProjection(input) {
+    const { status, reason, changes } = classify(input);
+    const projection = {
+        change_seq: input.changeSeq,
+        projection_version: INTERFACE_PROJECTION_VERSION,
+        language: input.language,
+        language_version: input.languageVersion,
+        status,
+        coverage: {
+            before: coverageSide(input.before, input),
+            after: coverageSide(input.after, input),
+        },
+        changes,
+    };
+    if (status !== 'ready')
+        projection.fallback_reason = reason;
+    return projection;
+}

package/dist/interface-range-resolver.js

@@ -0,0 +1,230 @@
+/** Resolve recorded file identities for one frozen pair of session cutoffs.
+ * FD4 owns blob retention, extraction, response pagination and HTTP mapping. */
+import { openLogCursor, LogCorruptError, LogReadAbortedError, LogReadLimitError } from "./log-reader.js";
+import { assertSafePath } from "./recovery.js";
+import { sourceFor } from "./event.js";
+const BASELINED = 'slipstream.file.baselined.v1';
+const CHANGED = 'slipstream.file.changed.v1';
+const COMPLETED = 'slipstream.capture.baseline.completed.v1';
+const GAP = 'slipstream.capture.gap.v1';
+const SHA = /^[0-9a-f]{64}$/;
+const SEQ = /^[1-9][0-9]*$/;
+const POLICY_EXCLUSIONS = ['store-directory', '.git', 'symlinks'];
+function corrupt(message) { throw new LogCorruptError(`interface range: ${message}`); }
+function object(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function snapshot(value, seq) {
+    if (!object(value))
+        corrupt(`bad snapshot at ${seq}`);
+    if (value.kind === 'absent')
+        return { kind: 'absent' };
+    if (value.kind === 'content' && typeof value.sha256 === 'string' && SHA.test(value.sha256)
+        && typeof value.size === 'number' && Number.isSafeInteger(value.size) && value.size >= 0) {
+        return { kind: 'content', sha256: value.sha256, size: value.size };
+    }
+    if (value.kind === 'unavailable' && typeof value.reason === 'string'
+        && ['oversize', 'unreadable', 'unstable', 'io-error', 'baseline-unknown'].includes(value.reason)) {
+        return { kind: 'unavailable', reason: value.reason };
+    }
+    return corrupt(`bad snapshot at ${seq}`);
+}
+function sameRecordedState(a, b) {
+    // The v2 fixture validator compares both content hash and recorded size for
+    // predecessor integrity. Recovery's equality helper suppresses observations
+    // by hash alone; it has a different purpose.
+    if (a.kind !== b.kind)
+        return false;
+    if (a.kind === 'content' && b.kind === 'content')
+        return a.sha256 === b.sha256 && a.size === b.size;
+    if (a.kind === 'unavailable' && b.kind === 'unavailable')
+        return a.reason === b.reason;
+    return true;
+}
+function endpoint(record, field) {
+    const result = {
+        kind: 'recorded', record_seq: record.seq, field, snapshot: snapshot(record.data[field], record.seq),
+    };
+    if (record.type === CHANGED) {
+        result.observation = record.data.observation;
+        if (record.data.gap_ref !== undefined)
+            result.gap_ref = record.data.gap_ref;
+    }
+    return result;
+}
+function stateEndpoint(record) {
+    return endpoint(record, record.type === BASELINED ? 'snapshot' : 'after');
+}
+function endpointsEqual(before, after) {
+    if (before.kind !== 'recorded')
+        return false;
+    if (before.snapshot.kind === 'absent' && after.snapshot.kind === 'absent')
+        return true;
+    return before.snapshot.kind === 'content' && after.snapshot.kind === 'content'
+        && before.snapshot.sha256 === after.snapshot.sha256;
+}
+function checkPath(value, seq) {
+    if (typeof value !== 'string' || value.includes('\0'))
+        corrupt(`bad path at ${seq}`);
+    try {
+        assertSafePath(value, `record ${seq}`);
+    }
+    catch {
+        corrupt(`unsafe path at ${seq}`);
+    }
+    return value;
+}
+function checkGap(data, seq) {
+    if (!['coalesced', 'baseline-unreadable', 'watcher-error', 'restart', 'storage'].includes(data.reason)
+        || !object(data.scope))
+        corrupt(`bad gap at ${seq}`);
+    const scope = data.scope;
+    if (scope.kind === 'session')
+        return { seq, reason: data.reason, scope: { kind: 'session' } };
+    if ((scope.kind !== 'directory' && scope.kind !== 'path') || typeof scope.path !== 'string'
+        || scope.path.includes('\0') || (scope.kind === 'path' && scope.path === ''))
+        corrupt(`bad gap scope at ${seq}`);
+    if (scope.path !== '')
+        checkPath(scope.path, seq);
+    return { seq, reason: data.reason, scope: { kind: scope.kind, path: scope.path } };
+}
+/** A bounded scan of the public log through A. No live worktree or Git access. */
+export async function resolveRecordedRange(options) {
+    const { logPath, sessionId, durableSeq, beforeSeq, afterSeq, scanBudget, signal } = options;
+    if (beforeSeq < 0n || afterSeq < beforeSeq || durableSeq < 0n)
+        throw new RangeError('invalid cutoffs');
+    if (afterSeq > durableSeq)
+        return { kind: 'beyondDurable' };
+    if (!Number.isSafeInteger(scanBudget.records) || scanBudget.records < 0
+        || !Number.isSafeInteger(scanBudget.bytes) || scanBudget.bytes < 0)
+        throw new RangeError('invalid scan budget');
+    const started = performance.now();
+    let records = 0;
+    let bytes = 0;
+    const scan = () => ({ records, bytes, elapsedMs: performance.now() - started });
+    if (signal?.aborted)
+        return { kind: 'aborted', scan: scan() };
+    if (afterSeq === 0n)
+        return {
+            kind: 'resolved', inventory: { scope: 'observed', baselineCompletedSeq: null, unknownScopes: [], policyExclusions: POLICY_EXCLUSIONS },
+            gaps: [], files: [], scan: scan(),
+        };
+    const states = new Map();
+    const gaps = [];
+    let baselineCompletedSeq = null;
+    let unknownScopes = [];
+    let lastSeq = 0n;
+    const cursor = await openLogCursor(logPath, 0n);
+    try {
+        while (lastSeq < afterSeq) {
+            if (signal?.aborted)
+                return { kind: 'aborted', scan: scan() };
+            if (records >= scanBudget.records || bytes >= scanBudget.bytes)
+                return { kind: 'scanLimit', scan: scan() };
+            let batch;
+            try {
+                batch = await cursor.readThrough(afterSeq, {
+                    maxRecords: scanBudget.records - records,
+                    maxBytes: scanBudget.bytes - bytes,
+                    signal,
+                });
+            }
+            catch (error) {
+                if (error instanceof LogReadAbortedError)
+                    return { kind: 'aborted', scan: scan() };
+                if (error instanceof LogReadLimitError)
+                    return { kind: 'scanLimit', scan: scan() };
+                throw error;
+            }
+            if (batch.length === 0)
+                corrupt(`disk short of durable boundary ${afterSeq}`);
+            for (const record of batch) {
+                records += 1;
+                if (record.bytesRead === undefined)
+                    corrupt(`missing bytesRead at ${record.seq}`);
+                bytes += record.bytesRead;
+                lastSeq = record.seq;
+                consume(record);
+            }
+        }
+    }
+    finally {
+        await cursor.close();
+    }
+    if (signal?.aborted)
+        return { kind: 'aborted', scan: scan() };
+    function consume(record) {
+        const seq = record.seq.toString();
+        const data = record.data;
+        if (data.session_id !== sessionId)
+            corrupt(`session mismatch at ${seq}`);
+        if (record.id !== seq)
+            corrupt(`envelope id ${record.id} != seq ${seq} at ${seq}`);
+        if (record.source !== sourceFor(sessionId))
+            corrupt(`envelope source ${record.source} != ${sourceFor(sessionId)} at ${seq}`);
+        if (record.type === BASELINED || record.type === CHANGED) {
+            const path = checkPath(data.path, seq);
+            const state = states.get(path) ?? {};
+            if (record.type === BASELINED) {
+                const tag = snapshot(data.snapshot, seq);
+                state.prior = tag;
+            }
+            else {
+                const before = snapshot(data.before, seq);
+                const after = snapshot(data.after, seq);
+                if (data.observation !== 'watcher' && data.observation !== 'reconciliation')
+                    corrupt(`bad observation at ${seq}`);
+                if (data.gap_ref !== undefined && (typeof data.gap_ref !== 'string' || !SEQ.test(data.gap_ref)))
+                    corrupt(`bad gap_ref at ${seq}`);
+                if (state.prior !== undefined && !sameRecordedState(state.prior, before))
+                    corrupt(`contradictory predecessor at ${seq}: ${path}`);
+                state.prior = after;
+            }
+            const fileRecord = { seq, type: record.type, data };
+            state.after = fileRecord;
+            if (record.seq <= beforeSeq)
+                state.before = fileRecord;
+            else if (state.firstAfterB === undefined)
+                state.firstAfterB = fileRecord;
+            states.set(path, state);
+        }
+        else if (record.type === COMPLETED && baselineCompletedSeq === null) {
+            if (!Array.isArray(data.unknown_scopes) || data.unknown_scopes.some((scope) => {
+                if (typeof scope !== 'string' || scope.includes('\0'))
+                    return true;
+                if (scope === '')
+                    return false;
+                try {
+                    assertSafePath(scope, `record ${seq}`);
+                    return false;
+                }
+                catch {
+                    return true;
+                }
+            }))
+                corrupt(`bad unknown scopes at ${seq}`);
+            baselineCompletedSeq = seq;
+            unknownScopes = [...data.unknown_scopes].sort();
+        }
+        else if (record.type === GAP) {
+            gaps.push(checkGap(data, seq));
+        }
+    }
+    const files = [];
+    for (const [path, state] of states) {
+        if (options.pathPrefix !== undefined && !path.startsWith(options.pathPrefix))
+            continue;
+        if (options.afterPath !== undefined && options.afterPath !== null && path <= options.afterPath)
+            continue;
+        if (state.after === undefined)
+            continue;
+        const after = stateEndpoint(state.after);
+        const before = state.before !== undefined ? stateEndpoint(state.before)
+            : baselineCompletedSeq !== null && BigInt(baselineCompletedSeq) <= beforeSeq && state.firstAfterB?.type === CHANGED
+                ? endpoint(state.firstAfterB, 'before') : { kind: 'unknownBoundary' };
+        files.push({ path, before, after, endpointsEqual: endpointsEqual(before, after) });
+    }
+    files.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+    return { kind: 'resolved', inventory: { scope: 'observed', baselineCompletedSeq, unknownScopes,
+            policyExclusions: POLICY_EXCLUSIONS }, gaps, files, scan: scan() };
+}