@moureau/pipeflow 0.0.1 → 0.0.3

package/dist/esm/providers/tts/adapters/openrouter/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../../src/providers/tts/adapters/openrouter/index.ts"],
+  "sourcesContent": ["export { OpenRouterTTS } from \"./openrouter\";\nexport type { OpenRouterTTSOptions } from \"./openrouter\";\n"],
+  "mappings": "AAAA,OAAS,iBAAAA,MAAqB",
+  "names": ["OpenRouterTTS"]
+}

package/dist/esm/providers/tts/adapters/openrouter/openrouter.js

@@ -0,0 +1,2 @@
+var h=Object.defineProperty;var a=(t,e)=>h(t,"name",{value:e,configurable:!0});class y{static{a(this,"OpenRouterTTS")}apiKey;baseUrl;model;voice;format;chunkSize;idleTimeoutMs;fetchImpl;streams=new Set;constructor(e){if(!e.apiKey)throw new Error("OpenRouterTTS requires an apiKey");this.apiKey=e.apiKey,this.baseUrl=(e.baseUrl??"https://openrouter.ai/api/v1").replace(/\/+$/,""),this.model=e.model??"fish-audio/s2.1-pro-free:free",this.voice=e.voice??"",this.format=e.format??"pcm",this.chunkSize=e.chunkSize??8192,this.idleTimeoutMs=e.idleTimeoutMs??15e3,this.fetchImpl=e.fetch??fetch}stop(){for(const e of this.streams)e.abort()}async*stream(e){if(!e.text)throw new Error("OpenRouterTTS requires request.text");const r=new AbortController;this.streams.add(r);let s=!1;try{const n={model:this.model,input:e.text,...e.voice??this.voice?{voice:e.voice??this.voice}:{},response_format:(e.format??this.format)==="mp3"?"mp3":"pcm"};e.speed!==void 0&&(n.speed=e.speed);const i=await d(this.fetchImpl(`${this.baseUrl}/audio/speech`,{method:"POST",headers:{"content-type":"application/json",authorization:`Bearer ${this.apiKey}`},body:JSON.stringify(n),signal:r.signal}),this.idleTimeoutMs,()=>{s=!0,r.abort()});if(!i.ok){const u=await i.text().catch(()=>"");throw new Error(`OpenRouter TTS failed (${i.status})${u?`: ${u}`:""}`)}if(!i.body)throw new Error("OpenRouter returned an empty body");const l=i.body.getReader();let o=new Uint8Array(0);for(;;){if(r.signal.aborted)throw new DOMException("The operation was aborted.","AbortError");const{done:u,value:c}=await d(l.read(),this.idleTimeoutMs,()=>{s=!0,r.abort()});if(u)break;o=yield*p(m(o,c),this.chunkSize)}o.length>0&&(yield o)}catch(n){throw s?new Error(`OpenRouter TTS produced no audio for ${this.idleTimeoutMs}ms`):n}finally{this.streams.delete(r)}}}function d(t,e,r){return new Promise((s,n)=>{let i;const l=a(()=>clearTimeout(i),"cleanup");i=setTimeout(()=>{l(),r(),n(new Error(`timed out after ${e}ms`))},e),t.then(o=>{l(),s(o)},o=>{l(),n(o)})})}a(d,"withTimeout");function m(t,e){const r=new Uint8Array(t.length+e.length);return r.set(t),r.set(e,t.length),r}a(m,"concat");function*p(t,e){let r=t;for(;r.length>=e;)yield r.slice(0,e),r=r.slice(e);return r}a(p,"sliceChunks");export{y as OpenRouterTTS};
+//# sourceMappingURL=openrouter.js.map

package/dist/esm/providers/tts/adapters/openrouter/openrouter.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../../src/providers/tts/adapters/openrouter/openrouter.ts"],
+  "sourcesContent": ["import type { TTS, TTSRequest } from \"../../types\";\nimport type { FetchLike } from \"../../../shared\";\n\nexport interface OpenRouterTTSOptions {\n  apiKey: string;\n  /** Defaults to `https://openrouter.ai/api/v1`. */\n  baseUrl?: string;\n  /**\n   * TTS model. Defaults to the free `fish-audio/s2.1-pro-free:free` variant \u2014\n   * fast, per-character priced. Pass `fish-audio/s2.1-pro` for the paid tier\n   * (no free-variant rate limits). Note the free variant is intermittently\n   * unavailable on OpenRouter (404 \"No endpoints found\").\n   */\n  model?: string;\n  /**\n   * Default voice, sent when the request carries none. Set it for a\n   * consistent voice: the default fish model accepts exactly `\"alloy\"` and\n   * rejects other names, and omitting `voice` lets the free variant vary the\n   * voice per request. Models like OpenAI TTS require a voice. Voice support\n   * varies by model and provider.\n   */\n  voice?: string;\n  /**\n   * Output format used when the request doesn't specify one. `\"pcm\"` (the\n   * default) is the lowest-latency realtime format, but its sample rate is\n   * provider-defined and opaque \u2014 clients must know it. `\"mp3\"` is\n   * self-describing: decoders read the real rate from the stream.\n   */\n  format?: \"pcm\" | \"mp3\";\n  /** Size of the audio chunks yielded from the response stream. Default 8192. */\n  chunkSize?: number;\n  /**\n   * Abort a synthesis that delivers no audio bytes for this long (default\n   * 15000ms). A provider connection that goes silent \u2014 or never responds \u2014\n   * would otherwise wedge the speech pipeline forever, since the pipeline\n   * holds one synthesis slot and its delivery chain until the stream ends.\n   * Any byte resets the clock; a genuinely slow synthesis just needs a\n   * response within this window.\n   */\n  idleTimeoutMs?: number;\n  /** Injectable fetch, mainly for tests. */\n  fetch?: FetchLike;\n}\n\n/**\n * OpenRouter TTS adapter (`POST /api/v1/audio/speech`, OpenAI-compatible).\n *\n * The endpoint returns raw audio bytes (not JSON) in `mp3` or `pcm` format.\n * The adapter re-chunks the response stream so audio can be played as it\n * arrives; `stop()` aborts the in-flight synthesis. `pcm` is the default\n * output (OpenRouter's own recommendation for realtime pipelines).\n */\nexport class OpenRouterTTS implements TTS {\n  private readonly apiKey: string;\n  private readonly baseUrl: string;\n  private readonly model: string;\n  private readonly voice: string;\n  private readonly format: \"pcm\" | \"mp3\";\n  private readonly chunkSize: number;\n  private readonly idleTimeoutMs: number;\n  private readonly fetchImpl: FetchLike;\n  private readonly streams = new Set<AbortController>();\n\n  constructor(options: OpenRouterTTSOptions) {\n    if (!options.apiKey) {\n      throw new Error(\"OpenRouterTTS requires an apiKey\");\n    }\n    this.apiKey = options.apiKey;\n    this.baseUrl = (options.baseUrl ?? \"https://openrouter.ai/api/v1\").replace(/\\/+$/, \"\");\n    this.model = options.model ?? \"fish-audio/s2.1-pro-free:free\";\n    this.voice = options.voice ?? \"\";\n    this.format = options.format ?? \"pcm\";\n    this.chunkSize = options.chunkSize ?? 8192;\n    this.idleTimeoutMs = options.idleTimeoutMs ?? 15_000;\n    this.fetchImpl = options.fetch ?? fetch;\n  }\n\n  stop(): void {\n    // Abort every in-flight synthesis. Streams are tracked individually so\n    // concurrent requests (the speech pipeline pre-starts the next sentence\n    // while the current one is still streaming) do not cancel each other.\n    for (const controller of this.streams) controller.abort();\n  }\n\n  async *stream(request: TTSRequest): AsyncGenerator<Uint8Array> {\n    if (!request.text) {\n      throw new Error(\"OpenRouterTTS requires request.text\");\n    }\n\n    const controller = new AbortController();\n    this.streams.add(controller);\n    // Every await is bounded by an idle clock: a request that never responds,\n    // or a connection that goes silent mid-stream, aborts with a clear error\n    // instead of holding the speech pipeline's synthesis slot and delivery\n    // chain open forever (the reply would otherwise wait for the next input).\n    let timedOut = false;\n\n    try {\n      const body: Record<string, unknown> = {\n        model: this.model,\n        input: request.text,\n        // Voice is only sent when configured: fish-audio (the default model)\n        // rejects an explicit voice with a 400, while models like OpenAI TTS\n        // require one.\n        ...(request.voice ?? this.voice ? { voice: request.voice ?? this.voice } : {}),\n        // OpenRouter supports mp3 and pcm only; anything else (or\n        // unspecified) maps to pcm, the lower-latency realtime format.\n        response_format: (request.format ?? this.format) === \"mp3\" ? \"mp3\" : \"pcm\",\n      };\n      if (request.speed !== undefined) body.speed = request.speed;\n\n      const response = await withTimeout(\n        this.fetchImpl(`${this.baseUrl}/audio/speech`, {\n          method: \"POST\",\n          headers: {\n            \"content-type\": \"application/json\",\n            authorization: `Bearer ${this.apiKey}`,\n          },\n          body: JSON.stringify(body),\n          signal: controller.signal,\n        }),\n        this.idleTimeoutMs,\n        () => {\n          timedOut = true;\n          controller.abort();\n        },\n      );\n\n      if (!response.ok) {\n        // Non-200 responses carry a JSON error body, not audio.\n        const detail = await response.text().catch(() => \"\");\n        throw new Error(\n          `OpenRouter TTS failed (${response.status})${detail ? `: ${detail}` : \"\"}`,\n        );\n      }\n      if (!response.body) {\n        throw new Error(\"OpenRouter returned an empty body\");\n      }\n\n      const reader = response.body.getReader();\n      let buffer = new Uint8Array(0);\n      while (true) {\n        if (controller.signal.aborted) {\n          throw new DOMException(\"The operation was aborted.\", \"AbortError\");\n        }\n        const { done, value } = await withTimeout(\n          reader.read(),\n          this.idleTimeoutMs,\n          () => {\n            timedOut = true;\n            controller.abort();\n          },\n        );\n        if (done) break;\n        buffer = yield* sliceChunks(concat(buffer, value), this.chunkSize);\n      }\n      if (buffer.length > 0) {\n        yield buffer;\n      }\n    } catch (error) {\n      // Translate the watchdog's abort into a clear failure. Real aborts\n      // (`stop()`, interrupts) keep their AbortError so callers can tell the\n      // difference.\n      if (timedOut) {\n        throw new Error(`OpenRouter TTS produced no audio for ${this.idleTimeoutMs}ms`);\n      }\n      throw error;\n    } finally {\n      this.streams.delete(controller);\n    }\n  }\n}\n\n/**\n * Race `promise` against a timeout: reject after `ms` and fire `onTimeout`\n * (which should abort the underlying request) so a hanging operation is\n * released rather than left pending forever.\n */\nfunction withTimeout<T>(\n  promise: Promise<T>,\n  ms: number,\n  onTimeout: () => void,\n): Promise<T> {\n  return new Promise((resolve, reject) => {\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    const cleanup = () => clearTimeout(timer);\n    timer = setTimeout(() => {\n      cleanup();\n      onTimeout();\n      reject(new Error(`timed out after ${ms}ms`));\n    }, ms);\n    promise.then(\n      (value) => {\n        cleanup();\n        resolve(value);\n      },\n      (error) => {\n        cleanup();\n        reject(error);\n      },\n    );\n  });\n}\n\nfunction concat(\n  a: Uint8Array<ArrayBufferLike>,\n  b: Uint8Array<ArrayBufferLike>,\n): Uint8Array<ArrayBuffer> {\n  const out = new Uint8Array(a.length + b.length);\n  out.set(a);\n  out.set(b, a.length);\n  return out;\n}\n\n/**\n * Yield up to `chunkSize` bytes from `audio`, returning the remainder for\n * the caller to keep buffering. Providers deliver arbitrary chunk\n * boundaries, so audio is re-sliced into uniform pieces.\n */\nfunction* sliceChunks(\n  audio: Uint8Array<ArrayBuffer>,\n  chunkSize: number,\n): Generator<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>, undefined> {\n  let buffer = audio;\n  while (buffer.length >= chunkSize) {\n    yield buffer.slice(0, chunkSize);\n    buffer = buffer.slice(chunkSize);\n  }\n  return buffer;\n}\n"],
+  "mappings": "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",
+  "names": ["OpenRouterTTS", "__name", "options", "controller", "request", "timedOut", "body", "response", "withTimeout", "detail", "reader", "buffer", "done", "value", "sliceChunks", "concat", "error", "promise", "ms", "onTimeout", "resolve", "reject", "timer", "cleanup", "a", "b", "out", "audio", "chunkSize"]
+}

package/dist/esm/transport/streamobject/field-stream/field-stream.js

@@ -0,0 +1,2 @@
+var s=Object.defineProperty;var a=(i,e)=>s(i,"name",{value:e,configurable:!0});import{materializeObject as c}from"../reference/reference.js";class f{static{a(this,"FieldStream")}schema;fieldHandlers;itemHandlers;objectHandlers=new Set;errorHandlers=new Set;onCancel;cancelled=!1;objectState="streaming";constructor(e,r={}){this.schema=e,this.onCancel=r.onCancel,this.fieldHandlers=new Array(e.length),this.itemHandlers=new Array(e.length)}when(e,r){const t=this.resolveIndex(e);return(this.fieldHandlers[t]??=new Set).add(r),this}whenItem(e,r){const t=this.resolveIndex(e),n=this.schema[t];if(n.mode!=="array")throw new TypeError(`whenItem: field "${n.path.join(".")}" is not an array`);return(this.itemHandlers[t]??=new Set).add(r),this}whenObjectDone(e){return this.objectHandlers.add(e),this}onError(e){return this.errorHandlers.add(e),this}cancel(){this.cancelled||(this.cancelled=!0,this.cancelObject(),this.onCancel?.())}beginObject(){this.objectState="streaming"}emitField(e,r){if(this.objectState!=="streaming")return;const t=this.fieldHandlers[e];if(t!==void 0)for(const n of t)this.fire(n,[r])}emitItem(e,r,t){if(this.objectState!=="streaming")return;const n=this.itemHandlers[e];if(n!==void 0)for(const d of n)this.fire(d,[t,r])}emitObject(e){if(this.objectState!=="streaming")return;this.objectState="done";const r=c(this.schema,e);for(const t of this.objectHandlers)this.fire(t,[r])}cancelObject(){this.objectState==="streaming"&&(this.objectState="cancelled")}fail(e){this.objectState==="streaming"&&(this.objectState="failed"),this.dispatchError(o(e))}get objectCompleted(){return this.objectState==="done"}resolveIndex(e){const r=Array.isArray(e)?e.join("."):e,t=this.schema.findIndex(n=>n.path.join(".")===r);if(t===-1)throw new TypeError(`unknown field path: "${r}"`);return t}fire(e,r){try{const t=e(...r);t instanceof Promise&&t.catch(n=>this.dispatchError(o(n)))}catch(t){this.dispatchError(o(t))}}dispatchError(e){if(this.errorHandlers.size===0)throw e;for(const r of this.errorHandlers)try{r(e)}catch{}}}function o(i){return i instanceof Error?i:new Error(String(i))}a(o,"toError");export{f as FieldStream};
+//# sourceMappingURL=field-stream.js.map

package/dist/esm/transport/streamobject/field-stream/field-stream.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/transport/streamobject/field-stream/field-stream.ts"],
+  "sourcesContent": ["/**\n * FieldStream \u2014 the semantic completion core shared by every source adapter.\n *\n * A FieldStream registers completion handlers (`when`/`whenItem`/`whenObjectDone`)\n * and dispatches completion events to them. It knows nothing about JSON, wire\n * records, SSE, or any particular producer: subclasses turn their source into\n * completion events via the protected emit helpers.\n *\n * Implementations:\n *   - StreamObject       \u2014 consumes an AsyncIterable of text chunks (JSON source)\n *   - ConversationStream \u2014 consumes conversation events (provider-native source)\n *\n * Lifecycle, per object:\n *\n *   STREAMING \u2500\u2500emitObject\u2500\u2500\u25B6 DONE\n *       \u2502\n *       \u251C\u2500\u2500cancel()\u2500\u2500\u25B6 CANCELLED\n *       \u2514\u2500\u2500fail()\u2500\u2500\u2500\u2500\u25B6 FAILED\n *\n * Exactly-once: within an object, completion handlers fire at most once per\n * boundary and never after a terminal state (events after DONE/CANCELLED/\n * FAILED are dropped). cancel() is idempotent. Multi-object sources call\n * beginObject() to start each object.\n *\n * `when` means completion, not mutation: handlers never see chunks or source\n * format. Handlers are invoked synchronously at the completion boundary and\n * never block the producer; async handlers run concurrently and their\n * rejections are routed to onError.\n *\n * Errors: delivered to onError handlers when registered; otherwise the\n * subclass decides (StreamObject rejects start(); callers of `fail()` get the\n * throw).\n */\n\nimport type { Event, FieldValue, ScalarValue, Schema } from \"../reference/reference\";\nimport { materializeObject } from \"../reference/reference\";\n\nexport type FieldHandler = (value: FieldValue) => void;\nexport type ItemHandler = (value: ScalarValue, index: number) => void;\nexport type ObjectDoneHandler = (object: Record<string, unknown>) => void;\nexport type ErrorHandler = (error: Error) => void;\n\nexport interface FieldStreamOptions {\n  /** Invoked by cancel() \u2014 e.g. to abort the producer's request. */\n  onCancel?: () => void;\n}\n\ntype ObjectState = \"streaming\" | \"done\" | \"cancelled\" | \"failed\";\n\nexport abstract class FieldStream {\n  protected readonly schema: Schema;\n  private readonly fieldHandlers: Array<Set<FieldHandler> | undefined>;\n  private readonly itemHandlers: Array<Set<ItemHandler> | undefined>;\n  private readonly objectHandlers = new Set<ObjectDoneHandler>();\n  private readonly errorHandlers = new Set<ErrorHandler>();\n  private readonly onCancel: (() => void) | undefined;\n  /** Stream-level: set by cancel(); consumed by source-driven subclasses. */\n  protected cancelled = false;\n  private objectState: ObjectState = \"streaming\";\n\n  constructor(schema: Schema, options: FieldStreamOptions = {}) {\n    this.schema = schema;\n    this.onCancel = options.onCancel;\n    this.fieldHandlers = new Array(schema.length);\n    this.itemHandlers = new Array(schema.length);\n  }\n\n  when(field: string | string[], handler: FieldHandler): this {\n    const index = this.resolveIndex(field);\n    (this.fieldHandlers[index] ??= new Set()).add(handler);\n    return this;\n  }\n\n  whenItem(field: string | string[], handler: ItemHandler): this {\n    const index = this.resolveIndex(field);\n    const def = this.schema[index]!;\n    if (def.mode !== \"array\") {\n      throw new TypeError(`whenItem: field \"${def.path.join(\".\")}\" is not an array`);\n    }\n    (this.itemHandlers[index] ??= new Set()).add(handler);\n    return this;\n  }\n\n  whenObjectDone(handler: ObjectDoneHandler): this {\n    this.objectHandlers.add(handler);\n    return this;\n  }\n\n  onError(handler: ErrorHandler): this {\n    this.errorHandlers.add(handler);\n    return this;\n  }\n\n  /**\n   * Abort the current object and stop the producer (idempotent). The object\n   * will not complete; already-delivered items remain valid partial state.\n   */\n  cancel(): void {\n    if (this.cancelled) return; // idempotent\n    this.cancelled = true;\n    this.cancelObject();\n    this.onCancel?.();\n  }\n\n  /** Start a new object's lifecycle (multi-object sources call this per object). */\n  protected beginObject(): void {\n    this.objectState = \"streaming\";\n  }\n\n  /** Emit a completed field value (subclasses call this at the completion boundary). */\n  protected emitField(field: number, value: FieldValue): void {\n    if (this.objectState !== \"streaming\") return;\n    const handlers = this.fieldHandlers[field];\n    if (handlers === undefined) return;\n    for (const handler of handlers) this.fire(handler, [value]);\n  }\n\n  /** Emit a completed array item. */\n  protected emitItem(field: number, index: number, value: ScalarValue): void {\n    if (this.objectState !== \"streaming\") return;\n    const handlers = this.itemHandlers[field];\n    if (handlers === undefined) return;\n    for (const handler of handlers) this.fire(handler, [value, index]);\n  }\n\n  /**\n   * Complete the current object: materializes and fires whenObjectDone exactly\n   * once (a second call, or a call after cancel/fail, is ignored).\n   */\n  protected emitObject(events: Event[]): void {\n    if (this.objectState !== \"streaming\") return;\n    this.objectState = \"done\";\n    const object = materializeObject(this.schema, events);\n    for (const handler of this.objectHandlers) this.fire(handler, [object]);\n  }\n\n  /** Abort the current object without completing it (idempotent). */\n  protected cancelObject(): void {\n    if (this.objectState === \"streaming\") this.objectState = \"cancelled\";\n  }\n\n  /**\n   * Route a source/adapter failure to onError (or rethrow when unhandled) and\n   * mark the current object failed.\n   */\n  protected fail(error: unknown): void {\n    if (this.objectState === \"streaming\") this.objectState = \"failed\";\n    this.dispatchError(toError(error));\n  }\n\n  protected get objectCompleted(): boolean {\n    return this.objectState === \"done\";\n  }\n\n  protected resolveIndex(field: string | string[]): number {\n    const key = Array.isArray(field) ? field.join(\".\") : field;\n    const index = this.schema.findIndex((def) => def.path.join(\".\") === key);\n    if (index === -1) {\n      throw new TypeError(`unknown field path: \"${key}\"`);\n    }\n    return index;\n  }\n\n  private fire<T extends unknown[]>(handler: (...args: T) => unknown, args: T): void {\n    try {\n      const result = handler(...args);\n      if (result instanceof Promise) {\n        void result.catch((error) => this.dispatchError(toError(error)));\n      }\n    } catch (error) {\n      this.dispatchError(toError(error));\n    }\n  }\n\n  private dispatchError(error: Error): void {\n    if (this.errorHandlers.size === 0) throw error;\n    for (const handler of this.errorHandlers) {\n      try {\n        handler(error);\n      } catch {\n        // a failing error handler is not re-dispatched\n      }\n    }\n  }\n}\n\nfunction toError(error: unknown): Error {\n  return error instanceof Error ? error : new Error(String(error));\n}\n"],
+  "mappings": "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",
+  "names": ["materializeObject", "FieldStream", "__name", "schema", "options", "field", "handler", "index", "def", "value", "handlers", "events", "object", "error", "toError", "key", "args", "result"]
+}

package/dist/esm/transport/streamobject/field-stream/index.js

@@ -0,0 +1,2 @@
+import{FieldStream as t}from"./field-stream.js";export{t as FieldStream};
+//# sourceMappingURL=index.js.map

package/dist/esm/transport/streamobject/field-stream/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/transport/streamobject/field-stream/index.ts"],
+  "sourcesContent": ["export { FieldStream } from \"./field-stream\";\nexport type {\n  ErrorHandler,\n  FieldHandler,\n  FieldStreamOptions,\n  ItemHandler,\n  ObjectDoneHandler,\n} from \"./field-stream\";\n"],
+  "mappings": "AAAA,OAAS,eAAAA,MAAmB",
+  "names": ["FieldStream"]
+}

package/dist/esm/transport/streamobject/index.js

@@ -0,0 +1,2 @@
+import{FieldStream as a}from"./field-stream/index.js";import{StreamObject as t}from"./stream-object/index.js";import{IncrementalJsonParser as l,JsonToStreamObjectAdapter as n}from"./json-adapter/index.js";import{ReferenceDecoder as p,Receiver as c,decode as i,encodeText as s,executeRecords as x,materializeObject as f,parseBooleanPayload as y,parseIntegerPayload as b,parseNumberPayload as S}from"./reference/index.js";export{a as FieldStream,l as IncrementalJsonParser,n as JsonToStreamObjectAdapter,c as Receiver,p as ReferenceDecoder,t as StreamObject,i as decode,s as encodeText,x as executeRecords,f as materializeObject,y as parseBooleanPayload,b as parseIntegerPayload,S as parseNumberPayload};
+//# sourceMappingURL=index.js.map

package/dist/esm/transport/streamobject/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/transport/streamobject/index.ts"],
+  "sourcesContent": ["// StreamObject \u2014 a schema-bound streaming semantic protocol.\n//\n// Turns a text-chunk source (LLM deltas, SSE, wire records, conversation\n// events) into completion events: consumers act when the value they depend on\n// completes, without waiting for the enclosing object. See README.md.\nexport { FieldStream } from \"./field-stream/index\";\nexport type {\n  ErrorHandler,\n  FieldHandler,\n  FieldStreamOptions,\n  ItemHandler,\n  ObjectDoneHandler,\n} from \"./field-stream/index\";\nexport { StreamObject } from \"./stream-object/index\";\nexport type { StreamObjectOptions } from \"./stream-object/index\";\nexport { IncrementalJsonParser, JsonToStreamObjectAdapter } from \"./json-adapter/index\";\nexport type { JsonAdapterCallbacks, JsonValue } from \"./json-adapter/index\";\nexport {\n  ReferenceDecoder,\n  Receiver,\n  decode,\n  encodeText,\n  executeRecords,\n  materializeObject,\n  parseBooleanPayload,\n  parseIntegerPayload,\n  parseNumberPayload,\n} from \"./reference/index\";\nexport type {\n  Decoder,\n  Event,\n  FieldDef,\n  FieldType,\n  FieldValue,\n  Payload,\n  ScalarValue,\n  Schema,\n  StreamRecord,\n} from \"./reference/index\";\n"],
+  "mappings": "AAKA,OAAS,eAAAA,MAAmB,uBAQ5B,OAAS,gBAAAC,MAAoB,wBAE7B,OAAS,yBAAAC,EAAuB,6BAAAC,MAAiC,uBAEjE,OACE,oBAAAC,EACA,YAAAC,EACA,UAAAC,EACA,cAAAC,EACA,kBAAAC,EACA,qBAAAC,EACA,uBAAAC,EACA,uBAAAC,EACA,sBAAAC,MACK",
+  "names": ["FieldStream", "StreamObject", "IncrementalJsonParser", "JsonToStreamObjectAdapter", "ReferenceDecoder", "Receiver", "decode", "encodeText", "executeRecords", "materializeObject", "parseBooleanPayload", "parseIntegerPayload", "parseNumberPayload"]
+}

package/dist/esm/transport/streamobject/json-adapter/index.js

@@ -0,0 +1,2 @@
+import{IncrementalJsonParser as a,JsonToStreamObjectAdapter as o}from"./json-adapter.js";export{a as IncrementalJsonParser,o as JsonToStreamObjectAdapter};
+//# sourceMappingURL=index.js.map

package/dist/esm/transport/streamobject/json-adapter/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/transport/streamobject/json-adapter/index.ts"],
+  "sourcesContent": ["export { IncrementalJsonParser, JsonToStreamObjectAdapter } from \"./json-adapter\";\nexport type { JsonAdapterCallbacks, JsonValue } from \"./json-adapter\";\n"],
+  "mappings": "AAAA,OAAS,yBAAAA,EAAuB,6BAAAC,MAAiC",
+  "names": ["IncrementalJsonParser", "JsonToStreamObjectAdapter"]
+}

package/dist/esm/transport/streamobject/json-adapter/json-adapter.js

@@ -0,0 +1,4 @@
+var y=Object.defineProperty;var s=(n,e)=>y(n,"name",{value:e,configurable:!0});class m{constructor(e){this.onValueDone=e}onValueDone;static{s(this,"IncrementalJsonParser")}stack=[];value=null;started=!1;done=!1;push(e){for(let t=0;t<e.length;t++)this.pushChar(e[t])}pushChar(e){if(this.done)return;if(!this.started){e==="{"&&(this.started=!0,this.stack.push({kind:"object",path:[],map:{},key:null,phase:"key"}));return}let t=e;for(;;){if(this.value!==null){if(this.feedValue(t))return;continue}this.dispatch(t);return}}dispatch(e){if(h(e))return;const t=this.stack[this.stack.length-1];if(t.kind==="object"){if(t.phase==="key"){if(e==='"'){this.value={kind:"string",path:t.path,raw:"",escaped:!1};return}if(e==="}"){this.closeContainer(t);return}if(e===",")return;throw new Error(`JSON: expected key or '}' at path [${t.path.join(".")}], got ${JSON.stringify(e)}`)}if(t.phase==="colon"){if(e===":"){t.phase="value";return}throw new Error(`JSON: expected ':' after key ${JSON.stringify(t.key)}`)}this.startValue(e,t,t.path.concat(t.key??"?"));return}if(e==="]"){this.closeContainer(t);return}e!==","&&this.startValue(e,t,t.path.concat(String(t.items.length)))}startValue(e,t,r){if(e==='"'){this.value={kind:"string",path:r,raw:"",escaped:!1};return}if(e==="{"){this.stack.push({kind:"object",path:r,map:{},key:null,phase:"key"});return}if(e==="["){this.stack.push({kind:"array",path:r,items:[]});return}if(e==="-"||p(e)){this.value={kind:"number",path:r,raw:e};return}if(e==="t"||e==="f"||e==="n"){this.value={kind:"literal",path:r,raw:e};return}throw new Error(`JSON: unexpected value start ${JSON.stringify(e)} at path [${r.join(".")}]`)}feedValue(e){const t=this.value;switch(t.kind){case"string":return e==="\\"?(t.raw+=e,t.escaped=!t.escaped,!0):e==='"'&&!t.escaped?(this.value=null,this.completeValue(t.path,b(t.raw)),!0):(t.raw+=e,t.escaped=!1,!0);case"number":{if(p(e)||e==="-"||e==="+"||e==="."||e==="e"||e==="E")return t.raw+=e,!0;const r=Number(t.raw);if(Number.isNaN(r))throw new Error(`JSON: invalid number ${JSON.stringify(t.raw)}`);return this.value=null,this.completeValue(t.path,r),!1}case"literal":{if(k(e)&&v(t.raw)){const i=t.raw==="true"?!0:t.raw==="false"?!1:null;return this.value=null,this.completeValue(t.path,i),!1}const r=t.raw+e;if(w(r))return t.raw=r,!0;throw new Error(`JSON: invalid literal ${JSON.stringify(r)}`)}}}completeValue(e,t){const r=this.stack[this.stack.length-1];if(r.kind==="object"&&r.phase==="key"){if(typeof t!="string")throw new Error("JSON: object key must be a string");r.key=t,r.phase="colon";return}if(this.onValueDone(e,t),r.kind==="object"){if(r.phase!=="value"||r.key===null)throw new Error(`JSON: unexpected value position at path [${e.join(".")}]`);r.map[r.key]=t,r.key=null,r.phase="key"}else r.items.push(t)}closeContainer(e){const t=e.kind==="object"?e.map:e.items,r=e.path;if(this.stack.pop(),this.stack.length===0){this.done=!0,this.onValueDone(r,t);return}this.completeValue(r,t)}}function b(n){let e="";for(let t=0;t<n.length;t++){const r=n[t];if(r!=="\\"){e+=r;continue}t++;const i=n[t];if(i===void 0)throw new Error("JSON: unterminated escape");switch(i){case'"':e+='"';break;case"\\":e+="\\";break;case"/":e+="/";break;case"b":e+="\b";break;case"f":e+="\f";break;case"n":e+=`
+`;break;case"r":e+="\r";break;case"t":e+="	";break;case"u":{const a=n.slice(t+1,t+5);if(!/^[0-9a-fA-F]{4}$/.test(a))throw new Error("JSON: invalid \\u escape");const o=parseInt(a,16);if(o>=55296&&o<=56319){const u=/^\\u([0-9a-fA-F]{4})/.exec(n.slice(t+5)),l=u?parseInt(u[1],16):-1;if(l>=56320&&l<=57343){e+=String.fromCharCode(o,l),t+=10;break}}e+=String.fromCharCode(o),t+=4;break}default:throw new Error(`JSON: invalid escape \\${i}`)}}return e}s(b,"decodeJsonString");function h(n){return n===" "||n==="	"||n===`
+`||n==="\r"}s(h,"isWhitespace");function p(n){return n>="0"&&n<="9"}s(p,"isDigit");function k(n){return h(n)||n===","||n==="}"||n==="]"}s(k,"isTerminator");function v(n){return n==="true"||n==="false"||n==="null"}s(v,"isCompleteLiteral");function w(n){return"true".startsWith(n)||"false".startsWith(n)||"null".startsWith(n)}s(w,"isLiteralPrefix");class S{static{s(this,"JsonToStreamObjectAdapter")}fields;parser;events=[];onFieldDone;onItemDone;onObjectDone;constructor(e,t={}){this.fields=e.map((r,i)=>({def:r,pathKey:r.path.join(".")})),this.onFieldDone=t.onFieldDone,this.onItemDone=t.onItemDone,this.onObjectDone=t.onObjectDone,this.parser=new m((r,i)=>this.handleValue(r,i))}push(e){this.parser.push(e)}getEvents(){return this.events}handleValue(e,t){const r=e.join(".");if(r===""){this.events.push({kind:"object-complete"}),this.onObjectDone?.();return}const i=this.fields.findIndex(d=>d.pathKey===r);if(i!==-1){const d=J(this.fields[i].def,t),g={kind:"field",field:i,value:d};this.events.push(g),this.onFieldDone?.(i,d);return}if(Array.isArray(t)||typeof t=="object"&&t!==null)return;const a=this.matchArrayItem(e);if(a===-1)return;const o=this.fields[a].def,u=f(o.type,t,o.path.join(".")),l=Number(e[e.length-1]),c={kind:"item",field:a,index:l,value:u};this.events.push(c),this.onItemDone?.(a,l,u)}matchArrayItem(e){if(e.length<2)return-1;const t=e[e.length-1];if(!/^\d+$/.test(t))return-1;const r=e.slice(0,-1).join("."),i=this.fields.findIndex(a=>a.pathKey===r);return i===-1||this.fields[i].def.mode!=="array"?-1:i}}function J(n,e){if(n.mode==="array"){if(!Array.isArray(e))throw new Error(`field ${n.path.join(".")}: expected array, got ${JSON.stringify(e)}`);return e.map(t=>f(n.type,t,n.path.join(".")))}return f(n.type,e,n.path.join("."))}s(J,"coerceToField");function f(n,e,t){switch(n){case"string":if(typeof e!="string")throw new Error(`field ${t}: expected string, got ${JSON.stringify(e)}`);return e;case"integer":if(typeof e!="number"||!Number.isSafeInteger(e))throw new Error(`field ${t}: expected integer, got ${JSON.stringify(e)}`);return e;case"number":if(typeof e!="number"||!Number.isFinite(e))throw new Error(`field ${t}: expected number, got ${JSON.stringify(e)}`);return e;case"boolean":if(typeof e!="boolean")throw new Error(`field ${t}: expected boolean, got ${JSON.stringify(e)}`);return e}}s(f,"coerceScalar");export{m as IncrementalJsonParser,S as JsonToStreamObjectAdapter};
+//# sourceMappingURL=json-adapter.js.map

package/dist/esm/transport/streamobject/json-adapter/json-adapter.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/transport/streamobject/json-adapter/json-adapter.ts"],
+  "sourcesContent": ["/**\n * Incremental JSON \u2192 StreamObject adapter.\n *\n * Consumes a JSON token stream (e.g. LLM output deltas) and emits StreamObject\n * field-completion events as soon as each schema field's value is complete \u2014\n * without waiting for the rest of the object. This is the designed production\n * shape of the protocol: the model emits ordinary output, deterministic\n * software does the parsing, and consumers react at field boundaries.\n *\n * The wire encoding is irrelevant here; only the Event model matters.\n */\n\nimport type { Event, FieldDef, FieldType, FieldValue, ScalarValue, Schema } from \"../reference/reference\";\n\nexport type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };\n\ninterface ObjectCtx {\n  kind: \"object\";\n  path: string[];\n  map: Record<string, JsonValue>;\n  key: string | null; // the key currently awaiting its value\n  phase: \"key\" | \"colon\" | \"value\";\n}\n\ninterface ArrayCtx {\n  kind: \"array\";\n  path: string[];\n  items: JsonValue[];\n}\n\ntype ValueState =\n  | { kind: \"string\"; path: string[]; raw: string; escaped: boolean }\n  | { kind: \"number\"; path: string[]; raw: string }\n  | { kind: \"literal\"; path: string[]; raw: string };\n\n/** Minimal incremental JSON parser. Emits every completed value with its path. */\nexport class IncrementalJsonParser {\n  private readonly stack: Array<ObjectCtx | ArrayCtx> = [];\n  private value: ValueState | null = null;\n  private started = false;\n  private done = false;\n\n  constructor(private readonly onValueDone: (path: string[], value: JsonValue) => void) {}\n\n  push(chunk: string): void {\n    for (let i = 0; i < chunk.length; i++) {\n      this.pushChar(chunk[i]!);\n    }\n  }\n\n  private pushChar(c: string): void {\n    if (this.done) return;\n    if (!this.started) {\n      // Preamble (markdown fences, prose) is ignored until the object starts.\n      if (c === \"{\") {\n        this.started = true;\n        this.stack.push({ kind: \"object\", path: [], map: {}, key: null, phase: \"key\" });\n      }\n      return;\n    }\n    let ch = c;\n    for (;;) {\n      if (this.value !== null) {\n        if (this.feedValue(ch)) return;\n        continue; // the value completed on ch as a terminator; reprocess it\n      }\n      this.dispatch(ch);\n      return;\n    }\n  }\n\n  private dispatch(c: string): void {\n    if (isWhitespace(c)) return;\n    const top = this.stack[this.stack.length - 1]!;\n    if (top.kind === \"object\") {\n      if (top.phase === \"key\") {\n        if (c === '\"') {\n          this.value = { kind: \"string\", path: top.path, raw: \"\", escaped: false };\n          return;\n        }\n        if (c === \"}\") {\n          this.closeContainer(top);\n          return;\n        }\n        if (c === \",\") return; // tolerate trailing commas in model output\n        throw new Error(\n          `JSON: expected key or '}' at path [${top.path.join(\".\")}], got ${JSON.stringify(c)}`,\n        );\n      }\n      if (top.phase === \"colon\") {\n        if (c === \":\") {\n          top.phase = \"value\";\n          return;\n        }\n        throw new Error(`JSON: expected ':' after key ${JSON.stringify(top.key)}`);\n      }\n      this.startValue(c, top, top.path.concat(top.key ?? \"?\"));\n      return;\n    }\n    if (c === \"]\") {\n      this.closeContainer(top);\n      return;\n    }\n    if (c === \",\") return; // tolerate trailing commas\n    this.startValue(c, top, top.path.concat(String(top.items.length)));\n  }\n\n  private startValue(c: string, _top: ObjectCtx | ArrayCtx, path: string[]): void {\n    if (c === '\"') {\n      this.value = { kind: \"string\", path, raw: \"\", escaped: false };\n      return;\n    }\n    if (c === \"{\") {\n      this.stack.push({ kind: \"object\", path, map: {}, key: null, phase: \"key\" });\n      return;\n    }\n    if (c === \"[\") {\n      this.stack.push({ kind: \"array\", path, items: [] });\n      return;\n    }\n    if (c === \"-\" || isDigit(c)) {\n      this.value = { kind: \"number\", path, raw: c };\n      return;\n    }\n    if (c === \"t\" || c === \"f\" || c === \"n\") {\n      this.value = { kind: \"literal\", path, raw: c };\n      return;\n    }\n    throw new Error(`JSON: unexpected value start ${JSON.stringify(c)} at path [${path.join(\".\")}]`);\n  }\n\n  private feedValue(c: string): boolean {\n    const v = this.value!;\n    switch (v.kind) {\n      case \"string\": {\n        if (c === \"\\\\\") {\n          v.raw += c;\n          v.escaped = !v.escaped;\n          return true;\n        }\n        if (c === '\"' && !v.escaped) {\n          this.value = null;\n          this.completeValue(v.path, decodeJsonString(v.raw));\n          return true;\n        }\n        v.raw += c;\n        v.escaped = false;\n        return true;\n      }\n      case \"number\": {\n        if (isDigit(c) || c === \"-\" || c === \"+\" || c === \".\" || c === \"e\" || c === \"E\") {\n          v.raw += c;\n          return true;\n        }\n        const n = Number(v.raw);\n        if (Number.isNaN(n)) throw new Error(`JSON: invalid number ${JSON.stringify(v.raw)}`);\n        this.value = null;\n        this.completeValue(v.path, n);\n        return false; // reprocess the terminator\n      }\n      case \"literal\": {\n        if (isTerminator(c) && isCompleteLiteral(v.raw)) {\n          const value = v.raw === \"true\" ? true : v.raw === \"false\" ? false : null;\n          this.value = null;\n          this.completeValue(v.path, value);\n          return false; // reprocess the terminator\n        }\n        const text = v.raw + c;\n        if (isLiteralPrefix(text)) {\n          v.raw = text;\n          return true;\n        }\n        throw new Error(`JSON: invalid literal ${JSON.stringify(text)}`);\n      }\n    }\n  }\n\n  private completeValue(path: string[], value: JsonValue): void {\n    const top = this.stack[this.stack.length - 1]!;\n    if (top.kind === \"object\" && top.phase === \"key\") {\n      // The completed string was an object key, not a value.\n      if (typeof value !== \"string\") throw new Error(\"JSON: object key must be a string\");\n      top.key = value;\n      top.phase = \"colon\";\n      return;\n    }\n    this.onValueDone(path, value);\n    if (top.kind === \"object\") {\n      if (top.phase !== \"value\" || top.key === null) {\n        throw new Error(`JSON: unexpected value position at path [${path.join(\".\")}]`);\n      }\n      top.map[top.key] = value;\n      top.key = null;\n      top.phase = \"key\";\n    } else {\n      top.items.push(value);\n    }\n  }\n\n  private closeContainer(ctx: ObjectCtx | ArrayCtx): void {\n    const value: JsonValue = ctx.kind === \"object\" ? ctx.map : ctx.items;\n    const path = ctx.path;\n    this.stack.pop();\n    if (this.stack.length === 0) {\n      this.done = true;\n      this.onValueDone(path, value);\n      return;\n    }\n    this.completeValue(path, value);\n  }\n}\n\n/** Decode the raw content of a JSON string literal (escapes and \\uXXXX). */\nfunction decodeJsonString(raw: string): string {\n  let out = \"\";\n  for (let i = 0; i < raw.length; i++) {\n    const c = raw[i]!;\n    if (c !== \"\\\\\") {\n      out += c;\n      continue;\n    }\n    i++;\n    const esc = raw[i];\n    if (esc === undefined) throw new Error(\"JSON: unterminated escape\");\n    switch (esc) {\n      case '\"': out += '\"'; break;\n      case \"\\\\\": out += \"\\\\\"; break;\n      case \"/\": out += \"/\"; break;\n      case \"b\": out += \"\\b\"; break;\n      case \"f\": out += \"\\f\"; break;\n      case \"n\": out += \"\\n\"; break;\n      case \"r\": out += \"\\r\"; break;\n      case \"t\": out += \"\\t\"; break;\n      case \"u\": {\n        const hex = raw.slice(i + 1, i + 5);\n        if (!/^[0-9a-fA-F]{4}$/.test(hex)) throw new Error(\"JSON: invalid \\\\u escape\");\n        const code = parseInt(hex, 16);\n        // Combine surrogate pairs (\\uD83D\\uDE00 \u2192 \uD83D\uDE00).\n        if (code >= 0xd800 && code <= 0xdbff) {\n          const low = /^\\\\u([0-9a-fA-F]{4})/.exec(raw.slice(i + 5));\n          const lowCode = low ? parseInt(low[1]!, 16) : -1;\n          if (lowCode >= 0xdc00 && lowCode <= 0xdfff) {\n            out += String.fromCharCode(code, lowCode);\n            i += 10;\n            break;\n          }\n        }\n        out += String.fromCharCode(code);\n        i += 4;\n        break;\n      }\n      default:\n        throw new Error(`JSON: invalid escape \\\\${esc}`);\n    }\n  }\n  return out;\n}\n\nfunction isWhitespace(c: string): boolean {\n  return c === \" \" || c === \"\\t\" || c === \"\\n\" || c === \"\\r\";\n}\n\nfunction isDigit(c: string): boolean {\n  return c >= \"0\" && c <= \"9\";\n}\n\nfunction isTerminator(c: string): boolean {\n  return isWhitespace(c) || c === \",\" || c === \"}\" || c === \"]\";\n}\n\nfunction isCompleteLiteral(text: string): boolean {\n  return text === \"true\" || text === \"false\" || text === \"null\";\n}\n\nfunction isLiteralPrefix(text: string): boolean {\n  return (\n    \"true\".startsWith(text) || \"false\".startsWith(text) || \"null\".startsWith(text)\n  );\n}\n\n// ---------------------------------------------------------------------------\n// Schema-aware adapter: JSON values \u2192 StreamObject field-completion events\n// ---------------------------------------------------------------------------\n\nexport interface JsonAdapterCallbacks {\n  onFieldDone?: (field: number, value: FieldValue) => void;\n  /** Fires for each completed array element, before the array field completes. */\n  onItemDone?: (field: number, index: number, value: ScalarValue) => void;\n  /** Fires when the root object closes. */\n  onObjectDone?: () => void;\n}\n\n/**\n * Feeds a JSON token stream into the reference Event model and emits a\n * completion hierarchy as soon as each piece is known:\n *\n *   VALUE_COMPLETE  \u2192 every parsed value (parser level, per path)\n *   ITEM_COMPLETE   \u2192 each array element of an array-typed schema field\n *   FIELD_COMPLETE  \u2192 a schema field's whole value (incl. a closed array)\n *   OBJECT_COMPLETE \u2192 the object closed\n *\n * The v0.1 wire decoder only exposes FIELD/OBJECT; item completion is a\n * semantic projection of array boundaries that every source already carries\n * (each JSON array element, each array append), not a wire record. Strictly\n * typed against the schema \u2014 a value that violates its field type throws.\n */\nexport class JsonToStreamObjectAdapter {\n  private readonly fields: Array<{ def: FieldDef; pathKey: string }>;\n  private readonly parser: IncrementalJsonParser;\n  private readonly events: Event[] = [];\n  private readonly onFieldDone: ((field: number, value: FieldValue) => void) | undefined;\n  private readonly onItemDone: ((field: number, index: number, value: ScalarValue) => void) | undefined;\n  private readonly onObjectDone: (() => void) | undefined;\n\n  constructor(schema: Schema, callbacks: JsonAdapterCallbacks = {}) {\n    this.fields = schema.map((def, field) => ({ def, pathKey: def.path.join(\".\") }));\n    this.onFieldDone = callbacks.onFieldDone;\n    this.onItemDone = callbacks.onItemDone;\n    this.onObjectDone = callbacks.onObjectDone;\n    this.parser = new IncrementalJsonParser((path, value) => this.handleValue(path, value));\n  }\n\n  push(chunk: string): void {\n    this.parser.push(chunk);\n  }\n\n  getEvents(): Event[] {\n    return this.events;\n  }\n\n  private handleValue(path: string[], value: JsonValue): void {\n    const pathKey = path.join(\".\");\n    if (pathKey === \"\") {\n      // The root object closed.\n      this.events.push({ kind: \"object-complete\" });\n      this.onObjectDone?.();\n      return;\n    }\n    const index = this.fields.findIndex((f) => f.pathKey === pathKey);\n    if (index !== -1) {\n      // Whole field value (a scalar, or the completed array).\n      const fieldValue = coerceToField(this.fields[index]!.def, value);\n      const event: Event = { kind: \"field\", field: index, value: fieldValue };\n      this.events.push(event);\n      this.onFieldDone?.(index, fieldValue);\n      return;\n    }\n    // Array element: path = fieldPath + numeric segment, field is array mode.\n    if (Array.isArray(value) || (typeof value === \"object\" && value !== null)) return;\n    const itemField = this.matchArrayItem(path);\n    if (itemField === -1) return;\n    const def = this.fields[itemField]!.def;\n    const item = coerceScalar(def.type, value, def.path.join(\".\"));\n    const itemIndex = Number(path[path.length - 1]);\n    const itemEvent: Event = { kind: \"item\", field: itemField, index: itemIndex, value: item };\n    this.events.push(itemEvent);\n    this.onItemDone?.(itemField, itemIndex, item);\n  }\n\n  private matchArrayItem(path: string[]): number {\n    if (path.length < 2) return -1;\n    const last = path[path.length - 1]!;\n    if (!/^\\d+$/.test(last)) return -1;\n    const parentKey = path.slice(0, -1).join(\".\");\n    const index = this.fields.findIndex((f) => f.pathKey === parentKey);\n    if (index === -1 || this.fields[index]!.def.mode !== \"array\") return -1;\n    return index;\n  }\n}\n\nfunction coerceToField(def: FieldDef, value: JsonValue): FieldValue {\n  if (def.mode === \"array\") {\n    if (!Array.isArray(value)) {\n      throw new Error(`field ${def.path.join(\".\")}: expected array, got ${JSON.stringify(value)}`);\n    }\n    return value.map((item) => coerceScalar(def.type, item, def.path.join(\".\")));\n  }\n  return coerceScalar(def.type, value, def.path.join(\".\"));\n}\n\nfunction coerceScalar(type: FieldType, value: JsonValue, label: string): ScalarValue {\n  switch (type) {\n    case \"string\":\n      if (typeof value !== \"string\") {\n        throw new Error(`field ${label}: expected string, got ${JSON.stringify(value)}`);\n      }\n      return value;\n    case \"integer\":\n      if (typeof value !== \"number\" || !Number.isSafeInteger(value)) {\n        throw new Error(`field ${label}: expected integer, got ${JSON.stringify(value)}`);\n      }\n      return value;\n    case \"number\":\n      if (typeof value !== \"number\" || !Number.isFinite(value)) {\n        throw new Error(`field ${label}: expected number, got ${JSON.stringify(value)}`);\n      }\n      return value;\n    case \"boolean\":\n      if (typeof value !== \"boolean\") {\n        throw new Error(`field ${label}: expected boolean, got ${JSON.stringify(value)}`);\n      }\n      return value;\n  }\n}\n"],
+  "mappings": "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",
+  "names": ["IncrementalJsonParser", "onValueDone", "__name", "chunk", "i", "c", "ch", "isWhitespace", "top", "_top", "path", "isDigit", "v", "decodeJsonString", "n", "isTerminator", "isCompleteLiteral", "value", "text", "isLiteralPrefix", "ctx", "raw", "out", "esc", "hex", "code", "low", "lowCode", "JsonToStreamObjectAdapter", "schema", "callbacks", "def", "field", "pathKey", "index", "f", "fieldValue", "coerceToField", "event", "itemField", "item", "coerceScalar", "itemIndex", "itemEvent", "last", "parentKey", "type", "label"]
+}

package/dist/esm/transport/streamobject/reference/index.js

@@ -0,0 +1,2 @@
+import{ReferenceDecoder as r,Receiver as o,decode as d,encodeText as c,executeRecords as l,materializeObject as t,parseBooleanPayload as p,parseIntegerPayload as i,parseNumberPayload as m}from"./reference.js";export{o as Receiver,r as ReferenceDecoder,d as decode,c as encodeText,l as executeRecords,t as materializeObject,p as parseBooleanPayload,i as parseIntegerPayload,m as parseNumberPayload};
+//# sourceMappingURL=index.js.map

package/dist/esm/transport/streamobject/reference/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/transport/streamobject/reference/index.ts"],
+  "sourcesContent": ["export {\n  ReferenceDecoder,\n  Receiver,\n  decode,\n  encodeText,\n  executeRecords,\n  materializeObject,\n  parseBooleanPayload,\n  parseIntegerPayload,\n  parseNumberPayload,\n} from \"./reference\";\nexport type {\n  Decoder,\n  Event,\n  FieldDef,\n  FieldType,\n  FieldValue,\n  Payload,\n  ScalarValue,\n  Schema,\n  StreamRecord,\n} from \"./reference\";\n"],
+  "mappings": "AAAA,OACE,oBAAAA,EACA,YAAAC,EACA,UAAAC,EACA,cAAAC,EACA,kBAAAC,EACA,qBAAAC,EACA,uBAAAC,EACA,uBAAAC,EACA,sBAAAC,MACK",
+  "names": ["ReferenceDecoder", "Receiver", "decode", "encodeText", "executeRecords", "materializeObject", "parseBooleanPayload", "parseIntegerPayload", "parseNumberPayload"]
+}

package/dist/esm/transport/streamobject/reference/reference.js

@@ -0,0 +1,2 @@
+var v=Object.defineProperty;var s=(r,e)=>v(r,"name",{value:e,configurable:!0});const y=/^-?(0|[1-9][0-9]*)$/,w=/^-?(0|[1-9][0-9]*)(\.[0-9]+)?([eE][+-]?[0-9]+)?$/;function E(r){if(!y.test(r)||r==="-0")return null;const e=Number(r);return Number.isSafeInteger(e)?e:null}s(E,"parseIntegerPayload");function x(r){if(!w.test(r))return null;const e=Number(r);return Number.isFinite(e)?e:null}s(x,"parseNumberPayload");function k(r){return r==="0"?!1:r==="1"?!0:null}s(k,"parseBooleanPayload");function h(r,e,t){switch(r){case"string":return e;case"integer":{const n=E(e);if(n===null)throw new Error(`field ${t}: invalid integer payload`);return n}case"number":{const n=x(e);if(n===null)throw new Error(`field ${t}: invalid number payload`);return n}case"boolean":{const n=k(e);if(n===null)throw new Error(`field ${t}: invalid boolean payload`);return n}}}s(h,"parseTyped");class u{static{s(this,"Receiver")}schema;state;acc;events=[];onEvent;ended=!1;constructor(e,t){this.schema=e,this.onEvent=t,this.state=new Uint8Array(e.length),this.acc=new Array(e.length)}append(e,t){if(this.assertActive(),this.assertField(e),this.state[e]===2)throw new Error(`field ${e}: append after completion`);const n=this.schema[e];if(n.mode==="array"){const i=this.acc[e]??=[],o=n.maxItems;if(i.length>=o)throw new Error(`field ${e}: exceeds maxItems=${o}`);if(n.maxLength!==void 0&&t.length>n.maxLength)throw new Error(`field ${e}: item exceeds maxLength=${n.maxLength}`);i.push(t)}else{const i=this.acc[e]??="";if(n.maxLength!==void 0&&i.length+t.length>n.maxLength)throw new Error(`field ${e}: exceeds maxLength=${n.maxLength}`);this.acc[e]=i+t}this.state[e]=1}complete(e){if(this.assertActive(),this.assertField(e),this.state[e]===2)throw new Error(`field ${e}: completed twice`);const t=this.schema[e];if(this.state[e]===0){if(t.type!=="string"&&t.mode!=="array")throw new Error(`field ${e}: cannot complete an empty ${t.type} field`);this.state[e]=2,this.emit({kind:"field",field:e,value:t.mode==="array"?[]:""});return}this.state[e]=2,this.emit({kind:"field",field:e,value:S(this.schema,e,this.acc[e])})}objectComplete(){this.assertActive(),this.ended=!0,this.emit({kind:"object-complete"})}objectAbort(){this.assertActive(),this.ended=!0,this.emit({kind:"object-abort"})}getEvents(){return this.events}get isEnded(){return this.ended}assertActive(){if(this.ended)throw new Error("object already ended")}assertField(e){if(e<0||e>=this.schema.length)throw new Error(`unknown field ${e}`)}emit(e){this.events.push(e),this.onEvent?.(e)}}function S(r,e,t){const n=r[e];return n.mode==="array"?t.map(i=>h(n.type,i,e)):h(n.type,t,e)}s(S,"materialize");function M(r,e){const t=new u(r);for(const n of e)switch(n.kind){case"append":t.append(n.field,n.payload);break;case"complete":t.complete(n.field);break;case"object-complete":t.objectComplete();break;case"object-abort":t.objectAbort();break}if(!t.isEnded)throw new Error("stream ended before object completion");return t.getEvents()}s(M,"executeRecords");function P(r,e){const t={};for(const n of e)n.kind==="field"&&R(t,r[n.field].path,n.value);return t}s(P,"materializeObject");function R(r,e,t){let n=r;for(let i=0;i<e.length-1;i++){const o=e[i];(typeof n[o]!="object"||n[o]===null)&&(n[o]={}),n=n[o]}n[e[e.length-1]]=t}s(R,"setPath");function T(r){let e="";for(const t of r)switch(t.kind){case"append":e+=`${t.field}:${t.payload.length}:${t.payload};`;break;case"complete":e+=`!${t.field};`;break;case"object-complete":e+="!;";break;case"object-abort":e+="~;";break}return e}s(T,"encodeText");class ${static{s(this,"ReferenceDecoder")}receiver;state="header";fieldId="";length="";payload="";remaining=0;constructor(e,t){this.receiver=new u(e,t)}push(e){for(let t=0;t<e.length;t++){const n=e[t];switch(this.state){case"header":this.onHeader(n);break;case"field-id":this.onFieldId(n);break;case"length":this.onLength(n);break;case"payload":this.onPayload(n);break;case"payload-end":this.onPayloadEnd(n);break;case"control":this.onControl(n);break;case"abort":this.onAbort(n);break}}}end(){if(!this.receiver.isEnded)throw new Error("stream ended before object completion");return this.receiver.getEvents()}onHeader(e){if(c(e)){this.reset(),this.fieldId=e,this.state="field-id";return}if(e==="!"){this.reset(),this.state="control";return}if(e==="~"){this.state="abort";return}throw new Error(`expected record start, got ${JSON.stringify(e)}`)}onFieldId(e){if(c(e)){this.fieldId+=e;return}if(e===":"){this.state="length";return}throw new Error(`expected ':' after field id, got ${JSON.stringify(e)}`)}onLength(e){if(c(e)){this.length+=e;return}if(e===":"){if(this.length==="")throw new Error("empty payload length");this.remaining=Number(this.length),this.payload="",this.state=this.remaining===0?"payload-end":"payload";return}throw new Error(`expected ':' after length, got ${JSON.stringify(e)}`)}onPayload(e){this.payload+=e,--this.remaining===0&&(this.state="payload-end")}onPayloadEnd(e){if(e!==";")throw new Error(`expected ';' after payload, got ${JSON.stringify(e)}`);this.receiver.append(Number(this.fieldId),this.payload),this.state="header"}onControl(e){if(c(e)){this.fieldId+=e;return}if(e===";"){this.fieldId===""?this.receiver.objectComplete():this.receiver.complete(Number(this.fieldId)),this.state="header";return}throw new Error(`expected field id or ';' after '!', got ${JSON.stringify(e)}`)}onAbort(e){if(e!==";")throw new Error(`expected ';' after '~', got ${JSON.stringify(e)}`);this.receiver.objectAbort(),this.state="header"}reset(){this.fieldId="",this.length="",this.payload="",this.remaining=0}}function c(r){return r>="0"&&r<="9"}s(c,"isDigit");function C(r,e){const t=new $(e);for(const n of r)t.push(n);return t.end()}s(C,"decode");function V(r){let e=r>>>0;return()=>{e=e+1831565813>>>0;let t=e;return t=Math.imul(t^t>>>15,t|1),t^=t+Math.imul(t^t>>>7,t|61),((t^t>>>14)>>>0)/4294967296}}s(V,"mulberry32");function O(r,e){const t=[];for(let o=1;o<r.length;o++)e()<.3&&t.push(o);const n=[];let i=0;for(const o of t)n.push(r.slice(i,o)),i=o;return n.push(r.slice(i)),n}s(O,"fragment");function D(r){const e=[];for(let t=1;t<r.length;t++)e.push([r.slice(0,t),r.slice(t)]);return e}s(D,"allSingleCuts");function J(r){const e=[];for(let t=0;t<1<<r.length-1;t++){const n=[];let i=0;for(let o=1;o<r.length;o++)t&1<<o-1&&(n.push(r.slice(i,o)),i=o);n.push(r.slice(i)),e.push(n)}return e}s(J,"allCompositions");const p=["string","integer","number","boolean"],m="abZ09;:!~ \xE9\u{1F600}";function B(r){const e=1+Math.floor(r()*4),t=[];for(let n=0;n<e;n++){const i=p[Math.floor(r()*p.length)],o=r()<.4;t.push({path:[`f${n}`],type:i,...o?{mode:"array",maxItems:1+Math.floor(r()*4)}:{},...r()<.8?{maxLength:1+Math.floor(r()*16)}:{}})}return t}s(B,"randomSchema");function j(r,e){let t="";for(;t.length<e&&r()<.85;)t+=m[Math.floor(r()*m.length)];return t}s(j,"randomString");function I(r,e,t){switch(e){case"string":return r()<.15?"":j(r,t);case"integer":return String(Math.floor(r()*2e3)-1e3);case"number":{const n=r();return n<.4?String(Math.floor(r()*2e3)-1e3):n<.7?String(Math.round((r()*2e3-1e3)*100)/100):String((r()*2-1)*1e10)}case"boolean":return r()<.5?"0":"1"}}s(I,"randomTyped");function f(r,e,t){const n=t??12;for(let i=0;i<100;i++){const o=I(r,e,n);if(o.length<=n)return o}return e==="string"?"":"0"}s(f,"payloadFor");function F(r,e){if(r.length===0)return[];const t=[];let n=0;for(let i=1;i<e;i++){const o=Math.floor(i*r.length/e);t.push(r.slice(n,o)),n=o}return t.push(r.slice(n)),t.filter(i=>i.length>0)}s(F,"splitFragments");function A(r,e,t){const n=e[t],i=[];if(n.mode==="array"){const l=n.maxItems,b=Math.floor(r()*(l+1));for(let d=0;d<b;d++)i.push({kind:"append",field:t,payload:f(r,n.type,n.maxLength)});return r()<.8&&i.push({kind:"complete",field:t}),i}const o=f(r,n.type,n.maxLength),a=F(o,1+Math.floor(r()*4));for(const l of a)i.push({kind:"append",field:t,payload:l});const g=n.type==="string";return(i.length>0?r()<.85:g&&r()<.5)&&i.push({kind:"complete",field:t}),i}s(A,"fieldRecords");function H(r,e){const t=e.map((o,a)=>({field:a,records:A(r,e,a),pos:0})),n=[];let i=t.reduce((o,a)=>o+a.records.length,0);for(;i>0;){let o=t[Math.floor(r()*t.length)];for(;o.pos>=o.records.length;)o=t[(o.field+1)%t.length];n.push(o.records[o.pos]),o.pos++,i--}return n.push(r()<.1?{kind:"object-abort"}:{kind:"object-complete"}),n}s(H,"generateValidRecords");export{u as Receiver,$ as ReferenceDecoder,J as allCompositions,D as allSingleCuts,C as decode,T as encodeText,M as executeRecords,A as fieldRecords,O as fragment,H as generateValidRecords,P as materializeObject,V as mulberry32,k as parseBooleanPayload,E as parseIntegerPayload,x as parseNumberPayload,B as randomSchema};
+//# sourceMappingURL=reference.js.map

package/dist/esm/transport/streamobject/reference/reference.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/transport/streamobject/reference/reference.ts"],
+  "sourcesContent": ["/**\n * StreamObject Protocol v0.1 \u2014 reference implementation (the executable spec).\n *\n * Deliberately boring: no arena, no pooling, no typed-array chunk chains.\n * Its purpose is to pin down semantics so the optimized receiver can be\n * validated against it instead of inventing behavior.\n *\n * Layering:\n *   records --(encodeText)--> text --(fragment)--> chunks\n *   chunks --(ReferenceDecoder)--> events\n *   records --(Receiver / executeRecords)--> events   <- the oracle\n *\n * Contract (the property every decoder must satisfy):\n *   decode(fragment(encodeText(records)))  ===  executeRecords(records)\n *\n * See README.md (in this directory) for the normative spec this implements.\n */\n\nexport type Payload = string; // payload as a JS string (UTF-16 code units)\n\nexport type StreamRecord =\n  | { kind: \"append\"; field: number; payload: Payload }\n  | { kind: \"complete\"; field: number }\n  | { kind: \"object-complete\" }\n  | { kind: \"object-abort\" };\n\nexport type FieldType = \"string\" | \"integer\" | \"number\" | \"boolean\";\n\nexport interface FieldDef {\n  path: string[];\n  type: FieldType;\n  mode?: \"array\";\n  /** Required for array fields. */\n  maxItems?: number;\n  /** Scalar: cap on accumulated payload length. Array: cap per item. */\n  maxLength?: number;\n}\n\nexport type Schema = FieldDef[];\n\nexport type ScalarValue = string | number | boolean;\nexport type FieldValue = ScalarValue | ScalarValue[];\n\nexport type Event =\n  | { kind: \"field\"; field: number; value: FieldValue }\n  /** Adapter-observable item completion (arrays); not emitted by the v0.1 wire decoder. */\n  | { kind: \"item\"; field: number; index: number; value: ScalarValue }\n  | { kind: \"object-complete\" }\n  | { kind: \"object-abort\" };\n\n// ---- canonical typed payloads (spec \u00A72.1) -----------------------------------\n\nconst INTEGER_RE = /^-?(0|[1-9][0-9]*)$/;\nconst NUMBER_RE = /^-?(0|[1-9][0-9]*)(\\.[0-9]+)?([eE][+-]?[0-9]+)?$/;\n\nexport function parseIntegerPayload(s: string): number | null {\n  if (!INTEGER_RE.test(s)) return null;\n  if (s === \"-0\") return null;\n  const n = Number(s);\n  return Number.isSafeInteger(n) ? n : null;\n}\n\nexport function parseNumberPayload(s: string): number | null {\n  if (!NUMBER_RE.test(s)) return null;\n  const n = Number(s);\n  return Number.isFinite(n) ? n : null;\n}\n\nexport function parseBooleanPayload(s: string): boolean | null {\n  if (s === \"0\") return false;\n  if (s === \"1\") return true;\n  return null;\n}\n\nfunction parseTyped(type: FieldType, s: string, field: number): ScalarValue {\n  switch (type) {\n    case \"string\":\n      return s;\n    case \"integer\": {\n      const v = parseIntegerPayload(s);\n      if (v === null) throw new Error(`field ${field}: invalid integer payload`);\n      return v;\n    }\n    case \"number\": {\n      const v = parseNumberPayload(s);\n      if (v === null) throw new Error(`field ${field}: invalid number payload`);\n      return v;\n    }\n    case \"boolean\": {\n      const v = parseBooleanPayload(s);\n      if (v === null) throw new Error(`field ${field}: invalid boolean payload`);\n      return v;\n    }\n  }\n}\n\n// ---- semantic engine (shared by oracle and decoder) --------------------------\n\nexport class Receiver {\n  private readonly schema: Schema;\n  private readonly state: Uint8Array; // 0 unseen, 1 streaming, 2 done\n  private readonly acc: Array<string | string[]>;\n  private readonly events: Event[] = [];\n  private readonly onEvent: ((event: Event) => void) | undefined;\n  private ended = false;\n\n  constructor(schema: Schema, onEvent?: (event: Event) => void) {\n    this.schema = schema;\n    this.onEvent = onEvent;\n    this.state = new Uint8Array(schema.length);\n    this.acc = new Array(schema.length);\n  }\n\n  append(field: number, payload: string): void {\n    this.assertActive();\n    this.assertField(field);\n    if (this.state[field] === 2) {\n      throw new Error(`field ${field}: append after completion`);\n    }\n    const def = this.schema[field]!;\n    if (def.mode === \"array\") {\n      const items = (this.acc[field] ??= []) as string[];\n      const maxItems = def.maxItems as number;\n      if (items.length >= maxItems) {\n        throw new Error(`field ${field}: exceeds maxItems=${maxItems}`);\n      }\n      if (def.maxLength !== undefined && payload.length > def.maxLength) {\n        throw new Error(`field ${field}: item exceeds maxLength=${def.maxLength}`);\n      }\n      items.push(payload);\n    } else {\n      const current = (this.acc[field] ??= \"\") as string;\n      if (def.maxLength !== undefined && current.length + payload.length > def.maxLength) {\n        throw new Error(`field ${field}: exceeds maxLength=${def.maxLength}`);\n      }\n      this.acc[field] = current + payload;\n    }\n    this.state[field] = 1;\n  }\n\n  complete(field: number): void {\n    this.assertActive();\n    this.assertField(field);\n    if (this.state[field] === 2) {\n      throw new Error(`field ${field}: completed twice`);\n    }\n    const def = this.schema[field]!;\n    if (this.state[field] === 0) {\n      if (def.type !== \"string\" && def.mode !== \"array\") {\n        throw new Error(`field ${field}: cannot complete an empty ${def.type} field`);\n      }\n      this.state[field] = 2;\n      this.emit({ kind: \"field\", field, value: def.mode === \"array\" ? [] : \"\" });\n      return;\n    }\n    this.state[field] = 2;\n    this.emit({\n      kind: \"field\",\n      field,\n      value: materialize(this.schema, field, this.acc[field] as string | string[]),\n    });\n  }\n\n  objectComplete(): void {\n    this.assertActive();\n    this.ended = true;\n    this.emit({ kind: \"object-complete\" });\n  }\n\n  objectAbort(): void {\n    this.assertActive();\n    this.ended = true;\n    this.emit({ kind: \"object-abort\" });\n  }\n\n  getEvents(): Event[] {\n    return this.events;\n  }\n\n  get isEnded(): boolean {\n    return this.ended;\n  }\n\n  private assertActive(): void {\n    if (this.ended) throw new Error(\"object already ended\");\n  }\n\n  private assertField(field: number): void {\n    if (field < 0 || field >= this.schema.length) {\n      throw new Error(`unknown field ${field}`);\n    }\n  }\n\n  private emit(event: Event): void {\n    this.events.push(event);\n    this.onEvent?.(event);\n  }\n}\n\nfunction materialize(schema: Schema, field: number, raw: string | string[]): FieldValue {\n  const def = schema[field]!;\n  if (def.mode === \"array\") {\n    return (raw as string[]).map((item) => parseTyped(def.type, item, field));\n  }\n  return parseTyped(def.type, raw as string, field);\n}\n\n/** The oracle: execute logical records directly. */\nexport function executeRecords(schema: Schema, records: StreamRecord[]): Event[] {\n  const receiver = new Receiver(schema);\n  for (const record of records) {\n    switch (record.kind) {\n      case \"append\":\n        receiver.append(record.field, record.payload);\n        break;\n      case \"complete\":\n        receiver.complete(record.field);\n        break;\n      case \"object-complete\":\n        receiver.objectComplete();\n        break;\n      case \"object-abort\":\n        receiver.objectAbort();\n        break;\n    }\n  }\n  if (!receiver.isEnded) throw new Error(\"stream ended before object completion\");\n  return receiver.getEvents();\n}\n\n// ---- materialization ----------------------------------------------------------\n\nexport function materializeObject(schema: Schema, events: Event[]): Record<string, unknown> {\n  const object: Record<string, unknown> = {};\n  for (const event of events) {\n    if (event.kind !== \"field\") continue;\n    setPath(object, schema[event.field]!.path, event.value);\n  }\n  return object;\n}\n\nfunction setPath(object: Record<string, unknown>, path: string[], value: unknown): void {\n  let target = object;\n  for (let i = 0; i < path.length - 1; i++) {\n    const key = path[i]!;\n    if (typeof target[key] !== \"object\" || target[key] === null) {\n      target[key] = {};\n    }\n    target = target[key] as Record<string, unknown>;\n  }\n  target[path[path.length - 1]!] = value;\n}\n\n// ---- reference text encoding (spec \u00A78) ----------------------------------------\n\nexport function encodeText(records: StreamRecord[]): string {\n  let out = \"\";\n  for (const record of records) {\n    switch (record.kind) {\n      case \"append\":\n        out += `${record.field}:${record.payload.length}:${record.payload};`;\n        break;\n      case \"complete\":\n        out += `!${record.field};`;\n        break;\n      case \"object-complete\":\n        out += \"!;\";\n        break;\n      case \"object-abort\":\n        out += \"~;\";\n        break;\n    }\n  }\n  return out;\n}\n\n// ---- reference decoder ----------------------------------------------------------\n\n/**\n * The contract every implementation (including the future arena-backed\n * receiver) must satisfy:\n *\n *   push(fragment(encodeText(records))) + end()  ===  executeRecords(schema, records)\n */\nexport interface Decoder {\n  push(chunk: string): void;\n  end(): Event[];\n}\n\ntype ParserState = \"header\" | \"field-id\" | \"length\" | \"payload\" | \"payload-end\" | \"control\" | \"abort\";\n\nexport class ReferenceDecoder implements Decoder {\n  private readonly receiver: Receiver;\n  private state: ParserState = \"header\";\n  private fieldId = \"\";\n  private length = \"\";\n  private payload = \"\";\n  private remaining = 0;\n\n  constructor(schema: Schema, onEvent?: (event: Event) => void) {\n    this.receiver = new Receiver(schema, onEvent);\n  }\n\n  push(chunk: string): void {\n    for (let i = 0; i < chunk.length; i++) {\n      const c = chunk[i]!;\n      switch (this.state) {\n        case \"header\":\n          this.onHeader(c);\n          break;\n        case \"field-id\":\n          this.onFieldId(c);\n          break;\n        case \"length\":\n          this.onLength(c);\n          break;\n        case \"payload\":\n          this.onPayload(c);\n          break;\n        case \"payload-end\":\n          this.onPayloadEnd(c);\n          break;\n        case \"control\":\n          this.onControl(c);\n          break;\n        case \"abort\":\n          this.onAbort(c);\n          break;\n      }\n    }\n  }\n\n  end(): Event[] {\n    if (!this.receiver.isEnded) throw new Error(\"stream ended before object completion\");\n    return this.receiver.getEvents();\n  }\n\n  private onHeader(c: string): void {\n    if (isDigit(c)) {\n      this.reset();\n      this.fieldId = c;\n      this.state = \"field-id\";\n      return;\n    }\n    if (c === \"!\") {\n      this.reset();\n      this.state = \"control\";\n      return;\n    }\n    if (c === \"~\") {\n      this.state = \"abort\";\n      return;\n    }\n    throw new Error(`expected record start, got ${JSON.stringify(c)}`);\n  }\n\n  private onFieldId(c: string): void {\n    if (isDigit(c)) {\n      this.fieldId += c;\n      return;\n    }\n    if (c === \":\") {\n      this.state = \"length\";\n      return;\n    }\n    throw new Error(`expected ':' after field id, got ${JSON.stringify(c)}`);\n  }\n\n  private onLength(c: string): void {\n    if (isDigit(c)) {\n      this.length += c;\n      return;\n    }\n    if (c === \":\") {\n      if (this.length === \"\") throw new Error(\"empty payload length\");\n      this.remaining = Number(this.length);\n      this.payload = \"\";\n      this.state = this.remaining === 0 ? \"payload-end\" : \"payload\";\n      return;\n    }\n    throw new Error(`expected ':' after length, got ${JSON.stringify(c)}`);\n  }\n\n  private onPayload(c: string): void {\n    this.payload += c;\n    if (--this.remaining === 0) this.state = \"payload-end\";\n  }\n\n  private onPayloadEnd(c: string): void {\n    if (c !== \";\") throw new Error(`expected ';' after payload, got ${JSON.stringify(c)}`);\n    this.receiver.append(Number(this.fieldId), this.payload);\n    this.state = \"header\";\n  }\n\n  private onControl(c: string): void {\n    if (isDigit(c)) {\n      this.fieldId += c;\n      return;\n    }\n    if (c === \";\") {\n      if (this.fieldId === \"\") this.receiver.objectComplete();\n      else this.receiver.complete(Number(this.fieldId));\n      this.state = \"header\";\n      return;\n    }\n    throw new Error(`expected field id or ';' after '!', got ${JSON.stringify(c)}`);\n  }\n\n  private onAbort(c: string): void {\n    if (c !== \";\") throw new Error(`expected ';' after '~', got ${JSON.stringify(c)}`);\n    this.receiver.objectAbort();\n    this.state = \"header\";\n  }\n\n  private reset(): void {\n    this.fieldId = \"\";\n    this.length = \"\";\n    this.payload = \"\";\n    this.remaining = 0;\n  }\n}\n\nfunction isDigit(c: string): boolean {\n  return c >= \"0\" && c <= \"9\";\n}\n\n/** Decode a sequence of transport chunks into events. */\nexport function decode(chunks: string[], schema: Schema): Event[] {\n  const decoder = new ReferenceDecoder(schema);\n  for (const chunk of chunks) decoder.push(chunk);\n  return decoder.end();\n}\n\n// ---- test utilities: rng, fragmentation, generators ----------------------------\n\nexport type Rng = () => number;\n\nexport function mulberry32(seed: number): Rng {\n  let a = seed >>> 0;\n  return () => {\n    a = (a + 0x6d2b79f5) >>> 0;\n    let t = a;\n    t = Math.imul(t ^ (t >>> 15), t | 1);\n    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);\n    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;\n  };\n}\n\nexport function fragment(text: string, rng: Rng): string[] {\n  const cuts: number[] = [];\n  for (let i = 1; i < text.length; i++) {\n    if (rng() < 0.3) cuts.push(i);\n  }\n  const chunks: string[] = [];\n  let prev = 0;\n  for (const cut of cuts) {\n    chunks.push(text.slice(prev, cut));\n    prev = cut;\n  }\n  chunks.push(text.slice(prev));\n  return chunks;\n}\n\n/** Every single-cut fragmentation of a message. */\nexport function allSingleCuts(text: string): string[][] {\n  const out: string[][] = [];\n  for (let i = 1; i < text.length; i++) {\n    out.push([text.slice(0, i), text.slice(i)]);\n  }\n  return out;\n}\n\n/** Every composition into 1..n chunks \u2014 2^(n-1) cases. Only for small messages. */\nexport function allCompositions(text: string): string[][] {\n  const out: string[][] = [];\n  for (let mask = 0; mask < 1 << (text.length - 1); mask++) {\n    const chunks: string[] = [];\n    let prev = 0;\n    for (let i = 1; i < text.length; i++) {\n      if (mask & (1 << (i - 1))) {\n        chunks.push(text.slice(prev, i));\n        prev = i;\n      }\n    }\n    chunks.push(text.slice(prev));\n    out.push(chunks);\n  }\n  return out;\n}\n\n// ---- random valid stream generators ----------------------------------------------\n\nconst TYPES: FieldType[] = [\"string\", \"integer\", \"number\", \"boolean\"];\nconst ALPHABET = \"abZ09;:!~ \u00E9\uD83D\uDE00\"; // protocol punctuation inside payloads + astral chars\n\nexport function randomSchema(rng: Rng): Schema {\n  const count = 1 + Math.floor(rng() * 4);\n  const schema: Schema = [];\n  for (let i = 0; i < count; i++) {\n    const type = TYPES[Math.floor(rng() * TYPES.length)]!;\n    const isArray = rng() < 0.4;\n    schema.push({\n      path: [`f${i}`],\n      type,\n      ...(isArray ? { mode: \"array\" as const, maxItems: 1 + Math.floor(rng() * 4) } : {}),\n      ...(rng() < 0.8 ? { maxLength: 1 + Math.floor(rng() * 16) } : {}),\n    });\n  }\n  return schema;\n}\n\nfunction randomString(rng: Rng, cap: number): string {\n  let s = \"\";\n  while (s.length < cap && rng() < 0.85) {\n    s += ALPHABET[Math.floor(rng() * ALPHABET.length)]!;\n  }\n  return s;\n}\n\nfunction randomTyped(rng: Rng, type: FieldType, cap: number): string {\n  switch (type) {\n    case \"string\":\n      return rng() < 0.15 ? \"\" : randomString(rng, cap);\n    case \"integer\":\n      return String(Math.floor(rng() * 2000) - 1000);\n    case \"number\": {\n      const r = rng();\n      if (r < 0.4) return String(Math.floor(rng() * 2000) - 1000);\n      if (r < 0.7) return String(Math.round((rng() * 2000 - 1000) * 100) / 100);\n      return String((rng() * 2 - 1) * 1e10);\n    }\n    case \"boolean\":\n      return rng() < 0.5 ? \"0\" : \"1\";\n  }\n}\n\n/** A payload that satisfies the type and (when set) the length cap. */\nfunction payloadFor(rng: Rng, type: FieldType, cap: number | undefined): string {\n  const limit = cap ?? 12;\n  for (let i = 0; i < 100; i++) {\n    const p = randomTyped(rng, type, limit);\n    if (p.length <= limit) return p;\n  }\n  return type === \"string\" ? \"\" : \"0\";\n}\n\nfunction splitFragments(s: string, count: number): string[] {\n  if (s.length === 0) return [];\n  const chunks: string[] = [];\n  let prev = 0;\n  for (let i = 1; i < count; i++) {\n    const cut = Math.floor((i * s.length) / count);\n    chunks.push(s.slice(prev, cut));\n    prev = cut;\n  }\n  chunks.push(s.slice(prev));\n  return chunks.filter((c) => c.length > 0);\n}\n\n/** Records for one field: appends (one item each for arrays), maybe a completion. */\nexport function fieldRecords(rng: Rng, schema: Schema, field: number): StreamRecord[] {\n  const def = schema[field]!;\n  const records: StreamRecord[] = [];\n\n  if (def.mode === \"array\") {\n    const maxItems = def.maxItems as number;\n    const count = Math.floor(rng() * (maxItems + 1));\n    for (let i = 0; i < count; i++) {\n      records.push({ kind: \"append\", field, payload: payloadFor(rng, def.type, def.maxLength) });\n    }\n    if (rng() < 0.8) records.push({ kind: \"complete\", field });\n    return records;\n  }\n\n  // scalar: generate the final payload, then fragment it across appends\n  const total = payloadFor(rng, def.type, def.maxLength);\n  const fragments = splitFragments(total, 1 + Math.floor(rng() * 4));\n  for (const fragment of fragments) {\n    records.push({ kind: \"append\", field, payload: fragment });\n  }\n\n  const canCompleteEmpty = def.type === \"string\";\n  const hasContent = records.length > 0;\n  if (hasContent ? rng() < 0.85 : canCompleteEmpty && rng() < 0.5) {\n    records.push({ kind: \"complete\", field });\n  }\n  return records;\n}\n\n/** A valid record sequence for the schema, randomly scheduled. */\nexport function generateValidRecords(rng: Rng, schema: Schema): StreamRecord[] {\n  const queues = schema.map((_, field) => ({\n    field,\n    records: fieldRecords(rng, schema, field),\n    pos: 0,\n  }));\n  const out: StreamRecord[] = [];\n  let remaining = queues.reduce((n, q) => n + q.records.length, 0);\n\n  while (remaining > 0) {\n    let queue = queues[Math.floor(rng() * queues.length)]!;\n    while (queue.pos >= queue.records.length) {\n      queue = queues[(queue.field + 1) % queues.length]!;\n    }\n    out.push(queue.records[queue.pos]!);\n    queue.pos++;\n    remaining--;\n  }\n\n  out.push(rng() < 0.1 ? { kind: \"object-abort\" } : { kind: \"object-complete\" });\n  return out;\n}\n"],
+  "mappings": "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",
+  "names": ["INTEGER_RE", "NUMBER_RE", "parseIntegerPayload", "s", "n", "__name", "parseNumberPayload", "parseBooleanPayload", "parseTyped", "type", "field", "v", "Receiver", "schema", "onEvent", "payload", "def", "items", "maxItems", "current", "materialize", "event", "raw", "item", "executeRecords", "records", "receiver", "record", "materializeObject", "events", "object", "setPath", "path", "value", "target", "key", "encodeText", "out", "ReferenceDecoder", "chunk", "i", "c", "isDigit", "decode", "chunks", "decoder", "mulberry32", "seed", "a", "fragment", "text", "rng", "cuts", "prev", "cut", "allSingleCuts", "allCompositions", "mask", "TYPES", "ALPHABET", "randomSchema", "count", "isArray", "randomString", "cap", "randomTyped", "r", "payloadFor", "limit", "p", "splitFragments", "fieldRecords", "total", "fragments", "canCompleteEmpty", "generateValidRecords", "queues", "_", "remaining", "q", "queue"]
+}

package/dist/esm/transport/streamobject/stream-object/index.js

@@ -0,0 +1,2 @@
+import{StreamObject as t}from"./stream-object.js";export{t as StreamObject};
+//# sourceMappingURL=index.js.map

package/dist/esm/transport/streamobject/stream-object/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/transport/streamobject/stream-object/index.ts"],
+  "sourcesContent": ["export { StreamObject } from \"./stream-object\";\nexport type {\n  ErrorHandler,\n  FieldHandler,\n  ItemHandler,\n  ObjectDoneHandler,\n  StreamObjectOptions,\n} from \"./stream-object\";\n"],
+  "mappings": "AAAA,OAAS,gBAAAA,MAAoB",
+  "names": ["StreamObject"]
+}

package/dist/esm/transport/streamobject/stream-object/stream-object.js

@@ -0,0 +1,2 @@
+var n=Object.defineProperty;var r=(i,a)=>n(i,"name",{value:a,configurable:!0});import{FieldStream as c}from"../field-stream/field-stream.js";import{JsonToStreamObjectAdapter as l}from"../json-adapter/json-adapter.js";class h extends c{constructor(o,e,t={}){super(e,t);this.source=o}source;static{r(this,"StreamObject")}started=!1;async start(){if(this.started)throw new Error("StreamObject already started");this.started=!0;const o=new l(this.schema,{onFieldDone:r((e,t)=>this.emitField(e,t),"onFieldDone"),onItemDone:r((e,t,s)=>this.emitItem(e,t,s),"onItemDone"),onObjectDone:r(()=>this.emitObject(o.getEvents()),"onObjectDone")});try{for await(const e of this.source){if(this.cancelled)break;for(let t=0;t<e.length&&!this.cancelled;t++)o.push(e[t])}if(!this.cancelled&&!this.objectCompleted)throw new Error("stream ended before object completion")}catch(e){if(this.cancelled)return;this.fail(e)}}}export{h as StreamObject};
+//# sourceMappingURL=stream-object.js.map

package/dist/esm/transport/streamobject/stream-object/stream-object.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/transport/streamobject/stream-object/stream-object.ts"],
+  "sourcesContent": ["/**\n * StreamObject \u2014 consumes an AsyncIterable of text chunks through the\n * incremental JSON adapter and exposes the FieldStream completion API.\n *\n *   const stream = new StreamObject(source, schema);\n *   stream.when(\"summary\", (summary) => { ... });            // field completion\n *   stream.whenItem(\"searchQueries\", (query, i) => { ... }); // item completion\n *   stream.whenObjectDone((object) => { ... });              // whole object\n *   stream.onError((error) => { ... });                      // failures\n *   await stream.start();\n *\n * `when` means completion, not mutation: handlers never see chunks, JSON,\n * SSE, or the wire codec. Handlers are invoked synchronously at the\n * completion boundary and never block the source; async handlers run\n * concurrently and their rejections are routed to onError. `cancel()` stops\n * the source and invokes the optional onCancel hook (e.g. to abort the\n * producer's request).\n *\n * Errors: delivered to onError handlers when registered; otherwise start()\n * rejects with the error. Cancelling the stream is not an error.\n */\n\nimport { FieldStream, type FieldStreamOptions } from \"../field-stream/field-stream\";\nimport { JsonToStreamObjectAdapter } from \"../json-adapter/json-adapter\";\nimport type { Schema } from \"../reference/reference\";\n\nexport type {\n  ErrorHandler,\n  FieldHandler,\n  FieldStreamOptions,\n  ItemHandler,\n  ObjectDoneHandler,\n} from \"../field-stream/field-stream\";\n\nexport type StreamObjectOptions = FieldStreamOptions;\n\nexport class StreamObject extends FieldStream {\n  private started = false;\n\n  constructor(\n    private readonly source: AsyncIterable<string>,\n    schema: Schema,\n    options: StreamObjectOptions = {},\n  ) {\n    super(schema, options);\n  }\n\n  async start(): Promise<void> {\n    if (this.started) throw new Error(\"StreamObject already started\");\n    this.started = true;\n\n    const adapter = new JsonToStreamObjectAdapter(this.schema, {\n      onFieldDone: (field, value) => this.emitField(field, value),\n      onItemDone: (field, index, value) => this.emitItem(field, index, value),\n      onObjectDone: () => this.emitObject(adapter.getEvents()),\n    });\n\n    try {\n      for await (const chunk of this.source) {\n        if (this.cancelled) break;\n        for (let i = 0; i < chunk.length; i++) {\n          if (this.cancelled) break;\n          adapter.push(chunk[i]!);\n        }\n      }\n      if (!this.cancelled && !this.objectCompleted) {\n        throw new Error(\"stream ended before object completion\");\n      }\n    } catch (error) {\n      if (this.cancelled) return; // intended cancellation (e.g. producer aborted)\n      this.fail(error);\n    }\n  }\n}\n"],
+  "mappings": "+EAsBA,OAAS,eAAAA,MAA4C,+BACrD,OAAS,6BAAAC,MAAiC,+BAanC,MAAMC,UAAqBF,CAAY,CAG5C,YACmBG,EACjBC,EACAC,EAA+B,CAAC,EAChC,CACA,MAAMD,EAAQC,CAAO,EAJJ,YAAAF,CAKnB,CALmB,OAxCrB,MAoC8C,CAAAG,EAAA,qBACpC,QAAU,GAUlB,MAAM,OAAuB,CAC3B,GAAI,KAAK,QAAS,MAAM,IAAI,MAAM,8BAA8B,EAChE,KAAK,QAAU,GAEf,MAAMC,EAAU,IAAIN,EAA0B,KAAK,OAAQ,CACzD,YAAaK,EAAA,CAACE,EAAOC,IAAU,KAAK,UAAUD,EAAOC,CAAK,EAA7C,eACb,WAAYH,EAAA,CAACE,EAAOE,EAAOD,IAAU,KAAK,SAASD,EAAOE,EAAOD,CAAK,EAA1D,cACZ,aAAcH,EAAA,IAAM,KAAK,WAAWC,EAAQ,UAAU,CAAC,EAAzC,eAChB,CAAC,EAED,GAAI,CACF,gBAAiBI,KAAS,KAAK,OAAQ,CACrC,GAAI,KAAK,UAAW,MACpB,QAASC,EAAI,EAAGA,EAAID,EAAM,QACpB,MAAK,UADuBC,IAEhCL,EAAQ,KAAKI,EAAMC,CAAC,CAAE,CAE1B,CACA,GAAI,CAAC,KAAK,WAAa,CAAC,KAAK,gBAC3B,MAAM,IAAI,MAAM,uCAAuC,CAE3D,OAASC,EAAO,CACd,GAAI,KAAK,UAAW,OACpB,KAAK,KAAKA,CAAK,CACjB,CACF,CACF",
+  "names": ["FieldStream", "JsonToStreamObjectAdapter", "StreamObject", "source", "schema", "options", "__name", "adapter", "field", "value", "index", "chunk", "i", "error"]
+}

package/dist/types/agents/agent.d.ts

@@ -2,6 +2,8 @@ import { Tool } from "./tools/tools.js";
 import type { LLM, LLMMessage } from "../providers/llm/types.js";
 export interface AgentOptions {
     name: string;
+    /** Names a participant might use to address this agent. */
+    aliases?: string[];
     context?: string;
     tools?: Tool<never, unknown>[];
     /** LLM provider used by `run()`. Injected by `Pipeflow.agent()`. */
@@ -40,6 +42,7 @@ export interface AgentRunResult {
  */
 export declare class Agent {
     readonly name: string;
+    readonly aliases: string[];
     readonly context: string;
     private readonly toolRegistry;
     /** LLM provider used by `run()` and the orchestrator. */

package/dist/types/agents/tools/tools.d.ts

@@ -1,9 +1,30 @@
-export interface ToolOptions<TArgs, TResult> {
+import { z } from "zod";
+/**
+ * Zod schemas for a tool's arguments. `in` shapes what the model sends (and
+ * derives the LLM-facing JSON schema); `out` is what `execute` receives after
+ * validation. Keeping them separate means `in` stays plain JSON-schema-able
+ * while `out` may transform, normalize, or narrow.
+ */
+export interface ToolSchema<TOut, TIn> {
+    /** What the model sends — derives the LLM-facing JSON schema. */
+    in: z.ZodType<TIn>;
+    /** What `execute` receives, validated at run time. Defaults to `in`. */
+    out?: z.ZodType<TOut>;
+}
+export interface ToolOptions<TOut, TResult, TIn> {
     name: string;
     description: string;
-    /** JSON schema describing the arguments for the LLM. */
+    /**
+     * Zod schemas for the tool arguments — the single source of truth: `in`
+     * derives the LLM-facing JSON schema (`parameters`), and `out` (defaulting
+     * to `in`) validates the arguments at `execute()` time, so a model sending
+     * garbage surfaces a clear tool error instead of a crash inside the tool.
+     * Mutually exclusive with `parameters`.
+     */
+    schema?: ToolSchema<TOut, TIn>;
+    /** JSON schema describing the arguments for the LLM (no runtime validation). */
     parameters?: Record<string, unknown>;
-    execute: (args: TArgs) => TResult | Promise<TResult>;
+    execute: (args: TOut) => TResult | Promise<TResult>;
 }
 /**
  * A capability exposed by the application to an agent.
@@ -11,12 +32,13 @@ export interface ToolOptions<TArgs, TResult> {
  * Tools execute in the application's backend: Pipeflow never runs
  * application code directly.
  */
-export declare class Tool<TArgs = Record<string, unknown>, TResult = unknown> {
+export declare class Tool<TOut = Record<string, unknown>, TResult = unknown, TIn = TOut> {
     readonly name: string;
     readonly description: string;
     readonly parameters: Record<string, unknown> | undefined;
+    private readonly parse;
     private readonly executor;
-    constructor(options: ToolOptions<TArgs, TResult>);
+    constructor(options: ToolOptions<TOut, TResult, TIn>);
     /** Execute the tool. Sync throws and rejections both surface as rejections. */
-    execute(args: TArgs): Promise<TResult>;
+    execute(args: TIn): Promise<TResult>;
 }