@brass-build/client 0.4.0 → 0.5.0

package/dist/inputs.js

@@ -0,0 +1,793 @@
+// The shape of a document that references other documents: the references a
+// key holds, the reserved CRDT roots they live in, the status the platform
+// reports for a key, and the frames and bodies that carry it. This is the one
+// definition; the platform's `@brass-build/contracts` re-exports it.
+//
+// The document's CRDT is the source of truth for each key's references and
+// read marks. Nothing read out of the roots is authority: a reference's
+// `organization_id` is a hint for resolving it and grants nothing.
+import { sha256Hex } from './sha256.js';
+const DEFAULT_STREAM_NAME = 'default';
+const NAME_TOKEN_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+function isNameToken(value) {
+    return NAME_TOKEN_PATTERN.test(value);
+}
+// A stored reference may carry its families as `types`, which reads the same.
+function parseSelectionAccept(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const raw = value;
+    const list = (v) => {
+        if (!Array.isArray(v))
+            return null;
+        const items = v.filter((x) => typeof x === 'string' && x !== '');
+        return items.length > 0 ? items : null;
+    };
+    const names = list(raw['names']);
+    const extensions = list(raw['extensions']);
+    const families = list(raw['families']) ?? list(raw['types']);
+    if (!names && !extensions && !families)
+        return null;
+    return {
+        ...(names ? { names } : {}),
+        ...(extensions ? { extensions } : {}),
+        ...(families ? { families } : {}),
+    };
+}
+function documentTopic(docId, branchId) {
+    return `doc:${docId}:${branchId}`;
+}
+function parseDocTopic(topic) {
+    const m = /^doc:(doc_[A-Za-z0-9_-]{32}):(b_[A-Za-z0-9_-]{32})$/.exec(topic);
+    return m && m[1] && m[2] ? { docId: m[1], branchId: m[2] } : null;
+}
+// --- Identifiers -----------------------------------------------------------
+const DOC_ID_PATTERN = /^doc_[A-Za-z0-9_-]{32}$/;
+const LINE_ID_PATTERN = /^b_[A-Za-z0-9_-]{32}$/;
+// Organization and project ids are opaque here; the shape only has to keep
+// them safe inside a key or an identity string.
+const ENTITY_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+/** @internal */
+export function isInputDocId(value) {
+    return typeof value === 'string' && DOC_ID_PATTERN.test(value);
+}
+/** @internal */
+export function isInputLineId(value) {
+    return typeof value === 'string' && LINE_ID_PATTERN.test(value);
+}
+// --- Keys ------------------------------------------------------------------
+/** @internal The longest key an app may record references under. */
+export const INPUT_KEY_MAX_CHARS = 128;
+/**
+ * @internal
+ * An app key: a letter or digit, then letters, digits and `._:@/+=~-`. `#`
+ * is excluded because the key is the tail of a row's sort key, and so is
+ * whitespace, which an app writing `stamp:${id}` never produces on purpose.
+ */
+export const INPUT_KEY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:@/+=~-]{0,127}$/;
+/** @internal Keys under this prefix are the platform's own, refused from an app. */
+export const INPUT_KEY_RESERVED_PREFIX = 'brass:';
+/** @internal */
+export function isInputKey(value) {
+    return (typeof value === 'string' &&
+        INPUT_KEY_PATTERN.test(value) &&
+        !value.toLowerCase().startsWith(INPUT_KEY_RESERVED_PREFIX));
+}
+/** @internal */
+export const INPUT_REFERENCE_LABEL_MAX_CHARS = 256;
+/**
+ * @internal
+ * Reads a reference off an untrusted value: the wire, or an entry a peer
+ * wrote into the reserved roots. Null when it is not one.
+ */
+export function parseInputReference(raw) {
+    if (!isRecord(raw))
+        return null;
+    const extent = raw['extent'];
+    const organizationId = raw['organization_id'];
+    if (typeof organizationId !== 'string' || !ENTITY_ID_PATTERN.test(organizationId))
+        return null;
+    const ref = { organization_id: organizationId, extent: 'organization' };
+    if (extent === 'document') {
+        if (!isInputDocId(raw['doc_id']))
+            return null;
+        ref.extent = 'document';
+        ref.doc_id = raw['doc_id'];
+        const stream = raw['stream'];
+        if (stream !== undefined) {
+            if (typeof stream !== 'string' || !isNameToken(stream))
+                return null;
+            if (stream !== DEFAULT_STREAM_NAME)
+                ref.stream = stream;
+        }
+    }
+    else if (extent === 'project') {
+        const projectId = raw['project_id'];
+        if (typeof projectId !== 'string' || !ENTITY_ID_PATTERN.test(projectId))
+            return null;
+        if (raw['stream'] !== undefined)
+            return null;
+        ref.extent = 'project';
+        ref.project_id = projectId;
+    }
+    else if (extent === 'organization') {
+        if (raw['stream'] !== undefined)
+            return null;
+    }
+    else {
+        return null;
+    }
+    // A project reference may also say which project a document sits in; the
+    // identity reads only the field its extent names.
+    if (ref.extent === 'document' && typeof raw['project_id'] === 'string') {
+        if (!ENTITY_ID_PATTERN.test(raw['project_id']))
+            return null;
+        ref.project_id = raw['project_id'];
+    }
+    const label = raw['label'];
+    if (label !== undefined) {
+        if (typeof label !== 'string' || label.length > INPUT_REFERENCE_LABEL_MAX_CHARS)
+            return null;
+        ref.label = label;
+    }
+    if (raw['accept'] !== undefined) {
+        if (!isRecord(raw['accept']))
+            return null;
+        // A narrowing with no clause narrows nothing, so it is the same
+        // reference as one carrying none.
+        const accept = parseSelectionAccept(raw['accept']);
+        if (accept !== null)
+            ref.accept = accept;
+    }
+    return ref;
+}
+function isEmptyAccept(accept) {
+    return !accept.families?.length && !accept.names?.length && !accept.extensions?.length;
+}
+// The narrowing as one canonical string: families and extensions compared
+// case-insensitively, extensions without their dot, names case-insensitively
+// (the match is), each list sorted and de-duplicated.
+function canonicalAccept(accept) {
+    const norm = (xs, strip = false) => [...new Set((xs ?? []).map((x) => (strip ? x.replace(/^\./, '') : x).toLowerCase()))].sort();
+    return JSON.stringify({
+        t: norm(accept.families),
+        e: norm(accept.extensions, true),
+        n: norm(accept.names),
+    });
+}
+/**
+ * @internal
+ * The reference's stable identity: the key it is stored under in the
+ * references root, and what the platform's rows name it by.
+ *
+ * `d:<doc_id>`, `d:<doc_id>/<stream>`, `p:<project_id>` or
+ * `o:<organization_id>`, followed by `~<16 hex>` when the reference carries a
+ * narrowing. The label is not part of it, so renaming a choice does not make
+ * it a different reference.
+ */
+export function inputReferenceId(ref) {
+    let id;
+    if (ref.extent === 'document') {
+        id = `d:${ref.doc_id ?? ''}`;
+        if (ref.stream !== undefined && ref.stream !== DEFAULT_STREAM_NAME)
+            id += `/${ref.stream}`;
+    }
+    else if (ref.extent === 'project') {
+        id = `p:${ref.project_id ?? ''}`;
+    }
+    else {
+        id = `o:${ref.organization_id}`;
+    }
+    if (ref.accept && !isEmptyAccept(ref.accept)) {
+        id += `~${sha256Hex(canonicalAccept(ref.accept)).slice(0, 16)}`;
+    }
+    return id;
+}
+const INPUT_REFERENCE_ID_PATTERN = /^(?:d:doc_[A-Za-z0-9_-]{32}(?:\/[a-z0-9][a-z0-9._-]{0,63})?|[po]:[A-Za-z0-9_-]{1,64})(?:~[0-9a-f]{16})?$/;
+/** @internal */
+export function isInputReferenceId(value) {
+    return typeof value === 'string' && INPUT_REFERENCE_ID_PATTERN.test(value);
+}
+/**
+ * @internal
+ * The hash of a reference set: what keys with identical references share one
+ * resolution under. Order and duplicates do not move it, and neither does a
+ * label.
+ */
+export function inputReferenceSetHash(refs) {
+    const ids = [...new Set(refs.map(inputReferenceId))].sort();
+    return sha256Hex(`inputs-v1\n${ids.join('\n')}`);
+}
+const SET_HASH_PATTERN = /^[0-9a-f]{64}$/;
+/** @internal */
+export function isInputReferenceSetHash(value) {
+    return typeof value === 'string' && SET_HASH_PATTERN.test(value);
+}
+// --- Limits ----------------------------------------------------------------
+/**
+ * @internal
+ * The most distinct documents a document's keys report across all of them.
+ * Past it the status says `truncated`; it is never a refusal.
+ */
+export const INPUT_DOCS_MAX = 2000;
+/** @internal The most references one key may hold in a provisional body. */
+export const INPUT_REFS_MAX_PER_KEY = 2000;
+/** @internal The most read marks one key may carry in a provisional body. */
+export const INPUT_READ_MARKS_MAX_PER_KEY = INPUT_DOCS_MAX;
+/** @internal The longest version stamp a read mark or a file may carry. */
+export const INPUT_STAMP_MAX_CHARS = 64;
+// --- The reserved CRDT roots -------------------------------------------------
+/**
+ * @internal
+ * The document roots holding every key's references and read marks. Both are
+ * flat maps at the root: a root container's id is fixed by its name, so every
+ * peer writes into the same container. A container created under a map entry
+ * is not: two peers creating one concurrently make two, and the entry keeps
+ * one of them, dropping the other's writes. So nothing here nests.
+ *
+ * The names sit outside both the `brass:` record-store key space and any name
+ * an app passes to `doc.map`, so record paging and the frozen-to-CRDT
+ * conversion, which walk app roots, never reach them.
+ *
+ * `INPUTS_REFS_ROOT`: `<key>␟<referenceId>` -> the reference.
+ * `INPUTS_READ_ROOT`: `<key>␟<docId>␟<stamp>␟<kind>` -> true.
+ */
+export const INPUTS_REFS_ROOT = '__brass_input_refs';
+/** @internal */
+export const INPUTS_READ_ROOT = '__brass_input_read';
+/**
+ * @internal
+ * Joins the parts of an entry key: U+241F SYMBOL FOR UNIT SEPARATOR, which no
+ * app key, reference id, doc id or stamp can contain.
+ */
+export const INPUTS_ENTRY_SEPARATOR = '␟';
+const SEP = INPUTS_ENTRY_SEPARATOR;
+/** @internal */
+export function inputRefEntryKey(key, refId) {
+    return `${key}${SEP}${refId}`;
+}
+/** @internal */
+export function parseInputRefEntryKey(entryKey) {
+    const parts = entryKey.split(SEP);
+    if (parts.length !== 2)
+        return null;
+    const [key, refId] = parts;
+    return isInputKey(key) && isInputReferenceId(refId) ? { key, refId } : null;
+}
+/** @internal Digits a stamp is zero-padded to in an entry key, so the keys sort by stamp. */
+export const INPUT_STAMP_DIGITS = 16;
+/**
+ * @internal
+ * A version of a document, as a read mark records it: the milliseconds since
+ * the epoch of the `updated_at` the reader read the document at.
+ */
+export function inputStampFromUpdatedAt(updatedAt) {
+    const ms = Date.parse(updatedAt);
+    return Number.isSafeInteger(ms) && ms >= 0 && ms < 10 ** INPUT_STAMP_DIGITS ? ms : null;
+}
+function isStamp(value) {
+    return (typeof value === 'number' &&
+        Number.isSafeInteger(value) &&
+        value >= 0 &&
+        value < 10 ** INPUT_STAMP_DIGITS);
+}
+const READ_KIND = { removed: '0', read: '1' };
+/** @internal */
+export function inputReadEntryKey(key, docId, mark) {
+    const stamp = String(mark.stamp).padStart(INPUT_STAMP_DIGITS, '0');
+    const kind = mark.removed ? READ_KIND.removed : READ_KIND.read;
+    return `${key}${SEP}${docId}${SEP}${stamp}${SEP}${kind}`;
+}
+/** @internal The prefix every read mark of one key shares, or of one document under it. */
+export function inputReadEntryPrefix(key, docId) {
+    return docId === undefined ? `${key}${SEP}` : `${key}${SEP}${docId}${SEP}`;
+}
+/** @internal */
+export function parseInputReadEntryKey(entryKey) {
+    const parts = entryKey.split(SEP);
+    if (parts.length !== 4)
+        return null;
+    const [key, docId, stamp, kind] = parts;
+    if (!isInputKey(key) || !isInputDocId(docId))
+        return null;
+    if (!new RegExp(`^[0-9]{${INPUT_STAMP_DIGITS}}$`).test(stamp))
+        return null;
+    if (kind !== READ_KIND.removed && kind !== READ_KIND.read)
+        return null;
+    return { key, docId, mark: { stamp: Number(stamp), removed: kind === READ_KIND.removed } };
+}
+/**
+ * @internal
+ * The mark that acknowledges a file leaving a key, given the latest mark the
+ * reader holds for it and the version it left at (`updatedAt` on the removed
+ * entry; null when the entry carries none). The mark sits at that version, so
+ * a read of the file returning at it follows the removal. When the version
+ * did not move past the reader's last read, the removal has to sit one stamp
+ * past that read to follow it, and `inputReadMarkFor` lifts a later read of
+ * the returning file to the removal's stamp. A removal already acknowledged
+ * keeps its mark.
+ */
+export function inputRemovalMark(latest, updatedAt) {
+    if (latest?.removed === true)
+        return latest;
+    const leftAt = updatedAt === null ? null : inputStampFromUpdatedAt(updatedAt);
+    const floor = latest === null ? 0 : latest.stamp + 1;
+    return { stamp: Math.max(leftAt ?? 0, floor), removed: true };
+}
+/**
+ * @internal
+ * The mark that records reading a file at `stamp`, given the latest mark the
+ * reader holds for it: at `stamp`, or at a removal's stamp when that removal
+ * sits past it, which is the one stamp a read can take to follow it.
+ */
+export function inputReadMarkFor(latest, stamp) {
+    if (latest?.removed === true && latest.stamp > stamp)
+        return { stamp: latest.stamp, removed: false };
+    return { stamp, removed: false };
+}
+/** @internal Whether `a` is a later acknowledgement than `b`. */
+export function inputReadMarkAfter(a, b) {
+    if (a.stamp !== b.stamp)
+        return a.stamp > b.stamp;
+    return !a.removed && b.removed;
+}
+/** @internal */
+export function parseInputReadMark(raw) {
+    if (!isRecord(raw) || !isStamp(raw['stamp']) || typeof raw['removed'] !== 'boolean')
+        return null;
+    return { stamp: raw['stamp'], removed: raw['removed'] };
+}
+/**
+ * @internal
+ * Every key holding references, from the two roots' plain-object forms.
+ * Tolerant, since peers write the roots: an entry whose key does not parse,
+ * whose value is not a reference, or whose reference id does not match the
+ * one re-derived from its value is dropped rather than failing the read. A
+ * read mark is kept only when present (`true`), and only the latest per
+ * document counts. Keys with no references are absent, along with their
+ * marks.
+ */
+export function decodeInputsRoots(refsRoot, readRoot) {
+    const refsByKey = new Map();
+    if (isRecord(refsRoot)) {
+        for (const [entryKey, value] of Object.entries(refsRoot)) {
+            const parsed = parseInputRefEntryKey(entryKey);
+            const ref = parseInputReference(value);
+            if (parsed === null || ref === null || inputReferenceId(ref) !== parsed.refId)
+                continue;
+            const held = refsByKey.get(parsed.key) ?? new Map();
+            held.set(parsed.refId, ref);
+            refsByKey.set(parsed.key, held);
+        }
+    }
+    const out = new Map();
+    for (const key of [...refsByKey.keys()].sort()) {
+        const held = refsByKey.get(key);
+        const refs = [...held.keys()].sort().map((id) => held.get(id));
+        out.set(key, { refs, read: {} });
+    }
+    if (isRecord(readRoot)) {
+        for (const [entryKey, value] of Object.entries(readRoot)) {
+            if (value !== true)
+                continue;
+            const parsed = parseInputReadEntryKey(entryKey);
+            const state = parsed ? out.get(parsed.key) : undefined;
+            if (!parsed || !state)
+                continue;
+            const prior = state.read[parsed.docId];
+            if (!prior || inputReadMarkAfter(parsed.mark, prior))
+                state.read[parsed.docId] = parsed.mark;
+        }
+    }
+    return out;
+}
+/**
+ * @internal
+ * The writes that make `key`'s references `next` (null clears the key), given
+ * the refs root as this writer sees it. Only the difference is written:
+ * entries this writer did not see are not touched, so a reference another
+ * peer adds concurrently survives. Throws on a reference that would not
+ * decode.
+ */
+export function inputRefsWrites(refsRoot, key, next) {
+    if (!isInputKey(key))
+        throw new TypeError('Not a valid input key');
+    const wanted = new Map();
+    for (const ref of next ?? []) {
+        const parsed = parseInputReference(ref);
+        if (parsed === null)
+            throw new TypeError('Not a valid input reference');
+        wanted.set(inputRefEntryKey(key, inputReferenceId(parsed)), parsed);
+    }
+    const writes = { set: {}, delete: [] };
+    for (const entryKey of Object.keys(refsRoot).sort()) {
+        if (parseInputRefEntryKey(entryKey)?.key === key && !wanted.has(entryKey)) {
+            writes.delete.push(entryKey);
+        }
+    }
+    for (const entryKey of [...wanted.keys()].sort()) {
+        const ref = wanted.get(entryKey);
+        if (!sameJson(refsRoot[entryKey], ref))
+            writes.set[entryKey] = ref;
+    }
+    return writes;
+}
+/**
+ * @internal
+ * The writes that record `mark` for `docId` under `key`, given the read root
+ * as this writer sees it: the mark's entry, and the deletion of every earlier
+ * mark for that document. A later mark already present is left in place, and
+ * still wins.
+ */
+export function inputReadMarkWrites(readRoot, key, docId, mark) {
+    if (!isInputKey(key) || !isInputDocId(docId) || parseInputReadMark(mark) === null) {
+        throw new TypeError('Not a valid read mark');
+    }
+    const own = inputReadEntryKey(key, docId, mark);
+    const writes = { set: {}, delete: [] };
+    for (const entryKey of Object.keys(readRoot).sort()) {
+        const parsed = parseInputReadEntryKey(entryKey);
+        if (parsed?.key === key && parsed.docId === docId && inputReadMarkAfter(mark, parsed.mark)) {
+            writes.delete.push(entryKey);
+        }
+    }
+    if (readRoot[own] !== true)
+        writes.set[own] = true;
+    return writes;
+}
+/** @internal The writes that clear every read mark under `key`, as when the key is cleared. */
+export function inputReadClearWrites(readRoot, key) {
+    const prefix = inputReadEntryPrefix(key);
+    return { set: {}, delete: Object.keys(readRoot).filter((k) => k.startsWith(prefix)).sort() };
+}
+function sameJson(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+/** @internal */
+export const INPUT_FILE_CHANGES = ['added', 'modified', 'removed'];
+/** @internal The most keys one page of the keyless status carries. */
+export const INPUT_KEYS_PAGE_SIZE = 50;
+/** @internal The most changed entries one page of the keyless status carries. */
+export const INPUT_KEYS_CHANGED_MAX = INPUT_DOCS_MAX;
+/** @internal Query parameters on `GET` of a key's status. */
+export const INPUT_STATUS_SINCE_PARAM = 'since_rev';
+/** @internal */
+export const INPUT_STATUS_CURSOR_PARAM = 'cursor';
+/**
+ * @internal
+ * The line whose keys a `GET` reads: a branch or a stream of the document,
+ * named as a document join names it. Absent reads the document's default
+ * branch.
+ */
+export const INPUT_STATUS_LINE_PARAM = 'branch';
+/** @internal The most documents one page or one delta carries. */
+export const INPUT_STATUS_PAGE_SIZE = 500;
+/**
+ * @internal
+ * A page cursor: the revision the first page answered at and the last doc id
+ * the previous page held. Pinning the revision is what keeps a paged read
+ * consistent; a server whose status moved since answers a resync, and the
+ * reader starts again.
+ */
+export function encodeInputStatusCursor(cursor) {
+    return `${cursor.rev}.${cursor.after}`;
+}
+/**
+ * @internal
+ * A keyless status cursor: `encodeInputStatusCursor` over the revision the
+ * first page answered at and the last key the previous page held.
+ */
+export function decodeInputKeysCursor(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const m = /^(0|[1-9][0-9]{0,14})\.(.+)$/s.exec(raw);
+    if (!m || !m[1] || !m[2] || !isInputKey(m[2]))
+        return null;
+    return { rev: Number(m[1]), after: m[2] };
+}
+/** @internal */
+export function decodeInputStatusCursor(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const m = /^(0|[1-9][0-9]{0,14})\.(doc_[A-Za-z0-9_-]{32})$/.exec(raw);
+    if (!m || !m[1] || !m[2])
+        return null;
+    return { rev: Number(m[1]), after: m[2] };
+}
+/**
+ * @internal
+ * The status a delta moves `status` to, or null when the delta does not start
+ * at `status.rev` (a gap, which the reader closes by fetching again).
+ */
+export function applyInputStatusDelta(status, delta) {
+    if (delta.key !== status.key || delta.since_rev !== status.rev)
+        return null;
+    return {
+        key: status.key,
+        refs: delta.refs ?? status.refs,
+        files: applyUpserts(status.files, delta.files),
+        changed: applyUpserts(status.changed, delta.changed),
+        hidden_count: delta.hidden_count,
+        truncated: delta.truncated,
+        rev: delta.rev,
+        ...(delta.stale === true ? { stale: true } : {}),
+        ...(delta.arriving === true ? { arriving: true } : {}),
+    };
+}
+function applyUpserts(current, diff) {
+    const byId = new Map(current.map((e) => [e.doc_id, e]));
+    for (const id of diff.remove)
+        byId.delete(id);
+    for (const e of diff.upsert)
+        byId.set(e.doc_id, e);
+    return [...byId.values()].sort((a, b) => (a.doc_id < b.doc_id ? -1 : a.doc_id > b.doc_id ? 1 : 0));
+}
+/** @internal Reads a key's status (or a page of one) off the wire. Null when malformed. */
+export function parseInputStatus(raw) {
+    if (!isRecord(raw) || !isInputKey(raw['key']))
+        return null;
+    const refs = parseList(raw['refs'], parseInputReference);
+    const files = parseList(raw['files'], parseInputStatusFile);
+    const changed = parseList(raw['changed'], parseInputStatusChange);
+    const counts = parseCounts(raw);
+    const stale = parseStale(raw);
+    const arriving = parseArriving(raw);
+    if (refs === null || files === null || changed === null || counts === null || stale === null || arriving === null) {
+        return null;
+    }
+    return { key: raw['key'], refs, files, changed, ...counts, ...stale, ...arriving };
+}
+/** @internal */
+export function parseInputStatusPage(raw) {
+    const status = parseInputStatus(raw);
+    if (status === null || !isRecord(raw))
+        return null;
+    const cursor = raw['cursor'];
+    if (cursor !== null && decodeInputStatusCursor(cursor) === null)
+        return null;
+    return { ...status, cursor: cursor };
+}
+/** @internal Reads a keyless status page, or the resync a moved cursor draws. Null when malformed. */
+export function parseInputStatusAll(raw) {
+    if (!isRecord(raw))
+        return null;
+    if (raw['resync'] === true)
+        return isRev(raw['rev']) ? { rev: raw['rev'], resync: true } : null;
+    const cursor = raw['cursor'] ?? null;
+    if (cursor !== null && decodeInputKeysCursor(cursor) === null)
+        return null;
+    const keys = raw['keys'];
+    if (!Array.isArray(keys) || !keys.every(isInputKey))
+        return null;
+    const changed = parseList(raw['changed'], parseInputStatusChange);
+    const counts = parseCounts(raw);
+    const stale = parseStale(raw);
+    if (changed === null || counts === null || stale === null)
+        return null;
+    const keyed = [];
+    for (const c of changed) {
+        if (c.key === undefined)
+            return null;
+        keyed.push({ ...c, key: c.key });
+    }
+    return { keys: [...keys], changed: keyed, ...counts, ...stale, cursor: cursor };
+}
+/** @internal Reads a `since_rev` answer: a delta, a resync, or null when malformed. */
+export function parseInputStatusDelta(raw) {
+    if (!isRecord(raw) || !isInputKey(raw['key']))
+        return null;
+    const rev = raw['rev'];
+    if (!isRev(rev))
+        return null;
+    if (raw['resync'] === true)
+        return { key: raw['key'], rev, resync: true };
+    const since = raw['since_rev'];
+    if (!isRev(since) || since > rev)
+        return null;
+    const files = parseDiff(raw['files'], parseInputStatusFile);
+    const changed = parseDiff(raw['changed'], parseInputStatusChange);
+    const counts = parseCounts(raw);
+    const stale = parseStale(raw);
+    const arriving = parseArriving(raw);
+    if (files === null || changed === null || counts === null || stale === null || arriving === null)
+        return null;
+    const delta = {
+        key: raw['key'],
+        since_rev: since,
+        rev,
+        files,
+        changed,
+        hidden_count: counts.hidden_count,
+        truncated: counts.truncated,
+        ...stale,
+        ...arriving,
+    };
+    if (raw['refs'] !== undefined) {
+        const refs = parseList(raw['refs'], parseInputReference);
+        if (refs === null)
+            return null;
+        delta.refs = refs;
+    }
+    return delta;
+}
+function parseInputStatusFile(raw) {
+    if (!isRecord(raw) || !isInputDocId(raw['doc_id']))
+        return null;
+    const updatedAt = raw['updated_at'];
+    if (typeof updatedAt !== 'string' || updatedAt.length > INPUT_STAMP_MAX_CHARS)
+        return null;
+    const name = raw['name'];
+    if (typeof name !== 'string')
+        return null;
+    const from = parseFrom(raw['from']);
+    const ref = parseInputReference(raw['ref']);
+    if (from === null || ref === null)
+        return null;
+    const schemaType = raw['schema_type'];
+    if (schemaType !== undefined && typeof schemaType !== 'string')
+        return null;
+    const awaitsImport = raw['awaits_import'];
+    if (awaitsImport !== undefined && awaitsImport !== true)
+        return null;
+    return {
+        doc_id: raw['doc_id'],
+        name,
+        ...(schemaType !== undefined ? { schema_type: schemaType } : {}),
+        updated_at: updatedAt,
+        from,
+        ref,
+        ...(awaitsImport === true ? { awaits_import: true } : {}),
+    };
+}
+function parseInputStatusChange(raw) {
+    if (!isRecord(raw) || !isInputDocId(raw['doc_id']))
+        return null;
+    const change = raw['change'];
+    if (!INPUT_FILE_CHANGES.includes(change))
+        return null;
+    const from = parseFrom(raw['from']);
+    if (from === null)
+        return null;
+    const out = { doc_id: raw['doc_id'], change: change, from };
+    if (raw['key'] !== undefined) {
+        if (!isInputKey(raw['key']))
+            return null;
+        out.key = raw['key'];
+    }
+    if (raw['updated_at'] !== undefined) {
+        const at = raw['updated_at'];
+        if (typeof at !== 'string' || at.length > INPUT_STAMP_MAX_CHARS)
+            return null;
+        out.updated_at = at;
+    }
+    return out;
+}
+function parseFrom(raw) {
+    return Array.isArray(raw) && raw.every(isInputReferenceId) ? [...raw] : null;
+}
+function parseCounts(raw) {
+    const hidden = raw['hidden_count'];
+    const truncated = raw['truncated'];
+    const rev = raw['rev'];
+    if (!isRev(hidden) || typeof truncated !== 'boolean' || !isRev(rev))
+        return null;
+    return { hidden_count: hidden, truncated, rev };
+}
+// `stale` is optional on the wire and carried only when true.
+function parseStale(raw) {
+    const stale = raw['stale'];
+    if (stale === undefined || stale === false)
+        return {};
+    return stale === true ? { stale: true } : null;
+}
+// `arriving` is optional on the wire and carried only when true.
+function parseArriving(raw) {
+    const arriving = raw['arriving'];
+    if (arriving === undefined || arriving === false)
+        return {};
+    return arriving === true ? { arriving: true } : null;
+}
+function parseDiff(raw, parse) {
+    if (!isRecord(raw))
+        return null;
+    const upsert = parseList(raw['upsert'], parse);
+    const remove = raw['remove'];
+    if (upsert === null || !Array.isArray(remove) || !remove.every(isInputDocId))
+        return null;
+    return { upsert, remove: [...remove] };
+}
+function parseList(raw, parse) {
+    if (!Array.isArray(raw))
+        return null;
+    const out = [];
+    for (const entry of raw) {
+        const parsed = parse(entry);
+        if (parsed === null)
+            return null;
+        out.push(parsed);
+    }
+    return out;
+}
+function isRev(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+// --- Live nudge (WS) --------------------------------------------------------
+/** @internal */
+export const INPUT_STATUS_FRAME_TYPE = 'doc_input_status';
+/** @internal */
+export function inputStatusNudgeFrame(docId, lineId, key, rev) {
+    return { type: INPUT_STATUS_FRAME_TYPE, topic: documentTopic(docId, lineId), key, rev };
+}
+/** @internal Reads a nudge frame. Null for any other frame or a malformed one. */
+export function parseInputStatusNudge(raw) {
+    if (!isRecord(raw) || raw['type'] !== INPUT_STATUS_FRAME_TYPE)
+        return null;
+    const topic = typeof raw['topic'] === 'string' ? parseDocTopic(raw['topic']) : null;
+    if (topic === null || !isInputKey(raw['key']) || !isRev(raw['rev']))
+        return null;
+    return { docId: topic.docId, lineId: topic.branchId, key: raw['key'], rev: raw['rev'] };
+}
+/** @internal */
+export function parseProvisionalInputsAnswer(raw) {
+    if (!isRecord(raw) || !isInputKey(raw['key']) || !isRev(raw['rev']))
+        return null;
+    if (typeof raw['written'] !== 'boolean')
+        return null;
+    return { key: raw['key'], rev: raw['rev'], written: raw['written'] };
+}
+/**
+ * @internal
+ * Reads a provisional body for document `docId`. Refuses a reference to any
+ * stream of `docId` itself, and references that repeat one identity.
+ */
+export function parseProvisionalInputsBody(raw, opts) {
+    if (!isRecord(raw))
+        return fail('Body must be an object');
+    const { branch_id: lineId, op_seq: opSeq } = raw;
+    if (!isInputLineId(lineId))
+        return fail('branch_id is not a valid line id');
+    if (typeof opSeq !== 'number' || !Number.isSafeInteger(opSeq) || opSeq < 1) {
+        return fail('op_seq must be a positive integer');
+    }
+    const refsRaw = raw['refs'];
+    if (!Array.isArray(refsRaw))
+        return fail('refs must be an array');
+    if (refsRaw.length > INPUT_REFS_MAX_PER_KEY)
+        return fail('Too many references');
+    const refs = [];
+    const seen = new Set();
+    for (const entry of refsRaw) {
+        const ref = parseInputReference(entry);
+        if (ref === null)
+            return fail('refs holds an invalid reference');
+        if (ref.extent === 'document' && ref.doc_id === opts.docId) {
+            return fail('A document cannot reference itself');
+        }
+        const id = inputReferenceId(ref);
+        if (seen.has(id))
+            return fail('refs repeats a reference');
+        seen.add(id);
+        refs.push(ref);
+    }
+    const readRaw = raw['read'];
+    if (!isRecord(readRaw))
+        return fail('read must be an object');
+    const docIds = Object.keys(readRaw);
+    if (docIds.length > INPUT_READ_MARKS_MAX_PER_KEY)
+        return fail('Too many read marks');
+    const read = {};
+    for (const docId of docIds) {
+        const mark = parseInputReadMark(readRaw[docId]);
+        if (!isInputDocId(docId) || mark === null)
+            return fail('read holds an invalid mark');
+        read[docId] = mark;
+    }
+    return { ok: true, value: { branch_id: lineId, op_seq: opSeq, refs, read } };
+}
+function fail(error) {
+    return { ok: false, error };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=inputs.js.map