@mostra/server 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,26 @@
-# Temporary Holding Version
+# @mostra/server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+What a Mostra artifact's server code imports: who a call is for, progress and log lines for the
+page, named secrets, signals and host events, the artifact's shared state, cancellation, and live
+sources. It works inside the artifact's worker, which Mostra starts for every version with
+`"use server"` modules or a `live.ts`; it needs no installation in the artifact.
+
+```ts
+"use server";
+import { abortSignal, progress, secret, signal } from "@mostra/server";
+
+export async function sendReply(messageId: string, body: string) {
+  progress({ message: "Sending…" });
+  const response = await fetch("https://mail.example/api/send", {
+    method: "POST",
+    headers: { authorization: `Bearer ${secret("MAIL_TOKEN")}`, "idempotency-key": messageId },
+    body: JSON.stringify({ messageId, body }),
+    signal: abortSignal,
+  });
+  if (!response.ok) throw new Error(`Mail API returned ${response.status}`);
+  signal("reply-sent", { messageId });
+  return { sent: true };
+}
+```
+
+Part of [Mostra](https://github.com/mostra-dev/mostra), the agent artifact runtime. Apache-2.0.

package/dist/host.d.ts

@@ -0,0 +1,63 @@
+import { a as parseDuration, i as liveSourceOptions, n as LiveSourceOptions } from "./live-BLUwPFXE.js";
+import { FieldOp, MutationResult } from "@mostra/protocol";
+//#region src/context.d.ts
+/** One call as server code sees it. */
+interface ServerCallContext {
+  /** `call`: a plain call, no durable record. `run`: an action run (D54). */
+  readonly kind: "call" | "run";
+  /** The channel's ID of the call: progress, logs and signals name it. */
+  readonly callId: string;
+  /** The action run, for `kind: "run"`. */
+  readonly runId?: string;
+  /** Who the call is for. */
+  readonly viewer?: {
+    readonly id: string;
+    readonly name?: string;
+  };
+  /** True only during `verify`'s smoke test (D55). */
+  readonly dryRun: boolean;
+  /** Aborted when the run is cancelled or the caller goes away (AC-04). */
+  readonly signal: AbortSignal;
+}
+/** The artifact's shared state as the supervisor answers it. */
+interface StateSnapshot {
+  /** The state document's revision. */
+  readonly revision: string;
+  /** Its fields by ID. */
+  readonly fields: Readonly<Record<string, {
+    readonly value?: unknown;
+    readonly deleted?: boolean;
+  }>>;
+}
+/** What `@mostra/server` needs from the process it runs in: the worker implements it. */
+interface ServerHost {
+  /** The secret's value; throws an error with `code: "MOSTRA_SECRET_MISSING"` when there is none. */
+  secret(name: string): string;
+  /** Reports a call's progress. */
+  progress(callId: string, progress: {
+    fraction?: number;
+    message?: string;
+  }): void;
+  /** Adds a line to a call's log, or to the worker's own outside calls. */
+  log(callId: string | undefined, line: string): void;
+  /** Raises a signal (already checked). */
+  signal(callId: string | undefined, name: string, payload: unknown): void;
+  /** Appends a host event (already checked). */
+  emit(callId: string | undefined, type: string, payload: unknown): void;
+  /** Reads the artifact's shared state. */
+  stateGet(ids: readonly string[] | undefined): Promise<StateSnapshot>;
+  /** Writes the artifact's shared state as the agent. */
+  statePatch(callId: string | undefined, ops: readonly FieldOp[], options: {
+    readonly mutationId?: string;
+    readonly baseRevision?: string;
+  }): Promise<MutationResult>;
+}
+/** Installs the process's {@link ServerHost}; the worker calls it once, before loading code. */
+export declare function installServerHost(host: ServerHost): void;
+/** The current call, or `undefined` outside any (module scope, a timer started at load). */
+export declare function currentCall(): ServerCallContext | undefined;
+/** Runs `fn` as `context`: everything it awaits sees the same call. */
+export declare function runWithContext<T>(context: ServerCallContext, fn: () => T): T;
+//#endregion
+export { type LiveSourceOptions, type ServerCallContext, type ServerHost, type StateSnapshot, liveSourceOptions, parseDuration };
+//# sourceMappingURL=host.d.ts.map

package/dist/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","names":[],"sources":["../src/context.ts"],"mappings":";;;;UAUiB;;WAEN;;WAEA;;WAEA;;WAEA;aAAoB;aAAqB;;;WAEzC;;WAEA,QAAQ;;;UAIF;;WAEN;;WAEA,QAAQ,SACf;aAA0B;aAA0B;;;;UAKvC;;EAEf,OAAO;;EAEP,SAAS,gBAAgB;IAAY;IAAmB;;;EAExD,IAAI,4BAA4B;;EAEhC,OAAO,4BAA4B,cAAc;;EAEjD,KAAK,4BAA4B,cAAc;;EAE/C,SAAS,qCAAqC,QAAQ;;EAEtD,WACE,4BACA,cAAc,WACd;aAAoB;aAA8B;MACjD,QAAQ;;;wBAOG,kBAAkB,MAAM;;wBAkBxB,eAAe;;wBAKf,eAAe,GAAG,SAAS,mBAAmB,UAAU,IAAI"}

package/dist/host.js

@@ -0,0 +1,2 @@
+import { a as installServerHost, i as currentCall, n as liveSourceOptions, o as runWithContext, r as parseDuration } from "./live-2VU8jmOO.js";
+export { currentCall, installServerHost, liveSourceOptions, parseDuration, runWithContext };

package/dist/index.d.ts

@@ -0,0 +1,95 @@
+import { n as LiveSourceOptions, r as defineLive, t as LiveSource } from "./live-BLUwPFXE.js";
+//#region src/index.d.ts
+/** Any JSON value. */
+export type Json = string | number | boolean | null | Json[] | {
+  [key: string]: Json;
+};
+/** An error with a Mostra diagnostic code, as `@mostra/server` throws them. */
+export declare class MostraServerError extends Error {
+  /** The diagnostic code, such as `MOSTRA_SECRET_MISSING`. */
+  readonly code: string;
+  constructor(code: string, message: string);
+}
+/**
+ * Whether this call is `verify`'s smoke test (D55). An action that checks it opts into the smoke
+ * test, and should then return without real effects; one that never calls it is skipped there.
+ */
+export declare function dryRun(): boolean;
+/** Reports the run's progress to every page following it (ephemeral, never an event). */
+export declare function progress(p: {
+  fraction?: number;
+  message?: string;
+}): void;
+/**
+ * Adds a line to the run's log (kept with the run, capped at 1 MB, D47); outside a run, to the
+ * worker's own log. Secrets are redacted from it.
+ */
+export declare function log(line: string): void;
+/**
+ * A secret's value, by name (D44): from the host's `secrets` port, the artifact's own secrets or
+ * the home's shared ones. Never put the value in a result, a log or a signal.
+ *
+ * @throws MostraServerError `MOSTRA_SECRET_MISSING` when no store holds it.
+ */
+export declare function secret(name: string): string;
+/**
+ * Raises a named signal for the host's attention (IN-09): one durable `signal.raised` event with
+ * `source: "action"` and this run as its causation. Mostra wakes no one by itself (D10).
+ *
+ * @throws MostraServerError `MOSTRA_SUBMIT_SIGNAL_INVALID` for a bad name or a payload over 64 KiB.
+ */
+export declare function signal(name: string, payload?: Json): void;
+/**
+ * Appends a host event, `host.<name>`, to the event log (AC-05), which hosts filter for.
+ *
+ * @throws MostraServerError `MOSTRA_ACTION_EVENT_INVALID` for a bad type or a payload over 64 KiB.
+ */
+export declare function emit(type: `host.${string}`, payload?: Json): void;
+/** Who the call is for; `undefined` in live producers and outside calls. */
+export declare function viewer(): {
+  id: string;
+  name?: string;
+} | undefined;
+/**
+ * The current call's cancellation (AC-04): aborted when a page cancels the run or the caller goes
+ * away. Pass it to `fetch` and other cancellable work. Outside a call it never aborts. Listeners
+ * added to it run in the call that added them, so they read `abortSignal.reason` of that call.
+ */
+export declare const abortSignal: AbortSignal;
+/** Options of a state write. */
+export interface StateWriteOptions {
+  /** The change's ID: a retry with the same ID and contents returns the recorded result. */
+  readonly mutationId?: string;
+  /** The revision you read: a field changed after it is a conflict and keeps its value. */
+  readonly baseRevision?: string;
+}
+/** The artifact's shared state, as server code reads and writes it. */
+export interface ServerState {
+  /** A field's value, or `undefined` when it isn't set. */
+  get<T>(id: string): Promise<T | undefined>;
+  /**
+   * Sets one field.
+   *
+   * @throws MostraServerError `MOSTRA_FIELD_CONFLICT` when the field changed after `baseRevision`.
+   */
+  set<T>(id: string, value: T, options?: StateWriteOptions): Promise<{
+    revision: string;
+  }>;
+  /** Sets and deletes several fields under one revision; conflicting ones are listed. */
+  patch(ops: readonly {
+    id: string;
+    value?: Json;
+    delete?: true;
+  }[], options?: StateWriteOptions): Promise<{
+    revision: string;
+    conflicts: string[];
+  }>;
+}
+/**
+ * The artifact's shared state (D63): the artifact-scoped fields every viewer sees, written through
+ * the same compare-and-set as viewers' edits, as the agent. Each write appends `state.changed`.
+ */
+export declare const state: ServerState;
+//#endregion
+export { type LiveSource, type LiveSourceOptions, defineLive };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;YAmCY,0CAA0C;GAA0B,cAAA;;;qBAGnE,0BAA0B;;WAE5B;EACT,YAAY,cAAc;;;;;;wBA0BZ;;wBAKA,SAAS;EAAK;EAAmB;;;;;;wBAcjC,IAAI;;;;;;;wBAUJ,OAAO;;;;;;;wBAUP,OAAO,cAAc,UAAU;;;;;;wBAgB/B,KAAK,wBAAwB,UAAU;;wBAavC;EAAY;EAAY;;;;;;;qBAyC3B,aAAa;;iBA8BT;;WAEN;;WAEA;;;iBAIM;;EAEf,IAAI,GAAG,aAAa,QAAQ;;;;;;EAM5B,IAAI,GAAG,YAAY,OAAO,GAAG,UAAU,oBAAoB;IAAU;;;EAErE,MACE;IAAgB;IAAY,QAAQ;IAAM;OAC1C,UAAU,oBACT;IAAU;IAAkB;;;;;;;qBAOpB,OAAO"}

package/dist/index.js

@@ -0,0 +1,195 @@
+import { i as currentCall, s as serverHost, t as defineLive } from "./live-2VU8jmOO.js";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { SIGNAL_NAME_PATTERN, canonicalJson } from "@mostra/protocol";
+//#region src/index.ts
+/**
+* `@mostra/server`: what server code imports (INTERFACES §2.4). Inside `"use server"` functions and
+* live sources, it tells who the call is for, reports progress and log lines to the page, reads
+* secrets, raises signals and host events, and reads and writes the artifact's shared state.
+* Server code runs with full capability (D05, AC-01): it can read files, start processes and call
+* any network service; this package only adds what Mostra knows.
+*
+* ```ts
+* "use server";
+* import { abortSignal, dryRun, progress, secret, signal } from "@mostra/server";
+*
+* export async function sendReply(messageId: string, body: string) {
+*   if (dryRun()) return { messageId, sent: false };
+*   progress({ message: "Sending…" });
+*   const response = await fetch("https://mail.example/api/send", {
+*     method: "POST",
+*     headers: { authorization: `Bearer ${secret("MAIL_TOKEN")}`, "idempotency-key": messageId },
+*     body: JSON.stringify({ messageId, body }),
+*     signal: abortSignal,
+*   });
+*   if (!response.ok) throw new Error(`Mail API returned ${response.status}`);
+*   signal("reply-sent", { messageId });
+*   return { messageId, sent: true };
+* }
+* ```
+*
+* @packageDocumentation
+*/
+/** An error with a Mostra diagnostic code, as `@mostra/server` throws them. */
+var MostraServerError = class extends Error {
+	/** The diagnostic code, such as `MOSTRA_SECRET_MISSING`. */
+	code;
+	constructor(code, message) {
+		super(message);
+		this.name = "MostraServerError";
+		this.code = code;
+	}
+};
+const PAYLOAD_MAX = 65536;
+function checkPayload(code, what, payload) {
+	if (payload === void 0) return;
+	let text;
+	try {
+		text = canonicalJson(payload);
+	} catch {
+		throw new MostraServerError(code, `The payload of ${what} isn't JSON.`);
+	}
+	if (Buffer.byteLength(text, "utf8") > PAYLOAD_MAX) throw new MostraServerError(code, `The payload of ${what} is larger than 64 KiB of JSON.`);
+}
+/**
+* Whether this call is `verify`'s smoke test (D55). An action that checks it opts into the smoke
+* test, and should then return without real effects; one that never calls it is skipped there.
+*/
+function dryRun() {
+	return currentCall()?.dryRun ?? false;
+}
+/** Reports the run's progress to every page following it (ephemeral, never an event). */
+function progress(p) {
+	const call = currentCall();
+	if (!call) return;
+	const fraction = p.fraction === void 0 ? void 0 : Math.min(1, Math.max(0, p.fraction));
+	serverHost().progress(call.callId, {
+		...fraction === void 0 || Number.isNaN(fraction) ? {} : { fraction },
+		...p.message === void 0 ? {} : { message: String(p.message).slice(0, 1e3) }
+	});
+}
+/**
+* Adds a line to the run's log (kept with the run, capped at 1 MB, D47); outside a run, to the
+* worker's own log. Secrets are redacted from it.
+*/
+function log(line) {
+	serverHost().log(currentCall()?.callId, String(line));
+}
+/**
+* A secret's value, by name (D44): from the host's `secrets` port, the artifact's own secrets or
+* the home's shared ones. Never put the value in a result, a log or a signal.
+*
+* @throws MostraServerError `MOSTRA_SECRET_MISSING` when no store holds it.
+*/
+function secret(name) {
+	return serverHost().secret(name);
+}
+/**
+* Raises a named signal for the host's attention (IN-09): one durable `signal.raised` event with
+* `source: "action"` and this run as its causation. Mostra wakes no one by itself (D10).
+*
+* @throws MostraServerError `MOSTRA_SUBMIT_SIGNAL_INVALID` for a bad name or a payload over 64 KiB.
+*/
+function signal(name, payload) {
+	if (typeof name !== "string" || !SIGNAL_NAME_PATTERN.test(name) || name === "submit") throw new MostraServerError("MOSTRA_SUBMIT_SIGNAL_INVALID", `${JSON.stringify(name).slice(0, 80)} isn't a signal name: 1 to 64 letters, digits, ".", "_" and "-", and not "submit".`);
+	checkPayload("MOSTRA_SUBMIT_SIGNAL_INVALID", `the signal ${name}`, payload);
+	serverHost().signal(currentCall()?.callId, name, payload);
+}
+/**
+* Appends a host event, `host.<name>`, to the event log (AC-05), which hosts filter for.
+*
+* @throws MostraServerError `MOSTRA_ACTION_EVENT_INVALID` for a bad type or a payload over 64 KiB.
+*/
+function emit(type, payload) {
+	const name = typeof type === "string" && type.startsWith("host.") ? type.slice(5) : "";
+	if (!SIGNAL_NAME_PATTERN.test(name)) throw new MostraServerError("MOSTRA_ACTION_EVENT_INVALID", `${JSON.stringify(type).slice(0, 80)} isn't a host event type: "host." and 1 to 64 letters, digits, ".", "_" and "-".`);
+	checkPayload("MOSTRA_ACTION_EVENT_INVALID", `the event ${type}`, payload);
+	serverHost().emit(currentCall()?.callId, type, payload);
+}
+/** Who the call is for; `undefined` in live producers and outside calls. */
+function viewer() {
+	const who = currentCall()?.viewer;
+	return who ? { ...who } : void 0;
+}
+const idle = new AbortController().signal;
+/**
+* The bound copies of listeners, per signal: each call has its own signal, so a listener added in
+* two calls (a module-level callback, say) gets a copy bound to each call's context, and removing
+* it from one call's signal finds that call's copy.
+*/
+const boundListeners = /* @__PURE__ */ new WeakMap();
+/** A listener that runs in the call it was added in, as `await`ed code does. */
+function bindListener(target, listener) {
+	if (typeof listener !== "function" && (typeof listener !== "object" || listener === null)) return listener;
+	let perSignal = boundListeners.get(target);
+	if (!perSignal) {
+		perSignal = /* @__PURE__ */ new WeakMap();
+		boundListeners.set(target, perSignal);
+	}
+	let bound = perSignal.get(listener);
+	if (!bound) {
+		const handle = typeof listener === "function" ? listener : (event) => listener.handleEvent(event);
+		bound = AsyncLocalStorage.bind(handle);
+		perSignal.set(listener, bound);
+	}
+	return bound;
+}
+/**
+* The current call's cancellation (AC-04): aborted when a page cancels the run or the caller goes
+* away. Pass it to `fetch` and other cancellable work. Outside a call it never aborts. Listeners
+* added to it run in the call that added them, so they read `abortSignal.reason` of that call.
+*/
+const abortSignal = new Proxy(idle, {
+	get(_target, property) {
+		const target = currentCall()?.signal ?? idle;
+		if (property === "addEventListener" || property === "removeEventListener") {
+			const method = target[property].bind(target);
+			return (type, listener, options) => method(type, bindListener(target, listener), options);
+		}
+		const value = Reflect.get(target, property, target);
+		return typeof value === "function" ? value.bind(target) : value;
+	},
+	set(_target, property, value) {
+		const target = currentCall()?.signal ?? idle;
+		return Reflect.set(target, property, property === "onabort" ? bindListener(target, value) : value, target);
+	},
+	has(_target, property) {
+		return Reflect.has(currentCall()?.signal ?? idle, property);
+	}
+});
+/**
+* The artifact's shared state (D63): the artifact-scoped fields every viewer sees, written through
+* the same compare-and-set as viewers' edits, as the agent. Each write appends `state.changed`.
+*/
+const state = {
+	async get(id) {
+		const field = (await serverHost().stateGet([id])).fields[id];
+		return field && !field.deleted ? field.value : void 0;
+	},
+	async set(id, value, options = {}) {
+		const result = await serverHost().statePatch(currentCall()?.callId, [{
+			id,
+			value
+		}], options);
+		if (result.conflicts.length > 0) throw new MostraServerError("MOSTRA_FIELD_CONFLICT", `The state field ${id} changed after revision ${options.baseRevision ?? "?"}; read it again and decide.`);
+		return { revision: result.revision };
+	},
+	async patch(ops, options = {}) {
+		const fieldOps = ops.map((op) => op.delete ? {
+			id: op.id,
+			delete: true
+		} : {
+			id: op.id,
+			value: op.value
+		});
+		const result = await serverHost().statePatch(currentCall()?.callId, fieldOps, options);
+		return {
+			revision: result.revision,
+			conflicts: result.conflicts.map((conflict) => conflict.id)
+		};
+	}
+};
+//#endregion
+export { MostraServerError, abortSignal, defineLive, dryRun, emit, log, progress, secret, signal, state, viewer };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * `@mostra/server`: what server code imports (INTERFACES §2.4). Inside `\"use server\"` functions and\n * live sources, it tells who the call is for, reports progress and log lines to the page, reads\n * secrets, raises signals and host events, and reads and writes the artifact's shared state.\n * Server code runs with full capability (D05, AC-01): it can read files, start processes and call\n * any network service; this package only adds what Mostra knows.\n *\n * ```ts\n * \"use server\";\n * import { abortSignal, dryRun, progress, secret, signal } from \"@mostra/server\";\n *\n * export async function sendReply(messageId: string, body: string) {\n *   if (dryRun()) return { messageId, sent: false };\n *   progress({ message: \"Sending…\" });\n *   const response = await fetch(\"https://mail.example/api/send\", {\n *     method: \"POST\",\n *     headers: { authorization: `Bearer ${secret(\"MAIL_TOKEN\")}`, \"idempotency-key\": messageId },\n *     body: JSON.stringify({ messageId, body }),\n *     signal: abortSignal,\n *   });\n *   if (!response.ok) throw new Error(`Mail API returned ${response.status}`);\n *   signal(\"reply-sent\", { messageId });\n *   return { messageId, sent: true };\n * }\n * ```\n *\n * @packageDocumentation\n */\nimport { AsyncLocalStorage } from \"node:async_hooks\";\nimport { canonicalJson, type FieldOp, SIGNAL_NAME_PATTERN } from \"@mostra/protocol\";\nimport { currentCall, serverHost } from \"./context.ts\";\n\nexport { defineLive, type LiveSource, type LiveSourceOptions } from \"./live.ts\";\n\n/** Any JSON value. */\nexport type Json = string | number | boolean | null | Json[] | { [key: string]: Json };\n\n/** An error with a Mostra diagnostic code, as `@mostra/server` throws them. */\nexport class MostraServerError extends Error {\n  /** The diagnostic code, such as `MOSTRA_SECRET_MISSING`. */\n  readonly code: string;\n  constructor(code: string, message: string) {\n    super(message);\n    this.name = \"MostraServerError\";\n    this.code = code;\n  }\n}\n\nconst PAYLOAD_MAX = 64 * 1024;\n\nfunction checkPayload(code: string, what: string, payload: unknown): void {\n  if (payload === undefined) return;\n  let text: string;\n  try {\n    text = canonicalJson(payload);\n  } catch {\n    throw new MostraServerError(code, `The payload of ${what} isn't JSON.`);\n  }\n  if (Buffer.byteLength(text, \"utf8\") > PAYLOAD_MAX) {\n    throw new MostraServerError(code, `The payload of ${what} is larger than 64 KiB of JSON.`);\n  }\n}\n\n/**\n * Whether this call is `verify`'s smoke test (D55). An action that checks it opts into the smoke\n * test, and should then return without real effects; one that never calls it is skipped there.\n */\nexport function dryRun(): boolean {\n  return currentCall()?.dryRun ?? false;\n}\n\n/** Reports the run's progress to every page following it (ephemeral, never an event). */\nexport function progress(p: { fraction?: number; message?: string }): void {\n  const call = currentCall();\n  if (!call) return;\n  const fraction = p.fraction === undefined ? undefined : Math.min(1, Math.max(0, p.fraction));\n  serverHost().progress(call.callId, {\n    ...(fraction === undefined || Number.isNaN(fraction) ? {} : { fraction }),\n    ...(p.message === undefined ? {} : { message: String(p.message).slice(0, 1000) }),\n  });\n}\n\n/**\n * Adds a line to the run's log (kept with the run, capped at 1 MB, D47); outside a run, to the\n * worker's own log. Secrets are redacted from it.\n */\nexport function log(line: string): void {\n  serverHost().log(currentCall()?.callId, String(line));\n}\n\n/**\n * A secret's value, by name (D44): from the host's `secrets` port, the artifact's own secrets or\n * the home's shared ones. Never put the value in a result, a log or a signal.\n *\n * @throws MostraServerError `MOSTRA_SECRET_MISSING` when no store holds it.\n */\nexport function secret(name: string): string {\n  return serverHost().secret(name);\n}\n\n/**\n * Raises a named signal for the host's attention (IN-09): one durable `signal.raised` event with\n * `source: \"action\"` and this run as its causation. Mostra wakes no one by itself (D10).\n *\n * @throws MostraServerError `MOSTRA_SUBMIT_SIGNAL_INVALID` for a bad name or a payload over 64 KiB.\n */\nexport function signal(name: string, payload?: Json): void {\n  if (typeof name !== \"string\" || !SIGNAL_NAME_PATTERN.test(name) || name === \"submit\") {\n    throw new MostraServerError(\n      \"MOSTRA_SUBMIT_SIGNAL_INVALID\",\n      `${JSON.stringify(name).slice(0, 80)} isn't a signal name: 1 to 64 letters, digits, \".\", \"_\" and \"-\", and not \"submit\".`,\n    );\n  }\n  checkPayload(\"MOSTRA_SUBMIT_SIGNAL_INVALID\", `the signal ${name}`, payload);\n  serverHost().signal(currentCall()?.callId, name, payload);\n}\n\n/**\n * Appends a host event, `host.<name>`, to the event log (AC-05), which hosts filter for.\n *\n * @throws MostraServerError `MOSTRA_ACTION_EVENT_INVALID` for a bad type or a payload over 64 KiB.\n */\nexport function emit(type: `host.${string}`, payload?: Json): void {\n  const name = typeof type === \"string\" && type.startsWith(\"host.\") ? type.slice(5) : \"\";\n  if (!SIGNAL_NAME_PATTERN.test(name)) {\n    throw new MostraServerError(\n      \"MOSTRA_ACTION_EVENT_INVALID\",\n      `${JSON.stringify(type).slice(0, 80)} isn't a host event type: \"host.\" and 1 to 64 letters, digits, \".\", \"_\" and \"-\".`,\n    );\n  }\n  checkPayload(\"MOSTRA_ACTION_EVENT_INVALID\", `the event ${type}`, payload);\n  serverHost().emit(currentCall()?.callId, type, payload);\n}\n\n/** Who the call is for; `undefined` in live producers and outside calls. */\nexport function viewer(): { id: string; name?: string } | undefined {\n  const who = currentCall()?.viewer;\n  return who ? { ...who } : undefined;\n}\n\nconst idle = new AbortController().signal;\n\n/**\n * The bound copies of listeners, per signal: each call has its own signal, so a listener added in\n * two calls (a module-level callback, say) gets a copy bound to each call's context, and removing\n * it from one call's signal finds that call's copy.\n */\nconst boundListeners = new WeakMap<AbortSignal, WeakMap<object, (event: Event) => void>>();\n\n/** A listener that runs in the call it was added in, as `await`ed code does. */\nfunction bindListener(target: AbortSignal, listener: unknown): unknown {\n  if (typeof listener !== \"function\" && (typeof listener !== \"object\" || listener === null)) {\n    return listener;\n  }\n  let perSignal = boundListeners.get(target);\n  if (!perSignal) {\n    perSignal = new WeakMap();\n    boundListeners.set(target, perSignal);\n  }\n  let bound = perSignal.get(listener);\n  if (!bound) {\n    const handle =\n      typeof listener === \"function\"\n        ? (listener as (event: Event) => void)\n        : (event: Event) => (listener as { handleEvent(event: Event): void }).handleEvent(event);\n    bound = AsyncLocalStorage.bind(handle);\n    perSignal.set(listener, bound);\n  }\n  return bound;\n}\n\n/**\n * The current call's cancellation (AC-04): aborted when a page cancels the run or the caller goes\n * away. Pass it to `fetch` and other cancellable work. Outside a call it never aborts. Listeners\n * added to it run in the call that added them, so they read `abortSignal.reason` of that call.\n */\nexport const abortSignal: AbortSignal = new Proxy(idle, {\n  get(_target, property) {\n    const target = currentCall()?.signal ?? idle;\n    if (property === \"addEventListener\" || property === \"removeEventListener\") {\n      const method = target[property].bind(target) as (\n        type: string,\n        listener: unknown,\n        options?: unknown,\n      ) => void;\n      return (type: string, listener: unknown, options?: unknown) =>\n        method(type, bindListener(target, listener), options);\n    }\n    const value: unknown = Reflect.get(target, property, target);\n    return typeof value === \"function\" ? value.bind(target) : value;\n  },\n  set(_target, property, value) {\n    const target = currentCall()?.signal ?? idle;\n    return Reflect.set(\n      target,\n      property,\n      property === \"onabort\" ? bindListener(target, value) : value,\n      target,\n    );\n  },\n  has(_target, property) {\n    return Reflect.has(currentCall()?.signal ?? idle, property);\n  },\n});\n\n/** Options of a state write. */\nexport interface StateWriteOptions {\n  /** The change's ID: a retry with the same ID and contents returns the recorded result. */\n  readonly mutationId?: string;\n  /** The revision you read: a field changed after it is a conflict and keeps its value. */\n  readonly baseRevision?: string;\n}\n\n/** The artifact's shared state, as server code reads and writes it. */\nexport interface ServerState {\n  /** A field's value, or `undefined` when it isn't set. */\n  get<T>(id: string): Promise<T | undefined>;\n  /**\n   * Sets one field.\n   *\n   * @throws MostraServerError `MOSTRA_FIELD_CONFLICT` when the field changed after `baseRevision`.\n   */\n  set<T>(id: string, value: T, options?: StateWriteOptions): Promise<{ revision: string }>;\n  /** Sets and deletes several fields under one revision; conflicting ones are listed. */\n  patch(\n    ops: readonly { id: string; value?: Json; delete?: true }[],\n    options?: StateWriteOptions,\n  ): Promise<{ revision: string; conflicts: string[] }>;\n}\n\n/**\n * The artifact's shared state (D63): the artifact-scoped fields every viewer sees, written through\n * the same compare-and-set as viewers' edits, as the agent. Each write appends `state.changed`.\n */\nexport const state: ServerState = {\n  async get<T>(id: string): Promise<T | undefined> {\n    const snapshot = await serverHost().stateGet([id]);\n    const field = snapshot.fields[id];\n    return field && !field.deleted ? (field.value as T) : undefined;\n  },\n  async set<T>(id: string, value: T, options: StateWriteOptions = {}) {\n    const result = await serverHost().statePatch(\n      currentCall()?.callId,\n      [{ id, value } as FieldOp],\n      options,\n    );\n    if (result.conflicts.length > 0) {\n      throw new MostraServerError(\n        \"MOSTRA_FIELD_CONFLICT\",\n        `The state field ${id} changed after revision ${options.baseRevision ?? \"?\"}; read it again and decide.`,\n      );\n    }\n    return { revision: result.revision };\n  },\n  async patch(ops, options: StateWriteOptions = {}) {\n    const fieldOps = ops.map((op) =>\n      op.delete\n        ? ({ id: op.id, delete: true } as FieldOp)\n        : ({ id: op.id, value: op.value } as FieldOp),\n    );\n    const result = await serverHost().statePatch(currentCall()?.callId, fieldOps, options);\n    return {\n      revision: result.revision,\n      conflicts: result.conflicts.map((conflict) => conflict.id),\n    };\n  },\n};\n"],"mappings":"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"}

package/dist/live-2VU8jmOO.js

@@ -0,0 +1,64 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/context.ts
+/**
+* The request context of server code (D19 seam 3): which call is running, for whom, and how to
+* reach the supervisor. Every call runs inside `AsyncLocalStorage`, so concurrent calls in one
+* worker each see their own viewer, run and `abortSignal` across every `await`. The worker installs
+* the {@link ServerHost} once; this module never does I/O of its own.
+*/
+const storage = new AsyncLocalStorage();
+let installed;
+/** Installs the process's {@link ServerHost}; the worker calls it once, before loading code. */
+function installServerHost(host) {
+	installed = host;
+}
+/** The installed host, or an error naming where server code must run. */
+function serverHost() {
+	if (!installed) throw Object.assign(/* @__PURE__ */ new Error("@mostra/server works only inside an artifact's worker: call it from a \"use server\" function or a live source."), { code: "MOSTRA_TARGET_UNAVAILABLE" });
+	return installed;
+}
+/** The current call, or `undefined` outside any (module scope, a timer started at load). */
+function currentCall() {
+	return storage.getStore();
+}
+/** Runs `fn` as `context`: everything it awaits sees the same call. */
+function runWithContext(context, fn) {
+	return storage.run(context, fn);
+}
+//#endregion
+//#region src/live.ts
+/**
+* Declares a live source (D56). Export it from `live.ts`; its export name is its key.
+*
+* ```ts
+* export const inbox = defineLive({ refresh: "5m", load: async () => fetchInbox() });
+* export const prices = defineLive({ stream: (signal) => tickerFeed(signal), ring: 3600 });
+* ```
+*/
+function defineLive(source) {
+	if (!source.load && !source.stream) throw new TypeError("defineLive needs a load function, a stream function, or both.");
+	if (source.refresh !== void 0) parseDuration(source.refresh);
+	if (source.ring !== void 0 && (!Number.isInteger(source.ring) || source.ring < 1)) throw new TypeError("defineLive's ring is the number of values to keep: a positive integer.");
+	return { "~mostra.live": source };
+}
+/** The options of a live source, or `undefined` for anything `defineLive` didn't make. */
+function liveSourceOptions(value) {
+	if (typeof value !== "object" || value === null) return void 0;
+	const options = value["~mostra.live"];
+	return typeof options === "object" && options !== null ? options : void 0;
+}
+/** `"5s"`, `"10m"`, `"24h"` → milliseconds; from 1 s to 24 h. */
+function parseDuration(text) {
+	const match = /^(\d+)(s|m|h)$/.exec(text);
+	const ms = match ? Number(match[1]) * {
+		s: 1e3,
+		m: 6e4,
+		h: 36e5
+	}[match[2]] : NaN;
+	if (!(ms >= 1e3 && ms <= 864e5)) throw new TypeError(`defineLive's refresh is a duration from "1s" to "24h", such as "30s" or "5m"; got ${JSON.stringify(text)}.`);
+	return ms;
+}
+//#endregion
+export { installServerHost as a, currentCall as i, liveSourceOptions as n, runWithContext as o, parseDuration as r, serverHost as s, defineLive as t };
+
+//# sourceMappingURL=live-2VU8jmOO.js.map

package/dist/live-2VU8jmOO.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-2VU8jmOO.js","names":[],"sources":["../src/context.ts","../src/live.ts"],"sourcesContent":["/**\n * The request context of server code (D19 seam 3): which call is running, for whom, and how to\n * reach the supervisor. Every call runs inside `AsyncLocalStorage`, so concurrent calls in one\n * worker each see their own viewer, run and `abortSignal` across every `await`. The worker installs\n * the {@link ServerHost} once; this module never does I/O of its own.\n */\nimport { AsyncLocalStorage } from \"node:async_hooks\";\nimport type { FieldOp, MutationResult } from \"@mostra/protocol\";\n\n/** One call as server code sees it. */\nexport interface ServerCallContext {\n  /** `call`: a plain call, no durable record. `run`: an action run (D54). */\n  readonly kind: \"call\" | \"run\";\n  /** The channel's ID of the call: progress, logs and signals name it. */\n  readonly callId: string;\n  /** The action run, for `kind: \"run\"`. */\n  readonly runId?: string;\n  /** Who the call is for. */\n  readonly viewer?: { readonly id: string; readonly name?: string };\n  /** True only during `verify`'s smoke test (D55). */\n  readonly dryRun: boolean;\n  /** Aborted when the run is cancelled or the caller goes away (AC-04). */\n  readonly signal: AbortSignal;\n}\n\n/** The artifact's shared state as the supervisor answers it. */\nexport interface StateSnapshot {\n  /** The state document's revision. */\n  readonly revision: string;\n  /** Its fields by ID. */\n  readonly fields: Readonly<\n    Record<string, { readonly value?: unknown; readonly deleted?: boolean }>\n  >;\n}\n\n/** What `@mostra/server` needs from the process it runs in: the worker implements it. */\nexport interface ServerHost {\n  /** The secret's value; throws an error with `code: \"MOSTRA_SECRET_MISSING\"` when there is none. */\n  secret(name: string): string;\n  /** Reports a call's progress. */\n  progress(callId: string, progress: { fraction?: number; message?: string }): void;\n  /** Adds a line to a call's log, or to the worker's own outside calls. */\n  log(callId: string | undefined, line: string): void;\n  /** Raises a signal (already checked). */\n  signal(callId: string | undefined, name: string, payload: unknown): void;\n  /** Appends a host event (already checked). */\n  emit(callId: string | undefined, type: string, payload: unknown): void;\n  /** Reads the artifact's shared state. */\n  stateGet(ids: readonly string[] | undefined): Promise<StateSnapshot>;\n  /** Writes the artifact's shared state as the agent. */\n  statePatch(\n    callId: string | undefined,\n    ops: readonly FieldOp[],\n    options: { readonly mutationId?: string; readonly baseRevision?: string },\n  ): Promise<MutationResult>;\n}\n\nconst storage = new AsyncLocalStorage<ServerCallContext>();\nlet installed: ServerHost | undefined;\n\n/** Installs the process's {@link ServerHost}; the worker calls it once, before loading code. */\nexport function installServerHost(host: ServerHost): void {\n  installed = host;\n}\n\n/** The installed host, or an error naming where server code must run. */\nexport function serverHost(): ServerHost {\n  if (!installed) {\n    throw Object.assign(\n      new Error(\n        '@mostra/server works only inside an artifact\\'s worker: call it from a \"use server\" function or a live source.',\n      ),\n      { code: \"MOSTRA_TARGET_UNAVAILABLE\" },\n    );\n  }\n  return installed;\n}\n\n/** The current call, or `undefined` outside any (module scope, a timer started at load). */\nexport function currentCall(): ServerCallContext | undefined {\n  return storage.getStore();\n}\n\n/** Runs `fn` as `context`: everything it awaits sees the same call. */\nexport function runWithContext<T>(context: ServerCallContext, fn: () => T): T {\n  return storage.run(context, fn);\n}\n","/**\n * Live sources (D56): `live.ts` exports `defineLive(…)` producers, which the artifact's worker runs\n * while someone views them, a host subscribes, or always with `always: true` (D63).\n */\n\n/** How a live source produces its values. */\nexport interface LiveSourceOptions<T> {\n  /** Loads the current value: on start, on every `refresh`, and when a `watch`ed file changes. */\n  readonly load?: () => Promise<T>;\n  /** How often `load` runs again: `\"5s\"` to `\"24h\"` (`s`, `m` or `h`). */\n  readonly refresh?: string;\n  /** Files whose changes run `load` again: globs relative to the artifact's source. */\n  readonly watch?: string | readonly string[];\n  /** Produces values as they come; `signal` aborts when the source stops. */\n  readonly stream?: (signal: AbortSignal) => AsyncIterable<T>;\n  /** Keep producing while nobody views the artifact (D63). */\n  readonly always?: boolean;\n  /** Keep the last N values for append mode (`useLive(key, { mode: \"append\" })`, AC-08). */\n  readonly ring?: number;\n}\n\n/** A live source, as `defineLive` returns it. Pages read it with `useLive(key)`. */\nexport interface LiveSource<T> {\n  /** The source's options, for the worker. */\n  readonly \"~mostra.live\": LiveSourceOptions<T>;\n  /** The value type, for `useLive`'s types (never set at run time). */\n  readonly __value?: T;\n}\n\n/**\n * Declares a live source (D56). Export it from `live.ts`; its export name is its key.\n *\n * ```ts\n * export const inbox = defineLive({ refresh: \"5m\", load: async () => fetchInbox() });\n * export const prices = defineLive({ stream: (signal) => tickerFeed(signal), ring: 3600 });\n * ```\n */\nexport function defineLive<T>(source: LiveSourceOptions<T>): LiveSource<T> {\n  if (!source.load && !source.stream) {\n    throw new TypeError(\"defineLive needs a load function, a stream function, or both.\");\n  }\n  if (source.refresh !== undefined) parseDuration(source.refresh);\n  if (source.ring !== undefined && (!Number.isInteger(source.ring) || source.ring < 1)) {\n    throw new TypeError(\"defineLive's ring is the number of values to keep: a positive integer.\");\n  }\n  return { \"~mostra.live\": source };\n}\n\n/** The options of a live source, or `undefined` for anything `defineLive` didn't make. */\nexport function liveSourceOptions(value: unknown): LiveSourceOptions<unknown> | undefined {\n  if (typeof value !== \"object\" || value === null) return undefined;\n  const options = (value as { \"~mostra.live\"?: unknown })[\"~mostra.live\"];\n  return typeof options === \"object\" && options !== null\n    ? (options as LiveSourceOptions<unknown>)\n    : undefined;\n}\n\n/** `\"5s\"`, `\"10m\"`, `\"24h\"` → milliseconds; from 1 s to 24 h. */\nexport function parseDuration(text: string): number {\n  const match = /^(\\d+)(s|m|h)$/.exec(text);\n  const unit = { s: 1_000, m: 60_000, h: 3_600_000 } as const;\n  const ms = match ? Number(match[1]) * unit[match[2] as keyof typeof unit] : Number.NaN;\n  if (!(ms >= 1_000 && ms <= 86_400_000)) {\n    throw new TypeError(\n      `defineLive's refresh is a duration from \"1s\" to \"24h\", such as \"30s\" or \"5m\"; got ${JSON.stringify(text)}.`,\n    );\n  }\n  return ms;\n}\n"],"mappings":";;;;;;;;AAyDA,MAAM,UAAU,IAAI,kBAAqC;AACzD,IAAI;;AAGJ,SAAgB,kBAAkB,MAAwB;CACxD,YAAY;AACd;;AAGA,SAAgB,aAAyB;CACvC,IAAI,CAAC,WACH,MAAM,OAAO,uBACX,IAAI,MACF,iHACF,GACA,EAAE,MAAM,4BAA4B,CACtC;CAEF,OAAO;AACT;;AAGA,SAAgB,cAA6C;CAC3D,OAAO,QAAQ,SAAS;AAC1B;;AAGA,SAAgB,eAAkB,SAA4B,IAAgB;CAC5E,OAAO,QAAQ,IAAI,SAAS,EAAE;AAChC;;;;;;;;;;;ACjDA,SAAgB,WAAc,QAA6C;CACzE,IAAI,CAAC,OAAO,QAAQ,CAAC,OAAO,QAC1B,MAAM,IAAI,UAAU,+DAA+D;CAErF,IAAI,OAAO,YAAY,KAAA,GAAW,cAAc,OAAO,OAAO;CAC9D,IAAI,OAAO,SAAS,KAAA,MAAc,CAAC,OAAO,UAAU,OAAO,IAAI,KAAK,OAAO,OAAO,IAChF,MAAM,IAAI,UAAU,wEAAwE;CAE9F,OAAO,EAAE,gBAAgB,OAAO;AAClC;;AAGA,SAAgB,kBAAkB,OAAwD;CACxF,IAAI,OAAO,UAAU,YAAY,UAAU,MAAM,OAAO,KAAA;CACxD,MAAM,UAAW,MAAuC;CACxD,OAAO,OAAO,YAAY,YAAY,YAAY,OAC7C,UACD,KAAA;AACN;;AAGA,SAAgB,cAAc,MAAsB;CAClD,MAAM,QAAQ,iBAAiB,KAAK,IAAI;CAExC,MAAM,KAAK,QAAQ,OAAO,MAAM,EAAE,IAAI;EADvB,GAAG;EAAO,GAAG;EAAQ,GAAG;CACE,EAAE,MAAM,MAA2B;CAC5E,IAAI,EAAE,MAAM,OAAS,MAAM,QACzB,MAAM,IAAI,UACR,qFAAqF,KAAK,UAAU,IAAI,EAAE,EAC5G;CAEF,OAAO;AACT"}

package/dist/live-BLUwPFXE.d.ts

@@ -0,0 +1,43 @@
+//#region src/live.d.ts
+/**
+ * Live sources (D56): `live.ts` exports `defineLive(…)` producers, which the artifact's worker runs
+ * while someone views them, a host subscribes, or always with `always: true` (D63).
+ */
+/** How a live source produces its values. */
+interface LiveSourceOptions<T> {
+  /** Loads the current value: on start, on every `refresh`, and when a `watch`ed file changes. */
+  readonly load?: () => Promise<T>;
+  /** How often `load` runs again: `"5s"` to `"24h"` (`s`, `m` or `h`). */
+  readonly refresh?: string;
+  /** Files whose changes run `load` again: globs relative to the artifact's source. */
+  readonly watch?: string | readonly string[];
+  /** Produces values as they come; `signal` aborts when the source stops. */
+  readonly stream?: (signal: AbortSignal) => AsyncIterable<T>;
+  /** Keep producing while nobody views the artifact (D63). */
+  readonly always?: boolean;
+  /** Keep the last N values for append mode (`useLive(key, { mode: "append" })`, AC-08). */
+  readonly ring?: number;
+}
+/** A live source, as `defineLive` returns it. Pages read it with `useLive(key)`. */
+interface LiveSource<T> {
+  /** The source's options, for the worker. */
+  readonly "~mostra.live": LiveSourceOptions<T>;
+  /** The value type, for `useLive`'s types (never set at run time). */
+  readonly __value?: T;
+}
+/**
+ * Declares a live source (D56). Export it from `live.ts`; its export name is its key.
+ *
+ * ```ts
+ * export const inbox = defineLive({ refresh: "5m", load: async () => fetchInbox() });
+ * export const prices = defineLive({ stream: (signal) => tickerFeed(signal), ring: 3600 });
+ * ```
+ */
+declare function defineLive<T>(source: LiveSourceOptions<T>): LiveSource<T>;
+/** The options of a live source, or `undefined` for anything `defineLive` didn't make. */
+declare function liveSourceOptions(value: unknown): LiveSourceOptions<unknown> | undefined;
+/** `"5s"`, `"10m"`, `"24h"` → milliseconds; from 1 s to 24 h. */
+declare function parseDuration(text: string): number;
+//#endregion
+export { parseDuration as a, liveSourceOptions as i, LiveSourceOptions as n, defineLive as r, LiveSource as t };
+//# sourceMappingURL=live-BLUwPFXE.d.ts.map

package/dist/live-BLUwPFXE.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-BLUwPFXE.d.ts","names":[],"sources":["../src/live.ts"],"mappings":";;;;;;UAMiB,kBAAkB;;WAExB,aAAa,QAAQ;;WAErB;;WAEA;;WAEA,UAAU,QAAQ,gBAAgB,cAAc;;WAEhD;;WAEA;;;UAIM,WAAW;;WAEjB,gBAAgB,kBAAkB;;WAElC,UAAU;;;;;;;;;;iBAWL,WAAW,GAAG,QAAQ,kBAAkB,KAAK,WAAW;;iBAYxD,kBAAkB,iBAAiB;;iBASnC,cAAc"}

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@mostra/server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "What server code imports: the request context, progress, secrets, signals, host events, artifact state and live sources.",
+  "license": "Apache-2.0",
+  "author": "The Mostra Authors",
+  "homepage": "https://github.com/mostra-dev/mostra/tree/main/packages/server#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mostra-dev/mostra.git",
+    "directory": "packages/server"
+  },
+  "bugs": "https://github.com/mostra-dev/mostra/issues",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "@mostra/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./host": {
+      "@mostra/source": "./src/host.ts",
+      "types": "./dist/host.d.ts",
+      "default": "./dist/host.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@mostra/protocol": "0.1.0"
+  },
+  "devDependencies": {
+    "@mostra/tools": "0.0.0",
+    "@types/node": "24.19.1",
+    "tsdown": "0.23.0",
+    "typescript": "7.0.2",
+    "vitest": "5.0.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -b",
+    "test": "vitest run",
+    "api": "mostra-tools api"
+  }
 }

package/src/context.ts

@@ -0,0 +1,87 @@
+/**
+ * The request context of server code (D19 seam 3): which call is running, for whom, and how to
+ * reach the supervisor. Every call runs inside `AsyncLocalStorage`, so concurrent calls in one
+ * worker each see their own viewer, run and `abortSignal` across every `await`. The worker installs
+ * the {@link ServerHost} once; this module never does I/O of its own.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { FieldOp, MutationResult } from "@mostra/protocol";
+
+/** One call as server code sees it. */
+export interface ServerCallContext {
+  /** `call`: a plain call, no durable record. `run`: an action run (D54). */
+  readonly kind: "call" | "run";
+  /** The channel's ID of the call: progress, logs and signals name it. */
+  readonly callId: string;
+  /** The action run, for `kind: "run"`. */
+  readonly runId?: string;
+  /** Who the call is for. */
+  readonly viewer?: { readonly id: string; readonly name?: string };
+  /** True only during `verify`'s smoke test (D55). */
+  readonly dryRun: boolean;
+  /** Aborted when the run is cancelled or the caller goes away (AC-04). */
+  readonly signal: AbortSignal;
+}
+
+/** The artifact's shared state as the supervisor answers it. */
+export interface StateSnapshot {
+  /** The state document's revision. */
+  readonly revision: string;
+  /** Its fields by ID. */
+  readonly fields: Readonly<
+    Record<string, { readonly value?: unknown; readonly deleted?: boolean }>
+  >;
+}
+
+/** What `@mostra/server` needs from the process it runs in: the worker implements it. */
+export interface ServerHost {
+  /** The secret's value; throws an error with `code: "MOSTRA_SECRET_MISSING"` when there is none. */
+  secret(name: string): string;
+  /** Reports a call's progress. */
+  progress(callId: string, progress: { fraction?: number; message?: string }): void;
+  /** Adds a line to a call's log, or to the worker's own outside calls. */
+  log(callId: string | undefined, line: string): void;
+  /** Raises a signal (already checked). */
+  signal(callId: string | undefined, name: string, payload: unknown): void;
+  /** Appends a host event (already checked). */
+  emit(callId: string | undefined, type: string, payload: unknown): void;
+  /** Reads the artifact's shared state. */
+  stateGet(ids: readonly string[] | undefined): Promise<StateSnapshot>;
+  /** Writes the artifact's shared state as the agent. */
+  statePatch(
+    callId: string | undefined,
+    ops: readonly FieldOp[],
+    options: { readonly mutationId?: string; readonly baseRevision?: string },
+  ): Promise<MutationResult>;
+}
+
+const storage = new AsyncLocalStorage<ServerCallContext>();
+let installed: ServerHost | undefined;
+
+/** Installs the process's {@link ServerHost}; the worker calls it once, before loading code. */
+export function installServerHost(host: ServerHost): void {
+  installed = host;
+}
+
+/** The installed host, or an error naming where server code must run. */
+export function serverHost(): ServerHost {
+  if (!installed) {
+    throw Object.assign(
+      new Error(
+        '@mostra/server works only inside an artifact\'s worker: call it from a "use server" function or a live source.',
+      ),
+      { code: "MOSTRA_TARGET_UNAVAILABLE" },
+    );
+  }
+  return installed;
+}
+
+/** The current call, or `undefined` outside any (module scope, a timer started at load). */
+export function currentCall(): ServerCallContext | undefined {
+  return storage.getStore();
+}
+
+/** Runs `fn` as `context`: everything it awaits sees the same call. */
+export function runWithContext<T>(context: ServerCallContext, fn: () => T): T {
+  return storage.run(context, fn);
+}

package/src/host.ts

@@ -0,0 +1,16 @@
+/**
+ * `@mostra/server/host`: what an artifact's worker uses to run server code: the request context
+ * (D19 seam 3), the bridge to the supervisor and the live sources `live.ts` declares. Artifact code
+ * never imports it.
+ *
+ * @packageDocumentation
+ */
+export {
+  currentCall,
+  installServerHost,
+  runWithContext,
+  type ServerCallContext,
+  type ServerHost,
+  type StateSnapshot,
+} from "./context.ts";
+export { type LiveSourceOptions, liveSourceOptions, parseDuration } from "./live.ts";

package/src/index.ts

@@ -0,0 +1,267 @@
+/**
+ * `@mostra/server`: what server code imports (INTERFACES §2.4). Inside `"use server"` functions and
+ * live sources, it tells who the call is for, reports progress and log lines to the page, reads
+ * secrets, raises signals and host events, and reads and writes the artifact's shared state.
+ * Server code runs with full capability (D05, AC-01): it can read files, start processes and call
+ * any network service; this package only adds what Mostra knows.
+ *
+ * ```ts
+ * "use server";
+ * import { abortSignal, dryRun, progress, secret, signal } from "@mostra/server";
+ *
+ * export async function sendReply(messageId: string, body: string) {
+ *   if (dryRun()) return { messageId, sent: false };
+ *   progress({ message: "Sending…" });
+ *   const response = await fetch("https://mail.example/api/send", {
+ *     method: "POST",
+ *     headers: { authorization: `Bearer ${secret("MAIL_TOKEN")}`, "idempotency-key": messageId },
+ *     body: JSON.stringify({ messageId, body }),
+ *     signal: abortSignal,
+ *   });
+ *   if (!response.ok) throw new Error(`Mail API returned ${response.status}`);
+ *   signal("reply-sent", { messageId });
+ *   return { messageId, sent: true };
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { canonicalJson, type FieldOp, SIGNAL_NAME_PATTERN } from "@mostra/protocol";
+import { currentCall, serverHost } from "./context.ts";
+
+export { defineLive, type LiveSource, type LiveSourceOptions } from "./live.ts";
+
+/** Any JSON value. */
+export type Json = string | number | boolean | null | Json[] | { [key: string]: Json };
+
+/** An error with a Mostra diagnostic code, as `@mostra/server` throws them. */
+export class MostraServerError extends Error {
+  /** The diagnostic code, such as `MOSTRA_SECRET_MISSING`. */
+  readonly code: string;
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = "MostraServerError";
+    this.code = code;
+  }
+}
+
+const PAYLOAD_MAX = 64 * 1024;
+
+function checkPayload(code: string, what: string, payload: unknown): void {
+  if (payload === undefined) return;
+  let text: string;
+  try {
+    text = canonicalJson(payload);
+  } catch {
+    throw new MostraServerError(code, `The payload of ${what} isn't JSON.`);
+  }
+  if (Buffer.byteLength(text, "utf8") > PAYLOAD_MAX) {
+    throw new MostraServerError(code, `The payload of ${what} is larger than 64 KiB of JSON.`);
+  }
+}
+
+/**
+ * Whether this call is `verify`'s smoke test (D55). An action that checks it opts into the smoke
+ * test, and should then return without real effects; one that never calls it is skipped there.
+ */
+export function dryRun(): boolean {
+  return currentCall()?.dryRun ?? false;
+}
+
+/** Reports the run's progress to every page following it (ephemeral, never an event). */
+export function progress(p: { fraction?: number; message?: string }): void {
+  const call = currentCall();
+  if (!call) return;
+  const fraction = p.fraction === undefined ? undefined : Math.min(1, Math.max(0, p.fraction));
+  serverHost().progress(call.callId, {
+    ...(fraction === undefined || Number.isNaN(fraction) ? {} : { fraction }),
+    ...(p.message === undefined ? {} : { message: String(p.message).slice(0, 1000) }),
+  });
+}
+
+/**
+ * Adds a line to the run's log (kept with the run, capped at 1 MB, D47); outside a run, to the
+ * worker's own log. Secrets are redacted from it.
+ */
+export function log(line: string): void {
+  serverHost().log(currentCall()?.callId, String(line));
+}
+
+/**
+ * A secret's value, by name (D44): from the host's `secrets` port, the artifact's own secrets or
+ * the home's shared ones. Never put the value in a result, a log or a signal.
+ *
+ * @throws MostraServerError `MOSTRA_SECRET_MISSING` when no store holds it.
+ */
+export function secret(name: string): string {
+  return serverHost().secret(name);
+}
+
+/**
+ * Raises a named signal for the host's attention (IN-09): one durable `signal.raised` event with
+ * `source: "action"` and this run as its causation. Mostra wakes no one by itself (D10).
+ *
+ * @throws MostraServerError `MOSTRA_SUBMIT_SIGNAL_INVALID` for a bad name or a payload over 64 KiB.
+ */
+export function signal(name: string, payload?: Json): void {
+  if (typeof name !== "string" || !SIGNAL_NAME_PATTERN.test(name) || name === "submit") {
+    throw new MostraServerError(
+      "MOSTRA_SUBMIT_SIGNAL_INVALID",
+      `${JSON.stringify(name).slice(0, 80)} isn't a signal name: 1 to 64 letters, digits, ".", "_" and "-", and not "submit".`,
+    );
+  }
+  checkPayload("MOSTRA_SUBMIT_SIGNAL_INVALID", `the signal ${name}`, payload);
+  serverHost().signal(currentCall()?.callId, name, payload);
+}
+
+/**
+ * Appends a host event, `host.<name>`, to the event log (AC-05), which hosts filter for.
+ *
+ * @throws MostraServerError `MOSTRA_ACTION_EVENT_INVALID` for a bad type or a payload over 64 KiB.
+ */
+export function emit(type: `host.${string}`, payload?: Json): void {
+  const name = typeof type === "string" && type.startsWith("host.") ? type.slice(5) : "";
+  if (!SIGNAL_NAME_PATTERN.test(name)) {
+    throw new MostraServerError(
+      "MOSTRA_ACTION_EVENT_INVALID",
+      `${JSON.stringify(type).slice(0, 80)} isn't a host event type: "host." and 1 to 64 letters, digits, ".", "_" and "-".`,
+    );
+  }
+  checkPayload("MOSTRA_ACTION_EVENT_INVALID", `the event ${type}`, payload);
+  serverHost().emit(currentCall()?.callId, type, payload);
+}
+
+/** Who the call is for; `undefined` in live producers and outside calls. */
+export function viewer(): { id: string; name?: string } | undefined {
+  const who = currentCall()?.viewer;
+  return who ? { ...who } : undefined;
+}
+
+const idle = new AbortController().signal;
+
+/**
+ * The bound copies of listeners, per signal: each call has its own signal, so a listener added in
+ * two calls (a module-level callback, say) gets a copy bound to each call's context, and removing
+ * it from one call's signal finds that call's copy.
+ */
+const boundListeners = new WeakMap<AbortSignal, WeakMap<object, (event: Event) => void>>();
+
+/** A listener that runs in the call it was added in, as `await`ed code does. */
+function bindListener(target: AbortSignal, listener: unknown): unknown {
+  if (typeof listener !== "function" && (typeof listener !== "object" || listener === null)) {
+    return listener;
+  }
+  let perSignal = boundListeners.get(target);
+  if (!perSignal) {
+    perSignal = new WeakMap();
+    boundListeners.set(target, perSignal);
+  }
+  let bound = perSignal.get(listener);
+  if (!bound) {
+    const handle =
+      typeof listener === "function"
+        ? (listener as (event: Event) => void)
+        : (event: Event) => (listener as { handleEvent(event: Event): void }).handleEvent(event);
+    bound = AsyncLocalStorage.bind(handle);
+    perSignal.set(listener, bound);
+  }
+  return bound;
+}
+
+/**
+ * The current call's cancellation (AC-04): aborted when a page cancels the run or the caller goes
+ * away. Pass it to `fetch` and other cancellable work. Outside a call it never aborts. Listeners
+ * added to it run in the call that added them, so they read `abortSignal.reason` of that call.
+ */
+export const abortSignal: AbortSignal = new Proxy(idle, {
+  get(_target, property) {
+    const target = currentCall()?.signal ?? idle;
+    if (property === "addEventListener" || property === "removeEventListener") {
+      const method = target[property].bind(target) as (
+        type: string,
+        listener: unknown,
+        options?: unknown,
+      ) => void;
+      return (type: string, listener: unknown, options?: unknown) =>
+        method(type, bindListener(target, listener), options);
+    }
+    const value: unknown = Reflect.get(target, property, target);
+    return typeof value === "function" ? value.bind(target) : value;
+  },
+  set(_target, property, value) {
+    const target = currentCall()?.signal ?? idle;
+    return Reflect.set(
+      target,
+      property,
+      property === "onabort" ? bindListener(target, value) : value,
+      target,
+    );
+  },
+  has(_target, property) {
+    return Reflect.has(currentCall()?.signal ?? idle, property);
+  },
+});
+
+/** Options of a state write. */
+export interface StateWriteOptions {
+  /** The change's ID: a retry with the same ID and contents returns the recorded result. */
+  readonly mutationId?: string;
+  /** The revision you read: a field changed after it is a conflict and keeps its value. */
+  readonly baseRevision?: string;
+}
+
+/** The artifact's shared state, as server code reads and writes it. */
+export interface ServerState {
+  /** A field's value, or `undefined` when it isn't set. */
+  get<T>(id: string): Promise<T | undefined>;
+  /**
+   * Sets one field.
+   *
+   * @throws MostraServerError `MOSTRA_FIELD_CONFLICT` when the field changed after `baseRevision`.
+   */
+  set<T>(id: string, value: T, options?: StateWriteOptions): Promise<{ revision: string }>;
+  /** Sets and deletes several fields under one revision; conflicting ones are listed. */
+  patch(
+    ops: readonly { id: string; value?: Json; delete?: true }[],
+    options?: StateWriteOptions,
+  ): Promise<{ revision: string; conflicts: string[] }>;
+}
+
+/**
+ * The artifact's shared state (D63): the artifact-scoped fields every viewer sees, written through
+ * the same compare-and-set as viewers' edits, as the agent. Each write appends `state.changed`.
+ */
+export const state: ServerState = {
+  async get<T>(id: string): Promise<T | undefined> {
+    const snapshot = await serverHost().stateGet([id]);
+    const field = snapshot.fields[id];
+    return field && !field.deleted ? (field.value as T) : undefined;
+  },
+  async set<T>(id: string, value: T, options: StateWriteOptions = {}) {
+    const result = await serverHost().statePatch(
+      currentCall()?.callId,
+      [{ id, value } as FieldOp],
+      options,
+    );
+    if (result.conflicts.length > 0) {
+      throw new MostraServerError(
+        "MOSTRA_FIELD_CONFLICT",
+        `The state field ${id} changed after revision ${options.baseRevision ?? "?"}; read it again and decide.`,
+      );
+    }
+    return { revision: result.revision };
+  },
+  async patch(ops, options: StateWriteOptions = {}) {
+    const fieldOps = ops.map((op) =>
+      op.delete
+        ? ({ id: op.id, delete: true } as FieldOp)
+        : ({ id: op.id, value: op.value } as FieldOp),
+    );
+    const result = await serverHost().statePatch(currentCall()?.callId, fieldOps, options);
+    return {
+      revision: result.revision,
+      conflicts: result.conflicts.map((conflict) => conflict.id),
+    };
+  },
+};

package/src/live.ts

@@ -0,0 +1,69 @@
+/**
+ * Live sources (D56): `live.ts` exports `defineLive(…)` producers, which the artifact's worker runs
+ * while someone views them, a host subscribes, or always with `always: true` (D63).
+ */
+
+/** How a live source produces its values. */
+export interface LiveSourceOptions<T> {
+  /** Loads the current value: on start, on every `refresh`, and when a `watch`ed file changes. */
+  readonly load?: () => Promise<T>;
+  /** How often `load` runs again: `"5s"` to `"24h"` (`s`, `m` or `h`). */
+  readonly refresh?: string;
+  /** Files whose changes run `load` again: globs relative to the artifact's source. */
+  readonly watch?: string | readonly string[];
+  /** Produces values as they come; `signal` aborts when the source stops. */
+  readonly stream?: (signal: AbortSignal) => AsyncIterable<T>;
+  /** Keep producing while nobody views the artifact (D63). */
+  readonly always?: boolean;
+  /** Keep the last N values for append mode (`useLive(key, { mode: "append" })`, AC-08). */
+  readonly ring?: number;
+}
+
+/** A live source, as `defineLive` returns it. Pages read it with `useLive(key)`. */
+export interface LiveSource<T> {
+  /** The source's options, for the worker. */
+  readonly "~mostra.live": LiveSourceOptions<T>;
+  /** The value type, for `useLive`'s types (never set at run time). */
+  readonly __value?: T;
+}
+
+/**
+ * Declares a live source (D56). Export it from `live.ts`; its export name is its key.
+ *
+ * ```ts
+ * export const inbox = defineLive({ refresh: "5m", load: async () => fetchInbox() });
+ * export const prices = defineLive({ stream: (signal) => tickerFeed(signal), ring: 3600 });
+ * ```
+ */
+export function defineLive<T>(source: LiveSourceOptions<T>): LiveSource<T> {
+  if (!source.load && !source.stream) {
+    throw new TypeError("defineLive needs a load function, a stream function, or both.");
+  }
+  if (source.refresh !== undefined) parseDuration(source.refresh);
+  if (source.ring !== undefined && (!Number.isInteger(source.ring) || source.ring < 1)) {
+    throw new TypeError("defineLive's ring is the number of values to keep: a positive integer.");
+  }
+  return { "~mostra.live": source };
+}
+
+/** The options of a live source, or `undefined` for anything `defineLive` didn't make. */
+export function liveSourceOptions(value: unknown): LiveSourceOptions<unknown> | undefined {
+  if (typeof value !== "object" || value === null) return undefined;
+  const options = (value as { "~mostra.live"?: unknown })["~mostra.live"];
+  return typeof options === "object" && options !== null
+    ? (options as LiveSourceOptions<unknown>)
+    : undefined;
+}
+
+/** `"5s"`, `"10m"`, `"24h"` → milliseconds; from 1 s to 24 h. */
+export function parseDuration(text: string): number {
+  const match = /^(\d+)(s|m|h)$/.exec(text);
+  const unit = { s: 1_000, m: 60_000, h: 3_600_000 } as const;
+  const ms = match ? Number(match[1]) * unit[match[2] as keyof typeof unit] : Number.NaN;
+  if (!(ms >= 1_000 && ms <= 86_400_000)) {
+    throw new TypeError(
+      `defineLive's refresh is a duration from "1s" to "24h", such as "30s" or "5m"; got ${JSON.stringify(text)}.`,
+    );
+  }
+  return ms;
+}