@ogygia/core 0.12.2 → 0.13.0

package/dist/server/rules.js

@@ -0,0 +1,64 @@
+import { Rules } from "../rules.js";
+import { warn } from "../messages/server.js";
+import { observe } from "@ogygia/machine";
+// src/server/rules.ts
+/**
+* THE SERVER'S RULES (#313, ../rules.ts): what is always true of the server, checked a task after
+* each response ends (in dev, and in a build made with `OGYGIA_RULES=1`), printed with its code.
+*
+* - `rule_request_scope_open`: a request's scope (its timers, streams, fetches) is closed once its
+*   response has ended.
+* - `rule_flight_kept_failure`: no flight keeps a failure: an answer kept is never an error.
+*
+* Each area tells this module what it holds (`note_response_end`) only when rules are on: every call
+* site folds out of a build without them.
+*/
+/** The server's rules. */
+const server_rules = /* @__PURE__ */ new Rules();
+/** Request scopes whose response has ended, until a check sees them closed. */
+const ended = /* @__PURE__ */ new Set();
+/** A response ended (its body read to the end, cancelled, or none): its request's scope must be
+*  closed by the time the next check runs. */
+function note_response_end(owner) {
+	if (!installed) return;
+	ended.add(owner);
+	check_soon();
+}
+function request_scopes_closed() {
+	let open = 0;
+	for (const owner of ended) if (owner.closed) ended.delete(owner);
+	else open++;
+	return open === 0 ? null : `${open} request scope(s) still open after their response ended`;
+}
+/** The flights' entries that keep an error as their answer now, each with what it keeps. An entry
+*  leaves when it moves on (dropped, or a fresh answer kept): the rule is about what is kept now, so
+*  a check (a simulated run, the next response in dev) sees its own breaks, not an earlier one's. */
+const kept_failures = /* @__PURE__ */ new Map();
+function no_kept_failure() {
+	if (kept_failures.size === 0) return null;
+	return [...kept_failures.values()].slice(0, 10).join("; ");
+}
+let installed = false;
+let pending = false;
+/** Checks every rule a task from now (once, however many responses ask), and says what broke. */
+function check_soon() {
+	if (pending) return;
+	pending = true;
+	setTimeout(() => {
+		pending = false;
+		server_rules.say((code, detail) => warn(code, { detail }));
+	}, 0);
+}
+/** Rules on: checked after each response, and what broke is said with its code. */
+function install_server_rules() {
+	if (installed) return;
+	installed = true;
+	server_rules.add("rule_request_scope_open", request_scopes_closed);
+	server_rules.add("rule_flight_kept_failure", no_kept_failure);
+	observe((name, _from, to, machine) => {
+		const answer = to?.kind === "kept" ? to.answer : void 0;
+		if (answer instanceof Error) kept_failures.set(machine, `"${name}" kept ${answer.name}: ${answer.message.slice(0, 120)}`);
+		else if (kept_failures.size !== 0) kept_failures.delete(machine);
+	});
+}
+export { install_server_rules, note_response_end, server_rules };

package/dist/server/signing-key.js

@@ -1,3 +1,4 @@
+import { OgygiaError, warn } from "../messages/server.js";
 import { buildHadSecret, buildKey } from "virtual:ogygia/secret";
 import { sign } from "virtual:ogygia/sign";
 import { building } from "$app/env";
@@ -24,23 +25,27 @@ const SOURCE_NAME = {
 	env: "OGYGIA_SECRET",
 	build: "this build's random key"
 };
+const slots = globalThis;
 function slot() {
-	const g = globalThis;
-	return g[SLOT] ??= {};
+	return slots[SLOT] ?? { kind: "undecided" };
 }
 function signing_key() {
 	const s = slot();
-	if (s.key) return s.key;
+	if (s.kind === "decided") return s.key;
 	const from_env = typeof process !== "undefined" && process.env?.OGYGIA_SECRET || "";
-	const [secret, source] = s.option ? [s.option, "option"] : from_env ? [from_env, "env"] : [buildKey, "build"];
-	s.key = {
+	const [secret, source] = s.kind === "secret" ? [s.option, "option"] : from_env ? [from_env, "env"] : [buildKey, "build"];
+	const key = {
 		secret,
 		stable: source !== "build",
 		fp: key_fingerprint(secret),
 		source
 	};
-	if (!s.key.stable && !import.meta.env.DEV) warn_build_key();
-	return s.key;
+	slots[SLOT] = {
+		kind: "decided",
+		key
+	};
+	if (!key.stable && !import.meta.env.DEV) warn_build_key();
+	return key;
 }
 /**
 * Record the app's `handle({ secret })`. A blank one counts as none (an app can pass a value that may
@@ -50,15 +55,23 @@ function signing_key() {
 function configure_signing_secret(secret) {
 	if (!secret?.trim()) return;
 	const s = slot();
-	const decided = s.key?.secret ?? s.option;
-	if (decided === void 0 || decided === secret) {
-		s.option = secret;
+	if (s.kind === "undecided") {
+		slots[SLOT] = {
+			kind: "secret",
+			option: secret
+		};
 		return;
 	}
-	const from = s.key ? `${SOURCE_NAME[s.key.source]}, decided by an earlier mint or verify` : "another handle({ secret })";
-	const message = `[ogygia] handle({ secret }) names key ${key_fingerprint(secret)}, but this server already signs with key ${key_fingerprint(decided)} (from ${from}). The first key stays: pass one secret, before anything renders.`;
-	if (import.meta.env.DEV) throw new Error(message);
-	console.error(message);
+	const decided = s.kind === "decided" ? s.key.secret : s.option;
+	if (decided === secret) return;
+	const from = s.kind === "decided" ? `${SOURCE_NAME[s.key.source]}, decided by an earlier mint or verify` : "another handle({ secret })";
+	const error = new OgygiaError("secret_conflict", {
+		key: key_fingerprint(secret),
+		decided: key_fingerprint(decided),
+		from
+	});
+	if (import.meta.env.DEV) throw error;
+	console.error(error);
 }
 function key_fingerprint(secret) {
 	return sign(secret, "ogygia:key-fp").slice(0, 8);
@@ -70,12 +83,12 @@ function warn_build_key() {
 	const K = Symbol.for("ogygia.build-key-warned");
 	if (g[K]) return;
 	g[K] = true;
-	if (building) console.warn("[ogygia] prerendered page mints region capabilities signed with a per-build random key — they stop verifying after your next deploy while the static HTML lives on. Set a stable OGYGIA_SECRET env var (or pass it to handle({ secret })) so prerendered holes survive redeploys.");
-	else if (buildHadSecret) console.error("[ogygia] OGYGIA_SECRET was set when this app was built but is not set where it runs: region capabilities are signed with this build's random key, so every hole minted by another deployment (another backend behind the same CDN, the previous deploy) is refused (403, x-ogygia-deny: foreign-key). Set OGYGIA_SECRET in the server's runtime environment, or pass it to handle({ secret }) (e.g. from $env/static/private).");
-	else console.warn("[ogygia] OGYGIA_SECRET is not set: region capabilities are signed with this build's random key, so a page cached across a deploy, or served by another deployment than its islands endpoint, gets its holes refused (403, x-ogygia-deny: foreign-key). Set a stable OGYGIA_SECRET, or pass one to handle({ secret }).");
+	if (building) warn("build_key_prerender");
+	else if (buildHadSecret) console.error(new OgygiaError("secret_missing_at_runtime"));
+	else warn("secret_missing");
 }
 /** Tests: forget the decided key and the app's secret. */
 function reset_signing_key() {
-	delete globalThis[SLOT];
+	delete slots[SLOT];
 }
 export { configure_signing_secret, key_fingerprint, reset_signing_key, signing_key };

package/dist/server/stream-regions.d.ts

@@ -1,5 +1,18 @@
+import { Scope } from "@ogygia/machine";
 /** Build a parcel `<template data-ogygia-slot="…">…rendered html…</template>` (length-framed when
  *  the html carries a `</template` of its own). */
 export declare function build_parcel(slot: string, html: string): string;
 /** The done-sentinel parcel (empty template) the client watches to end the batch. */
-export declare function done_parcel(): string;
+export declare function done_parcel(): string;
+/** One region call's answer in a batch: its slot (the capability signature) and its HTML. Null:
+ *  the call is left out (the client fetches it on its own). */
+export type BatchAnswer = {
+  slot: string;
+  html: string;
+} | null;
+/**
+ * The batch's frame stream: every call renders at once, and each answer goes out as its parcel the
+ * moment it settles, whatever the order; the done sentinel ends it. `render` is handed the batch's
+ * signal: it aborts when the stream is cancelled, or when `owner` (the request's) ends first.
+ */
+export declare function batch_stream(calls: readonly string[], render: (endpoint: string, signal: AbortSignal) => Promise<BatchAnswer>, owner?: Scope): ReadableStream<Uint8Array>;

package/dist/server/stream-regions.js

@@ -1,3 +1,4 @@
+import { STALE, machine } from "@ogygia/machine";
 // src/server/stream-regions.ts
 /**
 * Region parcels for the batch endpoint (single-flight navigation, a page's first-load holes, OOO).
@@ -11,7 +12,7 @@
 * decoded string counts in — so its content can never close the box or forge a parcel for another
 * slot, and it no longer falls back to a second request.
 *
-* Pure (no I/O, no Kit) so it stays unit-testable.
+* No I/O and no Kit (the batch stream is handed its render), so it stays unit-testable.
 */
 /** Sentinel slot appended once a batch finishes, so waiting regions know it is complete. */
 const STREAM_DONE_SLOT = "__ogygia_done__";
@@ -33,4 +34,39 @@ function build_parcel(slot, html) {
 function done_parcel() {
 	return `<template data-ogygia-slot="${STREAM_DONE_SLOT}"></template>`;
 }
-export { build_parcel, done_parcel };
+const batch_def = machine()({
+	name: "batch stream",
+	initial: "streaming",
+	steps: {
+		streaming: ["ended", "cancelled"],
+		ended: [],
+		cancelled: []
+	}
+});
+/**
+* The batch's frame stream: every call renders at once, and each answer goes out as its parcel the
+* moment it settles, whatever the order; the done sentinel ends it. `render` is handed the batch's
+* signal: it aborts when the stream is cancelled, or when `owner` (the request's) ends first.
+*/
+function batch_stream(calls, render, owner) {
+	const encoder = new TextEncoder();
+	const batch = batch_def.create();
+	owner?.defer(() => {
+		batch.move("streaming", "cancelled");
+	});
+	return new ReadableStream({
+		async start(controller) {
+			const streaming = batch.now;
+			if (await batch.scope.task((signal) => Promise.all(calls.map(async (endpoint) => {
+				const out = await render(endpoint, signal).catch(() => null);
+				if (out && batch.now === streaming) controller.enqueue(encoder.encode(build_parcel(out.slot, out.html)));
+			}))) === STALE || !batch.move("streaming", "ended")) return;
+			controller.enqueue(encoder.encode(done_parcel()));
+			controller.close();
+		},
+		cancel() {
+			batch.move("streaming", "cancelled");
+		}
+	});
+}
+export { batch_stream, build_parcel, done_parcel };

package/dist/shared-state.js

@@ -1,3 +1,4 @@
+import { OgygiaError } from "./messages/island.js";
 import { parse, stringify } from "devalue";
 import { createSubscriber } from "svelte/reactivity";
 // src/shared-state.ts
@@ -46,7 +47,10 @@ function snapshot(name, value) {
 	try {
 		return parse(stringify(value));
 	} catch (e) {
-		throw new Error(`[ogygia] SharedState '${name}': values must be plain data (devalue-serializable — JSON, Date, Map, Set, BigInt, RegExp). Functions, class instances, and DOM nodes do not cross build boundaries — share facts, not live objects. (${e instanceof Error ? e.message : e})`);
+		throw new OgygiaError("shared_state_not_plain", {
+			name,
+			reason: e instanceof Error ? e.message : String(e)
+		});
 	}
 }
 var SharedState = class {

package/dist/shims/app-navigation.js

@@ -1,14 +1,15 @@
 import { kit_bridge } from "./kit-bridge.js";
 import { refresh_remote_instances } from "./kit-remote/remote-cache.js";
 import { bind_to_component } from "../runtime/nav-hooks.js";
+import { OgygiaError } from "../messages/island.js";
 // src/shims/app-navigation.ts
 const kit = () => kit_bridge()?.navigation ?? null;
 const og = () => globalThis[Symbol.for("ogygia.nav")] ?? null;
 /** No runtime on this document at all (neither Kit's nor ogygia's): the browser navigates. */
 function browser_goto(url, opts = {}) {
 	const target = new URL(url, location.href);
-	if (target.protocol !== "http:" && target.protocol !== "https:") throw new Error("[ogygia] goto() only supports http(s) URLs");
-	if (target.origin !== location.origin && !opts.external) throw new Error("[ogygia] goto() only supports same-origin URLs (pass { external: true } to leave)");
+	if (target.protocol !== "http:" && target.protocol !== "https:") throw new OgygiaError("goto_not_http");
+	if (target.origin !== location.origin && !opts.external) throw new OgygiaError("goto_cross_origin");
 	if (opts.replaceState) location.replace(target.href);
 	else location.assign(target.href);
 	return Promise.resolve();

package/dist/shims/page-store.svelte.js

@@ -1,4 +1,5 @@
 import { foreign_hydrate } from "../current-region.js";
+import { warn } from "../messages/island.js";
 // src/shims/page-store.svelte.ts
 const FALLBACK = {
 	url: typeof location !== "undefined" ? new URL(location.href) : new URL("http://localhost/"),
@@ -32,7 +33,9 @@ var PageState = class {
 		this.state = s.state ?? {};
 		for (const fn of this.#subscribers) try {
 			fn();
-		} catch {}
+		} catch (error) {
+			report_thrown(error);
+		}
 	}
 	reset() {
 		this.set({
@@ -51,6 +54,13 @@ var PageState = class {
 		return () => this.#subscribers.delete(fn);
 	}
 };
+/** report-thrown.ts's `report_thrown`, here in full: island-side code never imports a module the
+*  runtime's boot imports (runtime-boot-svelte-free.test.ts), and the boot's ref watchers use it. */
+function report_thrown(error) {
+	const report = globalThis.reportError;
+	if (typeof report === "function") report(error);
+	else console.error(error);
+}
 const PAGE_STATE_KEY = Symbol.for("ogygia.page-state");
 const global_scope = globalThis;
 const page_state = global_scope[PAGE_STATE_KEY] ??= new PageState();
@@ -72,6 +82,10 @@ function warn_foreign_page_read(expr) {
 	const f = foreign_hydrate();
 	if (!f || warned_foreign_entries.has(f.entry)) return;
 	warned_foreign_entries.add(f.entry);
-	console.warn(`[ogygia] ${expr} was read inside a mounted MFE island (${f.entry}, from ${f.origin}).\nIn the browser this is the SHELL's page, not the MFE's. The HTML you see was rendered with the MFE's own load data, so this island will repaint with different values after hydrate.\nPass the value as a prop, or read it with a remote function.`);
+	warn("foreign_page_read", {
+		expr,
+		entry: f.entry,
+		origin: f.origin
+	});
 }
 export { PageState, page_state, reset_page, set_page, subscribe_page, warn_foreign_page_read };

package/dist/source.js

@@ -1,4 +1,5 @@
 import { fnv1a } from "./runtime/hash.js";
+import { report_thrown } from "./report-thrown.js";
 // src/source.ts
 /**
 * DATA SOURCES — `import.meta.og.source(fn)`, the RUNTIME half (the compiler rewrites the macro to
@@ -29,10 +30,14 @@ function set_source_observer(fn) {
 function record_source_read(tag) {
 	try {
 		slots.recorder?.(tag);
-	} catch {}
+	} catch (error) {
+		report_thrown(error);
+	}
 	try {
 		slots.observer?.(tag);
-	} catch {}
+	} catch (error) {
+		report_thrown(error);
+	}
 }
 /** The identity stamp — read by `postrender.invalidate(fn, args)`. */
 const SOURCE_ID = Symbol.for("ogygia.source.id");

package/dist/store-transport.js

@@ -1,5 +1,6 @@
 import { wire } from "./live-transport.js";
 import { mint, register_kind, resolve } from "./ref.js";
+import { OgygiaError, warn } from "./messages/island.js";
 import { derived, get, writable } from "svelte/store";
 // src/store-transport.ts
 /**
@@ -81,7 +82,7 @@ function mark_store(store, tag) {
 			enumerable: false
 		});
 	} catch {
-		if (typeof console !== "undefined") console.warn(`[ogygia] store "${tag}": the store object is not extensible (frozen/sealed), so it cannot carry its factory brand — it will cross boundaries as a plain writable (custom methods unavailable). Brand before freezing, or leave the store extensible.`);
+		if (typeof console !== "undefined") warn("store_not_extensible", { tag });
 	}
 	return store;
 }
@@ -100,12 +101,15 @@ function register_store_kind() {
 			const t = ref.t ?? GENERIC_TAG;
 			const factory = t === GENERIC_TAG ? void 0 : store_registry().factories.get(t);
 			if (t !== GENERIC_TAG && factory === void 0) {
-				if (typeof console !== "undefined") console.warn(`[ogygia] store "${t}": factory not loaded in this bundle — degraded to a plain writable (custom methods unavailable). Import the factory's module in the island (or its graph) so \`__register_store_factory\` runs there.`);
+				if (typeof console !== "undefined") warn("store_factory_missing", { tag: t });
 				return writable(ref.d);
 			}
 			const built = factory ? factory(ref.d) : writable(ref.d);
 			if (built === null || typeof built !== "object") {
-				if (typeof console !== "undefined") console.warn(`[ogygia] store "${t}": factory returned ${type_of(built)} while rebuilding — degraded to a plain writable (custom methods unavailable). A store factory must return a store on every call; move environment guards inside the factory body.`);
+				if (typeof console !== "undefined") warn("store_factory_bad_rebuild", {
+					tag: t,
+					got: type_of(built)
+				});
 				return writable(ref.d);
 			}
 			return built;
@@ -160,7 +164,10 @@ function __og_store(tag, factory) {
 		if (product === null || typeof product !== "object") {
 			if (!warned_unbranded.has(tag) && typeof console !== "undefined") {
 				warned_unbranded.add(tag);
-				console.warn(`[ogygia] store "${tag}": factory returned ${type_of(product)} — nothing to brand, value passed through as-is. Fine for a client-only store; a store that must cross an island boundary has to exist on the server too — return e.g. writable(seed) under your guard and gate the side effects inside the factory instead.`);
+				warn("store_factory_unbranded", {
+					tag,
+					got: type_of(product)
+				});
 			}
 			return product;
 		}
@@ -221,7 +228,7 @@ function register_derived_kind() {
 		},
 		decode(ref) {
 			const d = ref.d;
-			if (typeof d.f !== "function") throw new Error("[ogygia] cannot resume og_derived: its formula did not cross — mark it with import.meta.og.$ at the og_derived call site so it travels as a fn ref.");
+			if (typeof d.f !== "function") throw new OgygiaError("og_derived_formula_missing");
 			return og_derived(d.single ? d.s[0] : d.s, d.f, d.seed);
 		}
 	});

package/dist/transport.js

@@ -6,6 +6,7 @@ import { register_wire_kind } from "./live-transport.js";
 import { register_derived_kind, register_store_kind } from "./store-transport.js";
 import { register_snippet_kind } from "./region-snippet.js";
 import { register_fn_kind } from "./fn-transport.js";
+import { OgygiaError } from "./messages/island.js";
 // src/transport.ts
 /**
 * `ogygiaTransport` — the SvelteKit `transport` entry that lets a held region cross the wire.
@@ -38,7 +39,7 @@ function encode_region(value) {
 			return pack(f.id, props, sign(f.id, props), f.module, f.hydrate, f.hydrateMargin, f.html);
 		}
 		if (typeof f.html === "string") return pack("", f.props ?? {}, "", "", void 0, void 0, f.html);
-		throw new Error("[ogygia] a held region reached the wire but its component is a plain import, so nothing built a chunk for it. `await` the region before returning it from a remote/load — an awaited region bakes its SSR HTML and crosses as an HTML-only ticket. Or import the component `with { region: 'raw' }` (or a `wake:` mark) to make it a signed, fetchable capability. On a csr=false page you can also skip the wire entirely: call `get()` in a universal `+page.ts` load / the component — its data reaches the render by reference.");
+		throw new OgygiaError("held_region_plain_import");
 	}
 }
 /** The region DECODE law (single-flight frame write for baked HTML + deferred rebuild),
@@ -88,7 +89,7 @@ function register_region_kind() {
 		},
 		encode(value) {
 			const packed = encode_region(value);
-			if (packed === false) throw new Error("[ogygia] region kind claimed a non-region value");
+			if (packed === false) throw new OgygiaError("region_kind_mismatch");
 			return { d: packed };
 		},
 		decode(ref) {