@mosetta/router 0.0.0-stage → 0.0.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mosetta contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @mosetta/router
 
-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.
+The line instruction of mosetta: what a factory line is composed from — its modules by reference,
+reserved module names, the control headers between the factory gate and its lines, and the
+universal glue every line starts with.

package/package.json

@@ -1,6 +1,19 @@
 {
   "name": "@mosetta/router",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.9",
+  "license": "MIT",
+  "description": "mosetta factory line protocol: the line instruction a factory line is built from, reserved module names, control headers and the universal glue.",
+  "type": "module",
+  "files": [
+    "src"
+  ],
+  "exports": {
+    "./core": "./src/core/core.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  }
 }

package/src/core/core.ts

@@ -0,0 +1,6 @@
+// @mosetta/router/core — the RUNNER's protocol with its isolates (ADR-0053: the router module is
+// gone, the name stays): the isolate instruction, the reserved names and headers, the store model
+// and the universal glue source.
+export * from './verdictTypes';
+export * from './stores';
+export * from './universalGlue';

package/src/core/stores.ts

@@ -0,0 +1,36 @@
+// The application's store model: JUST base URLs — symmetric public/private pairs,
+// one per provider plus the app's content pair (live pages + runtime files / drafts).
+// How the URLs relate to each other (same host, four buckets, whatever) is NOBODY's knowledge:
+// the model carries no origin identity. A provider's identity, where one is needed (an
+// instruction's `ref.provider`), is its publicBase. Zod/di-free — the runner's store resolution. Base URLs are not secrets; keys for private stores
+// live in the runner's registry only.
+
+export interface IStorePair {
+  publicBase: string;
+  privateBase: string;
+}
+
+// a provider's pair — same shape, kept as a named alias for the authoring surface
+export type IProviderStores = IStorePair;
+
+export interface IRouterStores {
+  // [0] is the app's primary provider (the app's own distribution)
+  providers: IProviderStores[];
+  content: IStorePair;
+}
+
+const withSlash = (u: string): string => (u.endsWith('/') ? u : `${u}/`);
+
+// CONFIG-LEVEL SUGAR for dev / small installs: one server serves all four stores under path
+// prefixes — this constructor is the only place that knows that. Everything downstream sees
+// four independent base URLs; prod registry entries are four explicit URLs and never call this.
+export function storesFromSingleOrigin(origin: string): IRouterStores {
+  if (!origin) {
+    return { providers: [], content: { publicBase: '', privateBase: '' } };
+  }
+  const base = withSlash(origin);
+  return {
+    providers: [{ publicBase: base, privateBase: `${base}private/` }],
+    content: { publicBase: `${base}__mosetta__/`, privateBase: `${base}__mosetta__/content/` },
+  };
+}

package/src/core/universalGlue.ts

@@ -0,0 +1,19 @@
+// THE universal glue: embedded in the RUNNER and composed as `index.js` with every
+// instruction's modules map — never fetched, never named in instructions. It can be this small because
+// every module kind carries its own aspect and DEFAULT-exports fetch; the only jobs
+// left are adapting that export to the Worker Loader entry shape and guarding the boundary:
+// whatever escapes the monolith becomes a loud 500 error JSON.
+export const UNIVERSAL_GLUE_SOURCE = `import module from './module.js';
+export default {
+  async fetch(request, env) {
+    try {
+      return await module.fetch(request, env);
+    } catch (e) {
+      return new Response(
+        JSON.stringify({ error: { code: 'ISOLATE_FAILED', message: String((e && e.message) || e) } }),
+        { status: 500, headers: { 'content-type': 'application/json; charset=utf-8' } },
+      );
+    }
+  },
+};
+`;

package/src/core/verdictTypes.ts

@@ -0,0 +1,97 @@
+// What the RUNNER composes an isolate from (ADR-0053: there is no router — the runner decides
+// where a request goes and builds these itself), and the words it exchanges with an isolate:
+// the reserved module names, the recomposition and hand-over headers, the env fields a site reads.
+
+// The four store kinds of an application. Physically four different base URLs in
+// prod (buckets/CDN); in dev one origin derives all four bases (storesFromSingleOrigin):
+//  - provider-public:    a provider's client statics (components, styles, images, public prefabs)
+//  - provider-private:   a provider's server-action monoliths (+ framework isolate entries)
+//  - content-public:     the app's live pages collection + the runtime files pages reference
+//                        (system.js, bootstrap.js)
+//  - content-private:    the app's drafts
+export type TStoreName = 'provider-public' | 'provider-private' | 'content-public' | 'content-private';
+
+// a store-qualified artifact reference: the RUNNER resolves it against its store registry (and
+// attaches credentials for private stores) — instructions never carry URLs or secrets
+export interface IArtifactRef {
+  store: TStoreName;
+  // which CODE SOURCE a provider-* ref is read from — a key of the runner's own registry;
+  // omitted → the host. A key the registry does not hold resolves to nothing.
+  provider?: string;
+  // STORE-relative path, never an absolute URL (the runner builds every ref itself)
+  path: string;
+  // the artifact's integrity as the catalog names it (`sha256-…`): the runner checks what it
+  // fetched against it — a CDN may still serve an older build under the same address
+  integrity?: string;
+}
+
+// the reserved entry key: the runner's UNIVERSAL glue imports './module.js' and calls its
+// `module.fetch` — every modules map MUST contain it. Glue itself is never named in instructions:
+// every module kind carries its own aspect and exposes fetch, so the glue never differs.
+export const ISOLATE_ENTRY_MODULE = 'module.js';
+
+// "compose an isolate and hand it the request"
+export interface ILineInstruction {
+  // isolate cache key; the runner prefixes it with the project/provider so ids never collide
+  cacheId: string;
+  // in-isolate module name → store-qualified artifact ref. Must contain ISOLATE_ENTRY_MODULE —
+  // the aspect-carrying entry. Sibling entries are importable inside the isolate by their map
+  // names: isolates cannot eval fetched code, so a multi-file composition (SSR: renderer + the
+  // page tree's server-built modules, each from its author's provider) can enter an isolate ONLY
+  // through this map. Today's strategies emit single-entry maps — monoliths are self-contained.
+  modules: Record<string, IArtifactRef>;
+  // modules the RUNNER writes itself (name → source), composed beside the fetched ones: data an
+  // isolate needs that is too large for its env (the catalog snapshot — CATALOG_MODULE)
+  sources?: Record<string, string>;
+  // becomes the target isolate's env. Created ONCE per cacheId — only isolate-level constants belong
+  // here (PROVIDER_ORIGIN, small flags); per-request variability travels in the request. A Dynamic
+  // Worker's env is capped at 1 MiB: anything that grows with the platform goes into `sources`.
+  data?: Record<string, unknown>;
+}
+
+/**
+ * A render that is NOT the page as published: it fell back to the empty shell, linked without a
+ * module it could not get, or shipped its head before its actions settled. Served to the reader
+ * (better than nothing) but never kept at the edge — the next request tries again. Set by the
+ * site isolate, read and removed by the runner.
+ */
+export const DEGRADED_HEADER = 'x-mosetta-degraded';
+
+/** the catalog snapshot of a site isolate, as a module beside the code (`export default [...]`) */
+export const CATALOG_MODULE = 'catalog.js';
+/** the env field naming that module */
+export const CATALOG_MODULE_ENV = 'CATALOG_MODULE';
+
+// Recomposition: the target isolate may answer NOT the client but the runner —
+// "recompose me with these extra modules". The response is marked by a header, the body is a
+// tar container: RECOMPOSE_MANIFEST_ENTRY ({ modules: [{entry, name, type}] }) + module
+// entries. The runner validates names/size, composes a NEW isolate (the static set + the
+// reported modules) and REPLAYS the original request. hop = 1: phase 2 cannot request a third
+// composition.
+export const RECOMPOSE_HEADER = 'x-mosetta-recompose';
+export const RECOMPOSE_MANIFEST_ENTRY = 'recompose.json';
+// marker of a REPLAYED request: the phase-2 isolate must use the reported modules and fail
+// clearly if they are missing — a second recompose request is forbidden (hop = 1)
+export const RECOMPOSED_HEADER = 'x-mosetta-recomposed';
+// Recomposition BY REFERENCE (ADR-0052): the site isolate answers the runner with the ids of the
+// catalog's modules it lacks for a page (JSON `{ ids }`), not with code — the runner takes them
+// from the public code store, composes the site anew with them and replays (hop = 1); it keeps
+// what was learned for the site until the code changes.
+export const RECOMPOSE_REFS_HEADER = 'x-mosetta-recompose-refs';
+/**
+ * The site's ENGINE is not the page's (ADR-0053): the page's root names another ssr facet. The
+ * site answers the runner with this header and the facet's id; the runner replays the request
+ * in the site of that engine (hop = 1) and remembers the address for it.
+ */
+export const SITE_ENGINE_HEADER = 'x-mosetta-site-engine';
+/** the env field a site isolate learns its own engine (the ssr facet it is composed with) from */
+export const SITE_ENGINE_ENV = 'SITE_ENGINE';
+/** the env field a site isolate learns its own map from: the module ids composed into it */
+export const COMPOSED_ENV = 'COMPOSED';
+/**
+ * The content's generation as the runner read it for THIS request (the marker every publish
+ * rewrites). A site isolate keeps what it read of the live site for as long as the generation
+ * stays the same, and drops it when another one arrives — the isolate itself lives on: it is
+ * named by its code and its set, not by the content (ADR-0053). Set by the runner only.
+ */
+export const CONTENT_GENERATION_HEADER = 'x-mosetta-content-generation';