@mostra/protocol 0.7.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/actions.d.ts CHANGED
@@ -139,6 +139,13 @@ export interface LiveState {
139
139
  }[];
140
140
  /** The producer's last failure, while the last good value stays (FAILURE_MODEL §6). */
141
141
  readonly error?: WireError;
142
+ /**
143
+ * `true` while the source has no value and no failure and the artifact's latest version has a
144
+ * producer whose first `load` is on its way: the page shows it loading, and verify waits for it.
145
+ * Absent for a key nothing produces (one only `mostra push` writes) and for a source that only
146
+ * streams, whose first value may never come (WP-14's Opus review).
147
+ */
148
+ readonly awaiting?: boolean;
142
149
  }
143
150
  /** One live update on the event stream: never stored as an event (D63, LL-04). */
144
151
  export interface LiveUpdate {
@@ -152,6 +159,11 @@ export interface LiveUpdate {
152
159
  readonly value?: Batches;
153
160
  /** What went wrong. */
154
161
  readonly error?: WireError;
162
+ /**
163
+ * `false` when a source read as {@link LiveState.awaiting} turned out to have no first `load`
164
+ * (its producer only streams): the page stops waiting for a first value.
165
+ */
166
+ readonly awaiting?: boolean;
155
167
  }
156
168
  /**
157
169
  * An ephemeral message on a page's event stream (SSE `event: run` or `event: live`, without an
@@ -1 +1 @@
1
- {"version":3,"file":"actions.d.ts","names":[],"sources":["../src/actions.ts"],"mappings":";;;;YAgBY,6BAA6B;;;;;qBAM5B,SAAS,EAAE,QAAQ;;iBASf,oBAAoB;;WAE1B;;;qBAIE,aAAa,EAAE,QAAQ;;qBAYvB;;qBAGA;;qBAGA;;qBAGA;;qBAGA;;;;;;;YAQD;;qBAGC,uBAAuB;;wBAUpB,iBAAiB,QAAQ;;;;;;;YAU7B;;iBAGK;;WAEN;;WAEA;;;qBAIE,aAAa,EAAE,QAAQ;;;;;iBAcnB;;WAEN;;WAEA;;WAEA;;WAEA,QAAQ;;WAER,SAAS;;WAET,WAAW;;WAEX;;WAEA,SAAS;;WAET,QAAQ;;WAER;;WAEA;;WAEA;;;;;WAKA;;WAEA;;;qBAIE,UAAU,EAAE,QAAQ;;;;;;iBA2BhB;;WAEN;;WAEA,QAAQ;;WAER,SAAS;;WAET,WAAW;;WAEX;;WAEA;;WAEA;;WAEA,SAAS;;WAET,QAAQ;;WAER;;;iBAIM;;WAEN;;WAEA;;WAEA;;WAEA,QAAQ;;;;;WAKR;aACE;aACA;aACA,OAAO;;;WAGT,QAAQ;;;iBAIF;;WAEN;;WAEA;;WAEA;;WAEA,QAAQ;;WAER,QAAQ;;;;;;;YAQP;WACG;WAAsB,KAAK;;WAC3B;WAAuB,MAAM;;;iBAG3B;;WAEN;;WAEA,MAAM;;;qBAIJ,aAAa,EAAE,QAAQ;;;;YAUxB;WACG,gBAAgB;;WAChB;aAAgB;;;WAChB;aAAgB;aAA2B,OAAO;;;;iBAGhD;;WAEN;;WAEA;;WAEA,MAAM;;WAEN;;WAEA;;;qBAIE,YAAY,EAAE,QAAQ;;;;;iBAiBlB;;WAEN;;WAEA;;WAEA;aAA4B;aAAuB;;;;;;;WAMnD;aACE;aACA;aACA;;;;qBAKA,kBAAkB,EAAE,QAAQ;;iBA6BxB;;WAEN;;;qBAIE,kBAAkB,EAAE,QAAQ;;qBAK5B,kBAAkB;;qBAGlB;;qBAGA;;qBAGA;;;;;iBAMI;;WAEN;;;;;WAKA;aACE;aACA;aACA;;;;qBAKA,aAAa,EAAE,QAAQ;;qBAoBvB,qBAAqB;;qBAGrB"}
1
+ {"version":3,"file":"actions.d.ts","names":[],"sources":["../src/actions.ts"],"mappings":";;;;YAgBY,6BAA6B;;;;;qBAM5B,SAAS,EAAE,QAAQ;;iBASf,oBAAoB;;WAE1B;;;qBAIE,aAAa,EAAE,QAAQ;;qBAYvB;;qBAGA;;qBAGA;;qBAGA;;qBAGA;;;;;;;YAQD;;qBAGC,uBAAuB;;wBAUpB,iBAAiB,QAAQ;;;;;;;YAU7B;;iBAGK;;WAEN;;WAEA;;;qBAIE,aAAa,EAAE,QAAQ;;;;;iBAcnB;;WAEN;;WAEA;;WAEA;;WAEA,QAAQ;;WAER,SAAS;;WAET,WAAW;;WAEX;;WAEA,SAAS;;WAET,QAAQ;;WAER;;WAEA;;WAEA;;;;;WAKA;;WAEA;;;qBAIE,UAAU,EAAE,QAAQ;;;;;;iBA2BhB;;WAEN;;WAEA,QAAQ;;WAER,SAAS;;WAET,WAAW;;WAEX;;WAEA;;WAEA;;WAEA,SAAS;;WAET,QAAQ;;WAER;;;iBAIM;;WAEN;;WAEA;;WAEA;;WAEA,QAAQ;;;;;WAKR;aACE;aACA;aACA,OAAO;;;WAGT,QAAQ;;;;;;;WAOR;;;iBAIM;;WAEN;;WAEA;;WAEA;;WAEA,QAAQ;;WAER,QAAQ;;;;;WAKR;;;;;;;YAQC;WACG;WAAsB,KAAK;;WAC3B;WAAuB,MAAM;;;iBAG3B;;WAEN;;WAEA,MAAM;;;qBAIJ,aAAa,EAAE,QAAQ;;;;YAUxB;WACG,gBAAgB;;WAChB;aAAgB;;;WAChB;aAAgB;aAA2B,OAAO;;;;iBAGhD;;WAEN;;WAEA;;WAEA,MAAM;;WAEN;;WAEA;;;qBAIE,YAAY,EAAE,QAAQ;;;;;iBAiBlB;;WAEN;;WAEA;;WAEA;aAA4B;aAAuB;;;;;;;WAMnD;aACE;aACA;aACA;;;;qBAKA,kBAAkB,EAAE,QAAQ;;iBA6BxB;;WAEN;;;qBAIE,kBAAkB,EAAE,QAAQ;;qBAK5B,kBAAkB;;qBAGlB;;qBAGA;;qBAGA;;;;;iBAMI;;WAEN;;;;;WAKA;aACE;aACA;aACA;;;;qBAKA,aAAa,EAAE,QAAQ;;qBAoBvB,qBAAqB;;qBAGrB"}
@@ -1 +1 @@
1
- {"version":3,"file":"actions.js","names":[],"sources":["../src/actions.ts"],"sourcesContent":["/**\n * Actions, live data and secrets (INTERFACES §2.4, §4, §6; D24, D44, D54, D56): the shapes the\n * browser protocol, the host protocol and the worker channel share. Server-function arguments and\n * results travel as the serializer's batches (`Batches`).\n *\n * ```ts\n * const run: RunState = await post(\"runs\", { viewId, fnId: \"actions.ts#sendReply\", args, clientKey });\n * if (run.status === \"succeeded\") show(await deserializeAll(run.batches));\n * ```\n */\nimport * as z from \"zod\";\nimport { ViewId } from \"./ids.ts\";\nimport type { Frame, WireError } from \"./serializer.ts\";\nimport { wireRegistry } from \"./wire-registry.ts\";\n\n/** A value written by the serializer: its batches, in order (`serializeAll`). */\nexport type Batches = readonly (readonly Frame[])[];\n\n/**\n * The Zod schema of the `Batches` type: a list of batches, each a list of frames. The frames\n * themselves are checked by the reader (`ValueReader`), which refuses anything malformed.\n */\nexport const Batches: z.ZodType<Batches> = z\n .array(z.array(z.record(z.string(), z.unknown())).readonly())\n .readonly()\n .register(wireRegistry, {\n id: \"Batches\",\n description: \"A serialized server-function value: its batches of frames, in order.\",\n }) as unknown as z.ZodType<Batches>;\n\n/** An error as runs, calls and live sources report it. */\nexport interface ActionError extends WireError {\n /** The stack of the thrown error, kept in the run log and never sent to a page. */\n readonly stack?: string;\n}\n\n/** The Zod schema of the `ActionError` type. */\nexport const ActionError: z.ZodType<ActionError> = z\n .object({\n message: z.string(),\n code: z.string().exactOptional(),\n stack: z.string().exactOptional(),\n })\n .register(wireRegistry, {\n id: \"ActionError\",\n description: \"An error from server code: its message and diagnostic code.\",\n });\n\n/** The largest serialized arguments a call or run takes, in characters of JSON. */\nexport const ACTION_ARGS_MAX: number = 16 * 1024 * 1024;\n\n/** The largest serialized result a run keeps, in characters of JSON (larger fails the run). */\nexport const ACTION_RESULT_MAX: number = 16 * 1024 * 1024;\n\n/** The cap of a run's log, in UTF-16 code units of its lines (D47's 1 MB). */\nexport const RUN_LOG_MAX: number = 1024 * 1024;\n\n/** The line a capped log ends with. */\nexport const RUN_LOG_TRUNCATED = \"[log truncated at 1 MB]\";\n\n/** The longest run key, in characters. */\nexport const RUN_KEY_MAX = 256;\n\n/**\n * A run's state (D24, ARCHITECTURE §7). `queued`: recorded, not yet started in a worker.\n * `running`: started. `waiting` is reserved for a remote server's run that waits for its owner's\n * instance (WP-28, D117); a page that doesn't know it treats it like `queued`. The others are\n * final.\n */\nexport type RunStatus = \"queued\" | \"running\" | \"waiting\" | \"succeeded\" | \"failed\" | \"cancelled\";\n\n/** Every run status. */\nexport const RUN_STATUSES: readonly RunStatus[] = [\n \"queued\",\n \"running\",\n \"waiting\",\n \"succeeded\",\n \"failed\",\n \"cancelled\",\n];\n\n/** Whether a run in `status` has ended. */\nexport function isFinalRunStatus(status: RunStatus): boolean {\n return status === \"succeeded\" || status === \"failed\" || status === \"cancelled\";\n}\n\n/**\n * Why a run ended the way it did, beside its status: `interrupted` (its worker or the instance\n * stopped while it ran, D24), `threw` (the action threw), `unserializable` (its result is outside\n * the type set), `too-large`, `parked` (its artifact's worker keeps crashing), `cancelled` (by a\n * viewer), `unknown-function`. Later releases add reasons.\n */\nexport type RunReason = string;\n\n/** A run's progress, as the action last reported it. */\nexport interface RunProgress {\n /** From 0 to 1. */\n readonly fraction?: number;\n /** One short line for people. */\n readonly message?: string;\n}\n\n/** The Zod schema of the `RunProgress` type. */\nexport const RunProgress: z.ZodType<RunProgress> = z\n .object({\n fraction: z.number().min(0).max(1).exactOptional(),\n message: z.string().max(1000).exactOptional(),\n })\n .register(wireRegistry, {\n id: \"RunProgress\",\n description: \"A run's progress: fraction and message.\",\n });\n\n/**\n * One action run as a page reads it (D54): its state, progress, log and the result written so far.\n * A result that is an async iterable grows item by item while the run is `running`.\n */\nexport interface RunState {\n /** The run's `run_` ID. */\n readonly runId: string;\n /** The server function it runs: `<module path>#<export>`. */\n readonly fnId: string;\n /** The idempotency key it was started with, if any. */\n readonly key?: string;\n /** The run's state. */\n readonly status: RunStatus;\n /** Why it ended, for `failed` and `cancelled`. */\n readonly reason?: RunReason;\n /** Its latest progress. */\n readonly progress?: RunProgress;\n /** The log lines, capped at 1 MB with a marker line. */\n readonly log: readonly string[];\n /** The result's batches so far. */\n readonly batches: Batches;\n /** For `failed`: what went wrong, without the stack. */\n readonly error?: WireError;\n /** When it was recorded. */\n readonly startedAt: string;\n /** When it ended. */\n readonly finishedAt?: string;\n /** Whether this request joined a run that already existed (a key or a retried `clientKey`). */\n readonly joined?: boolean;\n /**\n * The index of the first line in `log`, when the request said which lines the page holds\n * (`RunAttachRequest.held`); absent: 0, the whole log.\n */\n readonly logFrom?: number;\n /** The index of the first batch in `batches`, as `logFrom`; absent: 0. */\n readonly batchFrom?: number;\n}\n\n/** The Zod schema of the `RunState` type. */\nexport const RunState: z.ZodType<RunState> = z\n .object({\n runId: z.string(),\n fnId: z.string(),\n key: z.string().exactOptional(),\n status: z.enum(RUN_STATUSES as [RunStatus, ...RunStatus[]]),\n reason: z.string().exactOptional(),\n progress: RunProgress.exactOptional(),\n log: z.array(z.string()).readonly(),\n batches: Batches,\n error: z.object({ message: z.string(), code: z.string().exactOptional() }).exactOptional(),\n startedAt: z.string(),\n finishedAt: z.string().exactOptional(),\n joined: z.boolean().exactOptional(),\n logFrom: z.number().int().nonnegative().exactOptional(),\n batchFrom: z.number().int().nonnegative().exactOptional(),\n })\n .register(wireRegistry, {\n id: \"RunState\",\n description: \"An action run: status, progress, log and the result written so far.\",\n });\n\n/**\n * What changed in a run since a page last heard: a lossy notification on the event stream. Lines\n * start at `logFrom` and batches at `batchFrom`; a page that holds fewer reads the run again\n * (`runs/attach`).\n */\nexport interface RunDelta {\n /** The run's `run_` ID. */\n readonly runId: string;\n /** The run's state. */\n readonly status: RunStatus;\n /** Why it ended so, for `failed` and `cancelled`. */\n readonly reason?: RunReason;\n /** Its latest progress. */\n readonly progress?: RunProgress;\n /** The index of the first line in `log`. */\n readonly logFrom: number;\n /** Log lines, starting at `logFrom`. */\n readonly log: readonly string[];\n /** The index of the first batch in `batches`. */\n readonly batchFrom: number;\n /** Result batches, starting at `batchFrom`. */\n readonly batches: Batches;\n /** What went wrong. */\n readonly error?: WireError;\n /** When it ended. */\n readonly finishedAt?: string;\n}\n\n/** A live source's value as a page reads it (D56). */\nexport interface LiveState {\n /** The idempotency key it was started with, if any. */\n readonly key: string;\n /** The value's revision, a decimal string that only grows; absent before any value. */\n readonly revision?: string;\n /** When the value was produced. */\n readonly at?: string;\n /** The latest value, serialized. */\n readonly value?: Batches;\n /**\n * Append mode (`useLive(key, { mode: \"append\" })`): the values kept in the source's ring, oldest\n * first, at most the window the page asked for.\n */\n readonly ring?: readonly {\n readonly revision: string;\n readonly at: string;\n readonly value: Batches;\n }[];\n /** The producer's last failure, while the last good value stays (FAILURE_MODEL §6). */\n readonly error?: WireError;\n}\n\n/** One live update on the event stream: never stored as an event (D63, LL-04). */\nexport interface LiveUpdate {\n /** The live source's key. */\n readonly key: string;\n /** The value's revision. */\n readonly revision?: string;\n /** When the value was produced. */\n readonly at?: string;\n /** The value, serialized. */\n readonly value?: Batches;\n /** What went wrong. */\n readonly error?: WireError;\n}\n\n/**\n * An ephemeral message on a page's event stream (SSE `event: run` or `event: live`, without an\n * `id`, so a reconnect's cursor is untouched) or in a poll's `ephemeral`: lossy, coalesced, and\n * never stored as an event.\n */\nexport type EphemeralMessage =\n | { readonly kind: \"run\"; readonly run: RunDelta }\n | { readonly kind: \"live\"; readonly live: LiveUpdate };\n\n/** `POST …/call/{fnId}`: a plain server-function call, no durable record (D54). */\nexport interface CallRequest {\n /** The view the page was opened as (D104). */\n readonly viewId: string;\n /** The arguments, serialized as one array value. */\n readonly args: Batches;\n}\n\n/** The Zod schema of the `CallRequest` type. */\nexport const CallRequest: z.ZodType<CallRequest> = z\n .object({ viewId: ViewId.schema, args: Batches })\n .register(wireRegistry, {\n id: \"CallRequest\",\n description: \"A plain server-function call: the view and the serialized arguments.\",\n });\n\n/**\n * One line of a plain call's answer (`application/x-ndjson`): a batch of the result, then the end.\n */\nexport type CallLine =\n | { readonly batch: readonly Frame[] }\n | { readonly end: { readonly status: \"succeeded\" } }\n | { readonly end: { readonly status: \"failed\"; readonly error: WireError } };\n\n/** `POST …/runs`: start a durable action run, or join one (D54, AC-02, AC-03). */\nexport interface RunRequest {\n /** The view the page was opened as (D104). */\n readonly viewId: string;\n /** `<module path>#<export>`. */\n readonly fnId: string;\n /** The arguments, serialized as one array value. */\n readonly args: Batches;\n /** The author's idempotency key: one run per artifact, function and key, ever. */\n readonly key?: string;\n /** A fresh ID per invocation, so a retried request joins the run it already started. */\n readonly clientKey: string;\n}\n\n/** The Zod schema of the `RunRequest` type. */\nexport const RunRequest: z.ZodType<RunRequest> = z\n .object({\n viewId: ViewId.schema,\n fnId: z.string().min(3).max(1024),\n args: Batches,\n key: z.string().min(1).max(RUN_KEY_MAX).exactOptional(),\n clientKey: z.string().min(8).max(64),\n })\n .register(wireRegistry, {\n id: \"RunRequest\",\n description: \"Start or join an action run: the function, its arguments and keys.\",\n });\n\n/**\n * `POST …/runs/attach`: read runs and hear their changes on the event stream for the next minute\n * (re-attach after a reload, AC-02). By ID, or by function and key.\n */\nexport interface RunAttachRequest {\n /** The view the page was opened as (D104). */\n readonly viewId: string;\n /** Runs by ID. */\n readonly runIds?: readonly string[];\n /** Runs by function and key. */\n readonly keyed?: readonly { readonly fnId: string; readonly key: string }[];\n /**\n * What the page already holds of runs it names by ID: so many log lines and batches. Each such\n * run's answer starts there (`RunState.logFrom`, `batchFrom`), so a page renewing its interest\n * doesn't read the whole run again (Opus review 14).\n */\n readonly held?: readonly {\n readonly runId: string;\n readonly log: number;\n readonly batches: number;\n }[];\n}\n\n/** The Zod schema of the `RunAttachRequest` type. */\nexport const RunAttachRequest: z.ZodType<RunAttachRequest> = z\n .object({\n viewId: ViewId.schema,\n runIds: z.array(z.string().max(64)).max(100).readonly().exactOptional(),\n keyed: z\n .array(\n z.object({ fnId: z.string().min(3).max(1024), key: z.string().min(1).max(RUN_KEY_MAX) }),\n )\n .max(100)\n .readonly()\n .exactOptional(),\n held: z\n .array(\n z.object({\n runId: z.string().max(64),\n log: z.number().int().nonnegative(),\n batches: z.number().int().nonnegative(),\n }),\n )\n .max(100)\n .readonly()\n .exactOptional(),\n })\n .register(wireRegistry, {\n id: \"RunAttachRequest\",\n description: \"Runs a page reads and follows: by ID, or by function and key.\",\n });\n\n/** `POST …/runs/{id}/cancel`. */\nexport interface RunCancelRequest {\n /** The view the page was opened as (D104). */\n readonly viewId: string;\n}\n\n/** The Zod schema of the `RunCancelRequest` type. */\nexport const RunCancelRequest: z.ZodType<RunCancelRequest> = z\n .object({ viewId: ViewId.schema })\n .register(wireRegistry, { id: \"RunCancelRequest\", description: \"Cancel a run, from a view.\" });\n\n/** The keys of live sources: like JavaScript export names, which is what `live.ts` declares. */\nexport const LIVE_KEY_PATTERN: RegExp = /^[A-Za-z_$][A-Za-z0-9_$]{0,127}$/;\n\n/** The largest live value, in characters of serialized JSON (DATA_MODEL §5's 4 MiB). */\nexport const LIVE_VALUE_MAX: number = 4 * 1024 * 1024;\n\n/** The ring size of a pushed source in append mode that no `defineLive` sized. */\nexport const LIVE_RING_DEFAULT = 1024;\n\n/** The largest ring a source may keep. */\nexport const LIVE_RING_MAX = 100_000;\n\n/**\n * `POST …/live`: read live sources and keep their producers running for this view for the next\n * minute (D56, LL-04); a page asks again while it shows them.\n */\nexport interface LiveRequest {\n /** The view the page was opened as (D104). */\n readonly viewId: string;\n /**\n * The sources, each with its append window; `refresh` asks the source's producer to load again\n * now (`useLive`'s `refresh()`).\n */\n readonly keys: readonly {\n readonly key: string;\n readonly window?: number;\n readonly refresh?: boolean;\n }[];\n}\n\n/** The Zod schema of the `LiveRequest` type. */\nexport const LiveRequest: z.ZodType<LiveRequest> = z\n .object({\n viewId: ViewId.schema,\n keys: z\n .array(\n z.object({\n key: z.string().regex(LIVE_KEY_PATTERN),\n window: z.int().min(1).max(LIVE_RING_MAX).exactOptional(),\n refresh: z.boolean().exactOptional(),\n }),\n )\n .max(256)\n .readonly(),\n })\n .register(wireRegistry, {\n id: \"LiveRequest\",\n description: \"Live sources a page reads and keeps running: keys and append windows.\",\n });\n\n/** Secret names: letters, digits, `_`, `.` and `-`, starting with a letter or `_` (D44). */\nexport const SECRET_NAME_PATTERN: RegExp = /^[A-Za-z_][A-Za-z0-9_.-]{0,127}$/;\n\n/** The largest secret value, in UTF-8 bytes. */\nexport const SECRET_VALUE_MAX: number = 64 * 1024;\n"],"mappings":"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"}
1
+ {"version":3,"file":"actions.js","names":[],"sources":["../src/actions.ts"],"sourcesContent":["/**\n * Actions, live data and secrets (INTERFACES §2.4, §4, §6; D24, D44, D54, D56): the shapes the\n * browser protocol, the host protocol and the worker channel share. Server-function arguments and\n * results travel as the serializer's batches (`Batches`).\n *\n * ```ts\n * const run: RunState = await post(\"runs\", { viewId, fnId: \"actions.ts#sendReply\", args, clientKey });\n * if (run.status === \"succeeded\") show(await deserializeAll(run.batches));\n * ```\n */\nimport * as z from \"zod\";\nimport { ViewId } from \"./ids.ts\";\nimport type { Frame, WireError } from \"./serializer.ts\";\nimport { wireRegistry } from \"./wire-registry.ts\";\n\n/** A value written by the serializer: its batches, in order (`serializeAll`). */\nexport type Batches = readonly (readonly Frame[])[];\n\n/**\n * The Zod schema of the `Batches` type: a list of batches, each a list of frames. The frames\n * themselves are checked by the reader (`ValueReader`), which refuses anything malformed.\n */\nexport const Batches: z.ZodType<Batches> = z\n .array(z.array(z.record(z.string(), z.unknown())).readonly())\n .readonly()\n .register(wireRegistry, {\n id: \"Batches\",\n description: \"A serialized server-function value: its batches of frames, in order.\",\n }) as unknown as z.ZodType<Batches>;\n\n/** An error as runs, calls and live sources report it. */\nexport interface ActionError extends WireError {\n /** The stack of the thrown error, kept in the run log and never sent to a page. */\n readonly stack?: string;\n}\n\n/** The Zod schema of the `ActionError` type. */\nexport const ActionError: z.ZodType<ActionError> = z\n .object({\n message: z.string(),\n code: z.string().exactOptional(),\n stack: z.string().exactOptional(),\n })\n .register(wireRegistry, {\n id: \"ActionError\",\n description: \"An error from server code: its message and diagnostic code.\",\n });\n\n/** The largest serialized arguments a call or run takes, in characters of JSON. */\nexport const ACTION_ARGS_MAX: number = 16 * 1024 * 1024;\n\n/** The largest serialized result a run keeps, in characters of JSON (larger fails the run). */\nexport const ACTION_RESULT_MAX: number = 16 * 1024 * 1024;\n\n/** The cap of a run's log, in UTF-16 code units of its lines (D47's 1 MB). */\nexport const RUN_LOG_MAX: number = 1024 * 1024;\n\n/** The line a capped log ends with. */\nexport const RUN_LOG_TRUNCATED = \"[log truncated at 1 MB]\";\n\n/** The longest run key, in characters. */\nexport const RUN_KEY_MAX = 256;\n\n/**\n * A run's state (D24, ARCHITECTURE §7). `queued`: recorded, not yet started in a worker.\n * `running`: started. `waiting` is reserved for a remote server's run that waits for its owner's\n * instance (WP-28, D117); a page that doesn't know it treats it like `queued`. The others are\n * final.\n */\nexport type RunStatus = \"queued\" | \"running\" | \"waiting\" | \"succeeded\" | \"failed\" | \"cancelled\";\n\n/** Every run status. */\nexport const RUN_STATUSES: readonly RunStatus[] = [\n \"queued\",\n \"running\",\n \"waiting\",\n \"succeeded\",\n \"failed\",\n \"cancelled\",\n];\n\n/** Whether a run in `status` has ended. */\nexport function isFinalRunStatus(status: RunStatus): boolean {\n return status === \"succeeded\" || status === \"failed\" || status === \"cancelled\";\n}\n\n/**\n * Why a run ended the way it did, beside its status: `interrupted` (its worker or the instance\n * stopped while it ran, D24), `threw` (the action threw), `unserializable` (its result is outside\n * the type set), `too-large`, `parked` (its artifact's worker keeps crashing), `cancelled` (by a\n * viewer), `unknown-function`. Later releases add reasons.\n */\nexport type RunReason = string;\n\n/** A run's progress, as the action last reported it. */\nexport interface RunProgress {\n /** From 0 to 1. */\n readonly fraction?: number;\n /** One short line for people. */\n readonly message?: string;\n}\n\n/** The Zod schema of the `RunProgress` type. */\nexport const RunProgress: z.ZodType<RunProgress> = z\n .object({\n fraction: z.number().min(0).max(1).exactOptional(),\n message: z.string().max(1000).exactOptional(),\n })\n .register(wireRegistry, {\n id: \"RunProgress\",\n description: \"A run's progress: fraction and message.\",\n });\n\n/**\n * One action run as a page reads it (D54): its state, progress, log and the result written so far.\n * A result that is an async iterable grows item by item while the run is `running`.\n */\nexport interface RunState {\n /** The run's `run_` ID. */\n readonly runId: string;\n /** The server function it runs: `<module path>#<export>`. */\n readonly fnId: string;\n /** The idempotency key it was started with, if any. */\n readonly key?: string;\n /** The run's state. */\n readonly status: RunStatus;\n /** Why it ended, for `failed` and `cancelled`. */\n readonly reason?: RunReason;\n /** Its latest progress. */\n readonly progress?: RunProgress;\n /** The log lines, capped at 1 MB with a marker line. */\n readonly log: readonly string[];\n /** The result's batches so far. */\n readonly batches: Batches;\n /** For `failed`: what went wrong, without the stack. */\n readonly error?: WireError;\n /** When it was recorded. */\n readonly startedAt: string;\n /** When it ended. */\n readonly finishedAt?: string;\n /** Whether this request joined a run that already existed (a key or a retried `clientKey`). */\n readonly joined?: boolean;\n /**\n * The index of the first line in `log`, when the request said which lines the page holds\n * (`RunAttachRequest.held`); absent: 0, the whole log.\n */\n readonly logFrom?: number;\n /** The index of the first batch in `batches`, as `logFrom`; absent: 0. */\n readonly batchFrom?: number;\n}\n\n/** The Zod schema of the `RunState` type. */\nexport const RunState: z.ZodType<RunState> = z\n .object({\n runId: z.string(),\n fnId: z.string(),\n key: z.string().exactOptional(),\n status: z.enum(RUN_STATUSES as [RunStatus, ...RunStatus[]]),\n reason: z.string().exactOptional(),\n progress: RunProgress.exactOptional(),\n log: z.array(z.string()).readonly(),\n batches: Batches,\n error: z.object({ message: z.string(), code: z.string().exactOptional() }).exactOptional(),\n startedAt: z.string(),\n finishedAt: z.string().exactOptional(),\n joined: z.boolean().exactOptional(),\n logFrom: z.number().int().nonnegative().exactOptional(),\n batchFrom: z.number().int().nonnegative().exactOptional(),\n })\n .register(wireRegistry, {\n id: \"RunState\",\n description: \"An action run: status, progress, log and the result written so far.\",\n });\n\n/**\n * What changed in a run since a page last heard: a lossy notification on the event stream. Lines\n * start at `logFrom` and batches at `batchFrom`; a page that holds fewer reads the run again\n * (`runs/attach`).\n */\nexport interface RunDelta {\n /** The run's `run_` ID. */\n readonly runId: string;\n /** The run's state. */\n readonly status: RunStatus;\n /** Why it ended so, for `failed` and `cancelled`. */\n readonly reason?: RunReason;\n /** Its latest progress. */\n readonly progress?: RunProgress;\n /** The index of the first line in `log`. */\n readonly logFrom: number;\n /** Log lines, starting at `logFrom`. */\n readonly log: readonly string[];\n /** The index of the first batch in `batches`. */\n readonly batchFrom: number;\n /** Result batches, starting at `batchFrom`. */\n readonly batches: Batches;\n /** What went wrong. */\n readonly error?: WireError;\n /** When it ended. */\n readonly finishedAt?: string;\n}\n\n/** A live source's value as a page reads it (D56). */\nexport interface LiveState {\n /** The idempotency key it was started with, if any. */\n readonly key: string;\n /** The value's revision, a decimal string that only grows; absent before any value. */\n readonly revision?: string;\n /** When the value was produced. */\n readonly at?: string;\n /** The latest value, serialized. */\n readonly value?: Batches;\n /**\n * Append mode (`useLive(key, { mode: \"append\" })`): the values kept in the source's ring, oldest\n * first, at most the window the page asked for.\n */\n readonly ring?: readonly {\n readonly revision: string;\n readonly at: string;\n readonly value: Batches;\n }[];\n /** The producer's last failure, while the last good value stays (FAILURE_MODEL §6). */\n readonly error?: WireError;\n /**\n * `true` while the source has no value and no failure and the artifact's latest version has a\n * producer whose first `load` is on its way: the page shows it loading, and verify waits for it.\n * Absent for a key nothing produces (one only `mostra push` writes) and for a source that only\n * streams, whose first value may never come (WP-14's Opus review).\n */\n readonly awaiting?: boolean;\n}\n\n/** One live update on the event stream: never stored as an event (D63, LL-04). */\nexport interface LiveUpdate {\n /** The live source's key. */\n readonly key: string;\n /** The value's revision. */\n readonly revision?: string;\n /** When the value was produced. */\n readonly at?: string;\n /** The value, serialized. */\n readonly value?: Batches;\n /** What went wrong. */\n readonly error?: WireError;\n /**\n * `false` when a source read as {@link LiveState.awaiting} turned out to have no first `load`\n * (its producer only streams): the page stops waiting for a first value.\n */\n readonly awaiting?: boolean;\n}\n\n/**\n * An ephemeral message on a page's event stream (SSE `event: run` or `event: live`, without an\n * `id`, so a reconnect's cursor is untouched) or in a poll's `ephemeral`: lossy, coalesced, and\n * never stored as an event.\n */\nexport type EphemeralMessage =\n | { readonly kind: \"run\"; readonly run: RunDelta }\n | { readonly kind: \"live\"; readonly live: LiveUpdate };\n\n/** `POST …/call/{fnId}`: a plain server-function call, no durable record (D54). */\nexport interface CallRequest {\n /** The view the page was opened as (D104). */\n readonly viewId: string;\n /** The arguments, serialized as one array value. */\n readonly args: Batches;\n}\n\n/** The Zod schema of the `CallRequest` type. */\nexport const CallRequest: z.ZodType<CallRequest> = z\n .object({ viewId: ViewId.schema, args: Batches })\n .register(wireRegistry, {\n id: \"CallRequest\",\n description: \"A plain server-function call: the view and the serialized arguments.\",\n });\n\n/**\n * One line of a plain call's answer (`application/x-ndjson`): a batch of the result, then the end.\n */\nexport type CallLine =\n | { readonly batch: readonly Frame[] }\n | { readonly end: { readonly status: \"succeeded\" } }\n | { readonly end: { readonly status: \"failed\"; readonly error: WireError } };\n\n/** `POST …/runs`: start a durable action run, or join one (D54, AC-02, AC-03). */\nexport interface RunRequest {\n /** The view the page was opened as (D104). */\n readonly viewId: string;\n /** `<module path>#<export>`. */\n readonly fnId: string;\n /** The arguments, serialized as one array value. */\n readonly args: Batches;\n /** The author's idempotency key: one run per artifact, function and key, ever. */\n readonly key?: string;\n /** A fresh ID per invocation, so a retried request joins the run it already started. */\n readonly clientKey: string;\n}\n\n/** The Zod schema of the `RunRequest` type. */\nexport const RunRequest: z.ZodType<RunRequest> = z\n .object({\n viewId: ViewId.schema,\n fnId: z.string().min(3).max(1024),\n args: Batches,\n key: z.string().min(1).max(RUN_KEY_MAX).exactOptional(),\n clientKey: z.string().min(8).max(64),\n })\n .register(wireRegistry, {\n id: \"RunRequest\",\n description: \"Start or join an action run: the function, its arguments and keys.\",\n });\n\n/**\n * `POST …/runs/attach`: read runs and hear their changes on the event stream for the next minute\n * (re-attach after a reload, AC-02). By ID, or by function and key.\n */\nexport interface RunAttachRequest {\n /** The view the page was opened as (D104). */\n readonly viewId: string;\n /** Runs by ID. */\n readonly runIds?: readonly string[];\n /** Runs by function and key. */\n readonly keyed?: readonly { readonly fnId: string; readonly key: string }[];\n /**\n * What the page already holds of runs it names by ID: so many log lines and batches. Each such\n * run's answer starts there (`RunState.logFrom`, `batchFrom`), so a page renewing its interest\n * doesn't read the whole run again (Opus review 14).\n */\n readonly held?: readonly {\n readonly runId: string;\n readonly log: number;\n readonly batches: number;\n }[];\n}\n\n/** The Zod schema of the `RunAttachRequest` type. */\nexport const RunAttachRequest: z.ZodType<RunAttachRequest> = z\n .object({\n viewId: ViewId.schema,\n runIds: z.array(z.string().max(64)).max(100).readonly().exactOptional(),\n keyed: z\n .array(\n z.object({ fnId: z.string().min(3).max(1024), key: z.string().min(1).max(RUN_KEY_MAX) }),\n )\n .max(100)\n .readonly()\n .exactOptional(),\n held: z\n .array(\n z.object({\n runId: z.string().max(64),\n log: z.number().int().nonnegative(),\n batches: z.number().int().nonnegative(),\n }),\n )\n .max(100)\n .readonly()\n .exactOptional(),\n })\n .register(wireRegistry, {\n id: \"RunAttachRequest\",\n description: \"Runs a page reads and follows: by ID, or by function and key.\",\n });\n\n/** `POST …/runs/{id}/cancel`. */\nexport interface RunCancelRequest {\n /** The view the page was opened as (D104). */\n readonly viewId: string;\n}\n\n/** The Zod schema of the `RunCancelRequest` type. */\nexport const RunCancelRequest: z.ZodType<RunCancelRequest> = z\n .object({ viewId: ViewId.schema })\n .register(wireRegistry, { id: \"RunCancelRequest\", description: \"Cancel a run, from a view.\" });\n\n/** The keys of live sources: like JavaScript export names, which is what `live.ts` declares. */\nexport const LIVE_KEY_PATTERN: RegExp = /^[A-Za-z_$][A-Za-z0-9_$]{0,127}$/;\n\n/** The largest live value, in characters of serialized JSON (DATA_MODEL §5's 4 MiB). */\nexport const LIVE_VALUE_MAX: number = 4 * 1024 * 1024;\n\n/** The ring size of a pushed source in append mode that no `defineLive` sized. */\nexport const LIVE_RING_DEFAULT = 1024;\n\n/** The largest ring a source may keep. */\nexport const LIVE_RING_MAX = 100_000;\n\n/**\n * `POST …/live`: read live sources and keep their producers running for this view for the next\n * minute (D56, LL-04); a page asks again while it shows them.\n */\nexport interface LiveRequest {\n /** The view the page was opened as (D104). */\n readonly viewId: string;\n /**\n * The sources, each with its append window; `refresh` asks the source's producer to load again\n * now (`useLive`'s `refresh()`).\n */\n readonly keys: readonly {\n readonly key: string;\n readonly window?: number;\n readonly refresh?: boolean;\n }[];\n}\n\n/** The Zod schema of the `LiveRequest` type. */\nexport const LiveRequest: z.ZodType<LiveRequest> = z\n .object({\n viewId: ViewId.schema,\n keys: z\n .array(\n z.object({\n key: z.string().regex(LIVE_KEY_PATTERN),\n window: z.int().min(1).max(LIVE_RING_MAX).exactOptional(),\n refresh: z.boolean().exactOptional(),\n }),\n )\n .max(256)\n .readonly(),\n })\n .register(wireRegistry, {\n id: \"LiveRequest\",\n description: \"Live sources a page reads and keeps running: keys and append windows.\",\n });\n\n/** Secret names: letters, digits, `_`, `.` and `-`, starting with a letter or `_` (D44). */\nexport const SECRET_NAME_PATTERN: RegExp = /^[A-Za-z_][A-Za-z0-9_.-]{0,127}$/;\n\n/** The largest secret value, in UTF-8 bytes. */\nexport const SECRET_VALUE_MAX: number = 64 * 1024;\n"],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mostra/protocol",
3
- "version": "0.7.0",
3
+ "version": "0.8.0",
4
4
  "description": "Mostra's shared protocol vocabulary: IDs, dated revisions and diagnostics, with Zod schemas and generated JSON Schema.",
5
5
  "license": "Apache-2.0",
6
6
  "author": "The Mostra Authors",
package/src/actions.ts CHANGED
@@ -221,6 +221,13 @@ export interface LiveState {
221
221
  }[];
222
222
  /** The producer's last failure, while the last good value stays (FAILURE_MODEL §6). */
223
223
  readonly error?: WireError;
224
+ /**
225
+ * `true` while the source has no value and no failure and the artifact's latest version has a
226
+ * producer whose first `load` is on its way: the page shows it loading, and verify waits for it.
227
+ * Absent for a key nothing produces (one only `mostra push` writes) and for a source that only
228
+ * streams, whose first value may never come (WP-14's Opus review).
229
+ */
230
+ readonly awaiting?: boolean;
224
231
  }
225
232
 
226
233
  /** One live update on the event stream: never stored as an event (D63, LL-04). */
@@ -235,6 +242,11 @@ export interface LiveUpdate {
235
242
  readonly value?: Batches;
236
243
  /** What went wrong. */
237
244
  readonly error?: WireError;
245
+ /**
246
+ * `false` when a source read as {@link LiveState.awaiting} turned out to have no first `load`
247
+ * (its producer only streams): the page stops waiting for a first value.
248
+ */
249
+ readonly awaiting?: boolean;
238
250
  }
239
251
 
240
252
  /**