@texuli/spec 0.5.0 → 0.6.0

package/dist/stream/assembler.js

@@ -0,0 +1,284 @@
+import { createJsonTokenizer, } from "./tokenizer.js";
+/**
+ * The partial-blueprint assembler (ADR-014): builds the value the tokenizer
+ * reads and reports, for every catalog node, when its **shell** is final.
+ * Streamed nodes put `children` last (`key`, `id`, `slot`, `props`, `when`,
+ * `bind`, `on`, `children`), so a node's shell (every member but `children`)
+ * is final once `children` starts, or once the node closes without it.
+ * Envelopes put `state` and `flow` before the tree, so the envelope header
+ * is final once `tree` starts. A member after `children` (or after `tree`)
+ * is a `stream-order` issue: the node it lands in is held until the final
+ * verdict. The assembler judges no rule itself; the catalog checks each
+ * shell and `validateDraft` judges the whole value.
+ */
+/** Members a streamed node may have, in the canonical order (`children` last). */
+export const STREAM_NODE_ORDER = Object.freeze([
+    'key',
+    'id',
+    'slot',
+    'props',
+    'when',
+    'bind',
+    'on',
+    'motion',
+    'children',
+]);
+/** Node path of child `index` under `parent` (`null` for a root). */
+function childPath(parent, index) {
+    return parent === null ? String(index) : `${parent}.children.${index}`;
+}
+export function createBlueprintAssembler(options = {}) {
+    const tokenizer = createJsonTokenizer(options);
+    const treeMembers = new Set(options.treeMembers ?? ['tree']);
+    const stack = [];
+    let root;
+    let rootSet = false;
+    let error = null;
+    let finished = false;
+    // `true` when the root object turned out to be an envelope or wrapper.
+    let rootIsEnvelope = false;
+    const header = (frame) => {
+        const out = {};
+        for (const [key, value] of Object.entries(frame.container)) {
+            if (!treeMembers.has(key))
+                out[key] = value;
+        }
+        return out;
+    };
+    const shellOf = (frame) => {
+        const out = {};
+        for (const [key, value] of Object.entries(frame.container)) {
+            if (key !== 'children')
+                out[key] = value;
+        }
+        return out;
+    };
+    const nodeEvent = (frame, parent, index, hasChildren, offset) => {
+        const shell = shellOf(frame);
+        const key = shell.key;
+        return {
+            type: 'node',
+            path: frame.path,
+            streamId: typeof key === 'string' && key !== '' ? key : frame.path,
+            parent,
+            index,
+            shell,
+            hasChildren,
+            inArray: frame.inArray,
+            offset,
+        };
+    };
+    /** Where a node sits: its parent path and index, from its path. */
+    const position = (path) => {
+        const at = path.lastIndexOf('.children.');
+        if (at === -1)
+            return { parent: null, index: Number(path) };
+        return { parent: path.slice(0, at), index: Number(path.slice(at + '.children.'.length)) };
+    };
+    /** Attach a closed value to the container on top of the stack (or make it the root). */
+    function attach(value, out, offset) {
+        const top = stack[stack.length - 1];
+        if (!top) {
+            root = value;
+            rootSet = true;
+            return;
+        }
+        if (Array.isArray(top.container)) {
+            top.container.push(value);
+            return;
+        }
+        const key = top.key;
+        top.container[key] = value;
+        top.key = null;
+        if (top.role === 'node' && key === 'id' && !top.final) {
+            out.push({ type: 'node-id', path: top.path, id: value, offset });
+        }
+        else if (top.role === 'root' && rootIsEnvelope && top.final && !treeMembers.has(key)) {
+            // A late envelope member (after the tree) changes the header the shells were checked with.
+            out.push({ type: 'header', header: header(top), offset });
+        }
+    }
+    /** The role and path a new container gets from where it opens. */
+    function open(kind, out, offset) {
+        const container = kind === 'object' ? {} : [];
+        const top = stack[stack.length - 1];
+        const frame = {
+            role: 'value',
+            container,
+            key: null,
+            path: null,
+            final: false,
+            inArray: false,
+        };
+        if (!top) {
+            // The top level: an object is an envelope, a wrapper or a root node; an array holds roots.
+            if (kind === 'object') {
+                frame.role = 'root';
+                frame.path = '0';
+            }
+            else {
+                frame.role = 'children';
+                frame.path = null;
+            }
+        }
+        else if (top.role === 'children' && kind === 'object') {
+            const index = top.container.length;
+            frame.role = 'node';
+            frame.path = childPath(top.path, index);
+            frame.inArray = true;
+            out.push({
+                type: 'node-start',
+                path: frame.path,
+                parent: top.path,
+                index,
+                inArray: true,
+                offset,
+            });
+        }
+        else if (top.role === 'node' && top.key === 'children' && kind === 'array') {
+            frame.role = 'children';
+            frame.path = top.path;
+        }
+        else if (top.role === 'root' && top.key !== null && treeMembers.has(top.key)) {
+            // The envelope's tree: one root node at `0`, or an array of roots.
+            if (kind === 'object') {
+                frame.role = 'node';
+                frame.path = '0';
+                out.push({ type: 'node-start', path: '0', parent: null, index: 0, inArray: false, offset });
+            }
+            else {
+                frame.role = 'children';
+                frame.path = null;
+            }
+        }
+        else if (top.role === 'root' &&
+            top.key === 'children' &&
+            !rootIsEnvelope &&
+            kind === 'array') {
+            frame.role = 'children';
+            frame.path = '0';
+        }
+        stack.push(frame);
+    }
+    function onKey(key, out, offset) {
+        const top = stack[stack.length - 1];
+        top.key = key;
+        if (top.role === 'root') {
+            if (top.final) {
+                out.push({ type: 'stream-order', path: rootIsEnvelope ? '$' : '0', key, offset });
+                return;
+            }
+            if (treeMembers.has(key)) {
+                top.final = true;
+                rootIsEnvelope = true;
+                top.path = null;
+                out.push({ type: 'header', header: header(top), offset });
+                return;
+            }
+            if (key === 'children') {
+                // The root is a node: say so (late) and report its shell.
+                top.final = true;
+                out.push({ type: 'node-start', path: '0', parent: null, index: 0, inArray: false, offset });
+                out.push(nodeEvent(top, null, 0, true, offset));
+            }
+            return;
+        }
+        if (top.role !== 'node')
+            return;
+        if (top.final) {
+            out.push({ type: 'stream-order', path: top.path, key, offset });
+            return;
+        }
+        if (key === 'children') {
+            top.final = true;
+            const { parent, index } = position(top.path);
+            out.push(nodeEvent(top, parent, index, true, offset));
+        }
+    }
+    function onClose(out, offset) {
+        const frame = stack.pop();
+        if (frame.role === 'node' || (frame.role === 'root' && !rootIsEnvelope)) {
+            const path = frame.path;
+            if (!frame.final) {
+                if (frame.role === 'root') {
+                    const record = frame.container;
+                    // A childless top-level object is a node unless it reads as an envelope.
+                    if (typeof record.format !== 'string') {
+                        out.push({ type: 'node-start', path, parent: null, index: 0, inArray: false, offset });
+                        out.push(nodeEvent(frame, null, 0, false, offset));
+                        out.push({ type: 'node-end', path, offset });
+                    }
+                }
+                else {
+                    const { parent, index } = position(path);
+                    out.push(nodeEvent(frame, parent, index, false, offset));
+                    out.push({ type: 'node-end', path, offset });
+                }
+            }
+            else {
+                out.push({ type: 'node-end', path, offset });
+            }
+        }
+        attach(frame.container, out, offset);
+    }
+    function apply(events, out) {
+        for (const event of events) {
+            if (event.type === 'open')
+                open(event.kind, out, event.offset);
+            else if (event.type === 'key')
+                onKey(event.key, out, event.offset);
+            else if (event.type === 'value')
+                attach(event.value, out, event.offset);
+            else
+                onClose(out, event.offset);
+        }
+    }
+    function settle(out) {
+        if (error === null && tokenizer.error !== null) {
+            error = tokenizer.error;
+            out.push({ type: 'error', error });
+        }
+        return out;
+    }
+    return {
+        write(chunk) {
+            if (error !== null || finished)
+                return [];
+            const out = [];
+            apply(tokenizer.write(chunk), out);
+            return settle(out);
+        },
+        end() {
+            if (error !== null || finished)
+                return [];
+            const out = [];
+            apply(tokenizer.end(), out);
+            settle(out);
+            if (error === null && tokenizer.done && rootSet) {
+                finished = true;
+                out.push({ type: 'complete', value: root, offset: tokenizer.bytes });
+            }
+            return out;
+        },
+        abort(code = 'aborted', message) {
+            if (error !== null || finished)
+                return [];
+            error = {
+                code,
+                offset: tokenizer.bytes,
+                message: message ??
+                    (code === 'aborted' ? 'The stream was aborted.' : 'The stream connection dropped.'),
+            };
+            return [{ type: 'error', error }];
+        },
+        get bytes() {
+            return tokenizer.bytes;
+        },
+        get error() {
+            return error;
+        },
+        get value() {
+            return rootSet ? root : stack[0]?.container;
+        },
+    };
+}

package/dist/stream/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@texuli/spec/stream` — streamed blueprints (ADR-014): an incremental JSON
+ * tokenizer with a byte budget and a depth cap, the partial-blueprint
+ * assembler that reports when each node's shell is final, and a push handle
+ * hosts write chunks into. Framework-free: no DOM, no Svelte, no Node APIs.
+ * Nothing here validates a node; `@texuli/catalog/validate`
+ * (`validateStreamNode`, then `validateDraft`) does.
+ */
+export { type BlueprintAssembler, type BlueprintAssemblerOptions, type BlueprintStreamEvent, createBlueprintAssembler, STREAM_NODE_ORDER, type StreamNodeShell, } from './assembler.js';
+export { BlueprintStreamAbortError, type BlueprintStreamHandle, createBlueprintStream, } from './source.js';
+export { createJsonTokenizer, DEFAULT_STREAM_MAX_BYTES, DEFAULT_STREAM_MAX_DEPTH, type JsonScalar, type JsonStreamEvent, type JsonTokenizer, type JsonTokenizerOptions, STREAM_PROTOTYPE_KEYS, type StreamError, type StreamErrorCode, } from './tokenizer.js';

package/dist/stream/index.js

@@ -0,0 +1,11 @@
+/**
+ * `@texuli/spec/stream` — streamed blueprints (ADR-014): an incremental JSON
+ * tokenizer with a byte budget and a depth cap, the partial-blueprint
+ * assembler that reports when each node's shell is final, and a push handle
+ * hosts write chunks into. Framework-free: no DOM, no Svelte, no Node APIs.
+ * Nothing here validates a node; `@texuli/catalog/validate`
+ * (`validateStreamNode`, then `validateDraft`) does.
+ */
+export { createBlueprintAssembler, STREAM_NODE_ORDER, } from "./assembler.js";
+export { BlueprintStreamAbortError, createBlueprintStream, } from "./source.js";
+export { createJsonTokenizer, DEFAULT_STREAM_MAX_BYTES, DEFAULT_STREAM_MAX_DEPTH, STREAM_PROTOTYPE_KEYS, } from "./tokenizer.js";

package/dist/stream/source.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A push handle for a blueprint stream (ADR-014): the host writes text as it
+ * arrives (an agent's tool deltas, server-sent events) and a reader such as
+ * `<Player stream={handle}>` iterates it. One reader per handle. `abort()`
+ * makes the reader's iteration throw a {@link BlueprintStreamAbortError};
+ * chunks written before it are still read first.
+ */
+export interface BlueprintStreamHandle extends AsyncIterable<string> {
+    /** Queue the next chunk. Ignored after `end()` or `abort()`. */
+    write(text: string): void;
+    /** The stream is complete: the reader finishes after the queued chunks. */
+    end(): void;
+    /** The stream stopped early: the reader throws after the queued chunks. */
+    abort(reason?: string): void;
+    /** `true` after `end()` or `abort()`. */
+    readonly closed: boolean;
+}
+/** What a reader of an aborted {@link BlueprintStreamHandle} throws. */
+export declare class BlueprintStreamAbortError extends Error {
+    readonly name = "AbortError";
+}
+export declare function createBlueprintStream(): BlueprintStreamHandle;

package/dist/stream/source.js

@@ -0,0 +1,72 @@
+/**
+ * A push handle for a blueprint stream (ADR-014): the host writes text as it
+ * arrives (an agent's tool deltas, server-sent events) and a reader such as
+ * `<Player stream={handle}>` iterates it. One reader per handle. `abort()`
+ * makes the reader's iteration throw a {@link BlueprintStreamAbortError};
+ * chunks written before it are still read first.
+ */
+/** What a reader of an aborted {@link BlueprintStreamHandle} throws. */
+export class BlueprintStreamAbortError extends Error {
+    name = 'AbortError';
+}
+export function createBlueprintStream() {
+    const queue = [];
+    let state = 'open';
+    let reason = 'The stream was aborted.';
+    let wake = null;
+    const notify = () => {
+        const resume = wake;
+        wake = null;
+        resume?.();
+    };
+    return {
+        write(text) {
+            if (state !== 'open' || typeof text !== 'string' || text === '')
+                return;
+            queue.push(text);
+            notify();
+        },
+        end() {
+            if (state !== 'open')
+                return;
+            state = 'ended';
+            notify();
+        },
+        abort(message) {
+            if (state !== 'open')
+                return;
+            state = 'aborted';
+            if (typeof message === 'string' && message !== '')
+                reason = message;
+            notify();
+        },
+        get closed() {
+            return state !== 'open';
+        },
+        [Symbol.asyncIterator]() {
+            return {
+                async next() {
+                    while (queue.length === 0 && state === 'open') {
+                        await new Promise((resolve) => {
+                            wake = resolve;
+                        });
+                    }
+                    const chunk = queue.shift();
+                    if (chunk !== undefined)
+                        return { value: chunk, done: false };
+                    if (state === 'aborted')
+                        throw new BlueprintStreamAbortError(reason);
+                    return { value: undefined, done: true };
+                },
+                async return() {
+                    // The reader stopped listening: drop what is queued.
+                    queue.length = 0;
+                    if (state === 'open')
+                        state = 'ended';
+                    notify();
+                    return { value: undefined, done: true };
+                },
+            };
+        },
+    };
+}

package/dist/stream/tokenizer.d.ts

@@ -0,0 +1,67 @@
+/**
+ * An incremental JSON tokenizer for untrusted streams (ADR-014). Text
+ * arrives in chunks split anywhere (inside a string, an escape, a number, a
+ * literal or a UTF-16 surrogate pair); the tokenizer reports each value as
+ * it closes. One pass over every code unit, no backtracking and no
+ * recursion, so the time is linear in the input and the memory is bounded
+ * by the byte budget and the depth cap. Framework-free: no DOM, no Node.
+ *
+ * It refuses, at a UTF-8 byte offset: malformed JSON, input over the byte
+ * budget, containers nested past the depth cap, duplicate keys and the
+ * prototype keys (`__proto__`, `constructor`, `prototype`). After an error
+ * it reports nothing more.
+ */
+/** Why a stream stopped. Tokenizer codes, plus the codes a stream reader adds. */
+export type StreamErrorCode = 'bad-json' | 'too-large' | 'too-deep' | 'duplicate-key' | 'prototype-key' | 'truncated' | 'aborted' | 'connection';
+export interface StreamError {
+    code: StreamErrorCode;
+    /** UTF-8 byte offset of the refused input (the bytes read so far for a reader error). */
+    offset: number;
+    message: string;
+}
+export type JsonScalar = string | number | boolean | null;
+/** One closed token. `offset` is the UTF-8 byte offset where it starts. */
+export type JsonStreamEvent = {
+    type: 'open';
+    kind: 'object' | 'array';
+    offset: number;
+} | {
+    type: 'key';
+    key: string;
+    offset: number;
+} | {
+    type: 'value';
+    value: JsonScalar;
+    offset: number;
+} | {
+    type: 'close';
+    kind: 'object' | 'array';
+    offset: number;
+};
+export interface JsonTokenizerOptions {
+    /** UTF-8 bytes the whole stream may take. Default {@link DEFAULT_STREAM_MAX_BYTES}. */
+    maxBytes?: number;
+    /** Containers that may nest. Default {@link DEFAULT_STREAM_MAX_DEPTH}. */
+    maxDepth?: number;
+}
+export interface JsonTokenizer {
+    /** Feed the next chunk; returns the tokens that closed inside it. */
+    write(chunk: string): JsonStreamEvent[];
+    /** No more input: closes a trailing top-level number or literal, or reports `truncated`. */
+    end(): JsonStreamEvent[];
+    /** UTF-8 bytes read so far. */
+    readonly bytes: number;
+    /** Open containers right now. */
+    readonly depth: number;
+    /** The first error, or `null`. */
+    readonly error: StreamError | null;
+    /** `true` once `end()` accepted one complete JSON value. */
+    readonly done: boolean;
+}
+/** Default byte budget: the catalog's default tree cap (256 KiB) plus 8 KiB of whitespace. */
+export declare const DEFAULT_STREAM_MAX_BYTES: number;
+/** Default depth cap: the catalog's value-depth guard. */
+export declare const DEFAULT_STREAM_MAX_DEPTH = 128;
+/** Keys refused anywhere in a stream. */
+export declare const STREAM_PROTOTYPE_KEYS: readonly string[];
+export declare function createJsonTokenizer(options?: JsonTokenizerOptions): JsonTokenizer;