@volter/world-core 2.0.0

package/dist/src/mirror-shell.d.ts

@@ -0,0 +1,2 @@
+/** The shell's HTML mounted at `base` (the twin's place, ending in '/'). */
+export declare function mirrorShellUnder(html: string, base: string): string;

package/dist/src/mirror-shell.js

@@ -0,0 +1,13 @@
+// A pack's mirror shell as a World serves it, at /<org>/<world>/<vendor>/mirror/ (the served World's
+// mount and the hosted supervisor's): its <base> becomes the twin's place under the World, so the
+// mirror's reads go to the World's wire; its assets stay under mirror/; and its own `#/` routes stay on
+// the shell. A mirror links its routes as href="#/…", which the browser resolves against <base> — the
+// twin's API path, not the shell — so a capture-phase handler moves the hash on the page instead.
+const HASH_LINKS = `<script>document.addEventListener('click',function(e){var a=e.target&&e.target.closest&&e.target.closest('a[href^="#"]');if(!a||e.defaultPrevented||e.button!==0||e.metaKey||e.ctrlKey||e.shiftKey||e.altKey)return;e.preventDefault();location.hash=a.getAttribute('href');},true);</script>`;
+/** The shell's HTML mounted at `base` (the twin's place, ending in '/'). */
+export function mirrorShellUnder(html, base) {
+    const mounted = html
+        .replace(/<base href="[^"]*">/, `<base href="${base}">`)
+        .replace(/(href|src)="assets\//g, '$1="mirror/assets/');
+    return mounted.includes('</head>') ? mounted.replace('</head>', `${HASH_LINKS}</head>`) : `${HASH_LINKS}${mounted}`;
+}

package/dist/src/observe.d.ts

@@ -0,0 +1,49 @@
+import { type SubjectFields } from './hash.js';
+export type ObservedResource = {
+    type: string;
+    id: string;
+    fields: SubjectFields;
+    deleted?: boolean;
+};
+export type ObserveReport = {
+    observed: number;
+    appended: number;
+    unchanged: number;
+    removed: number;
+};
+export type Observation = {
+    service: string;
+    root?: string;
+} & ({
+    resource: ObservedResource;
+} | {
+    resources: ObservedResource[];
+    complete?: string[];
+});
+/** Run `fn` with every `observeResource` inside it COLLECTED instead of folded; the caller folds the
+ *  batch (`observeResources`) once `fn` returns. The kernel's refresh does this around an adapter. */
+export declare function collectObservations<T>(fn: () => Promise<T>): Promise<{
+    value: T;
+    observations: Observation[];
+}>;
+/** Fold a collected batch: one `observeResources` per service, `complete` applied to each. */
+export declare function foldObservations(observations: Observation[], opts?: {
+    root?: string;
+    at?: string;
+    complete?: string[];
+    batch?: string;
+}): ObserveReport;
+/** One observed resource: collected when a refresh scope is open, else folded onto the root's log now. */
+export declare function observeResource(service: string, resource: ObservedResource, opts?: {
+    root?: string;
+    at?: string;
+}): ObserveReport;
+/** The fold: diff each resource against upstream state, append what changed to the root's log. `complete`
+ *  names the types this batch listed in full — a subject of such a type the batch does not hold is
+ *  tombstoned. Entry ids are content-addressed, so the same observation folds once. */
+export declare function observeResources(service: string, resources: ObservedResource[], opts?: {
+    root?: string;
+    at?: string;
+    complete?: string[];
+    batch?: string;
+}): ObserveReport;

package/dist/src/observe.js

@@ -0,0 +1,148 @@
+// OBSERVE — the kernel's fold for the second difference between simulated and real: how the tree
+// is kept current (company contract "Refresh is the kernel's fold", ruled 2026-09-06).
+//
+// A pack's refresh and ingest code hand the kernel RESOURCES, never rows. The kernel diffs each
+// against the upstream view and appends to the ROOT's log (the parent log — the vendor's history as
+// observed) only what changed: one entry per changed subject, carrying the changed fields; an
+// unchanged resource appends nothing; a listing the adapter declares complete tombstones what it
+// no longer holds. A refresh runs inside a scope that collects the adapter's observations and folds
+// them as one batch; an ingest observes directly, one resource at a time.
+import { withAncestryLock } from "./ancestry.js";
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { appendParentEntry, readParentTreeMap } from "./log.js";
+import { hashFieldValue } from "./hash.js";
+import { worldNow } from "./world-clock.js";
+// ONE sink per process, whichever copy of the kernel a pack resolved: a pack installed beside a
+// world carries its own `@volter/world-core`, and its observations must reach the scope the runtime
+// opened. A module-level instance would be one per copy; a process-global symbol is one per process.
+const SINK = Symbol.for('volter.observe.sink');
+// created on first use, never at import: a mirror's CLIENT bundle (target browser) carries this module
+// through the pack's shared helpers, and a browser has no AsyncLocalStorage — constructing one at load
+// would kill the whole client ("not a constructor") for a scope the browser never opens
+const sink = () => (globalThis[SINK] ??= new AsyncLocalStorage());
+/** Run `fn` with every `observeResource` inside it COLLECTED instead of folded; the caller folds the
+ *  batch (`observeResources`) once `fn` returns. The kernel's refresh does this around an adapter. */
+export async function collectObservations(fn) {
+    const observations = [];
+    const value = await sink().run(observations, fn);
+    return { value, observations };
+}
+/** Fold a collected batch: one `observeResources` per service, `complete` applied to each. */
+export function foldObservations(observations, opts = {}) {
+    const total = { observed: 0, appended: 0, unchanged: 0, removed: 0 };
+    const groups = new Map();
+    for (const o of observations) {
+        const root = opts.root ?? o.root;
+        const key = JSON.stringify([o.service, root]);
+        let group = groups.get(key);
+        if (!group) {
+            group = { service: o.service, root, resources: [], complete: new Set(opts.complete) };
+            groups.set(key, group);
+        }
+        if ('resource' in o)
+            group.resources.push(o.resource);
+        else
+            for (const resource of o.resources)
+                group.resources.push(resource);
+        if ('resources' in o)
+            for (const type of o.complete ?? [])
+                group.complete.add(type);
+    }
+    for (const { service, root, resources, complete } of groups.values()) {
+        const r = foldResources(service, resources, { ...opts, root, complete: [...complete] });
+        total.observed += r.observed;
+        total.appended += r.appended;
+        total.unchanged += r.unchanged;
+        total.removed += r.removed;
+    }
+    return total;
+}
+/** One observed resource: collected when a refresh scope is open, else folded onto the root's log now. */
+export function observeResource(service, resource, opts = {}) {
+    const collecting = typeof AsyncLocalStorage === 'function' ? sink().getStore() : undefined;
+    if (collecting) {
+        collecting.push({ service, resource, ...(opts.root !== undefined ? { root: opts.root } : {}) });
+        return { observed: 1, appended: 0, unchanged: 0, removed: 0 };
+    }
+    return observeResources(service, [resource], opts);
+}
+function stable(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'undefined';
+    if (Array.isArray(value))
+        return `[${value.map(stable).join(',')}]`;
+    const o = value;
+    return `{${Object.keys(o).sort().map((k) => `${JSON.stringify(k)}:${stable(o[k])}`).join(',')}}`;
+}
+/** The fold: diff each resource against upstream state, append what changed to the root's log. `complete`
+ *  names the types this batch listed in full — a subject of such a type the batch does not hold is
+ *  tombstoned. Entry ids are content-addressed, so the same observation folds once. */
+export function observeResources(service, resources, opts = {}) {
+    const collecting = typeof AsyncLocalStorage === 'function' ? sink().getStore() : undefined;
+    if (collecting) {
+        collecting.push({ service, resources, ...(opts.root !== undefined ? { root: opts.root } : {}), ...(opts.complete ? { complete: opts.complete } : {}) });
+        return { observed: resources.length, appended: 0, unchanged: 0, removed: 0 };
+    }
+    return foldResources(service, resources, opts);
+}
+function foldResources(service, resources, opts) {
+    return withAncestryLock(() => {
+        const at = opts.at ?? worldNow();
+        // one look is one batch: every entry it appends carries the same id, and no position may split it
+        const batch = opts.batch ?? `obs:${service}:${at}`;
+        const tree = readParentTreeMap(service, opts.root);
+        const report = { observed: resources.length, appended: 0, unchanged: 0, removed: 0 };
+        const seen = new Set();
+        const append = (subject, fields) => {
+            const entry = {
+                id: `observed:${service}:${subject.type}:${subject.id}:${hashFieldValue({ subject, fields, at })}`,
+                service, op: 'set', operation: 'observed', subject, occurredAt: at, actor: { kind: 'system', id: 'vendor' }, fields, batch,
+            };
+            const { appended } = appendParentEntry(entry, opts.root);
+            const key = `${subject.type}:${subject.id}`;
+            const existing = tree.get(key) ?? { type: subject.type, id: subject.id, updatedAt: at, fields: {} };
+            const merged = { ...existing.fields, ...fields };
+            if (existing.fields.deleted === true && fields.deleted !== true)
+                delete merged.deleted;
+            tree.set(key, { ...existing, updatedAt: at, fields: merged });
+            return appended;
+        };
+        for (const r of resources) {
+            const key = `${r.type}:${r.id}`;
+            seen.add(key);
+            const existing = tree.get(key);
+            if (r.deleted) {
+                if (existing && existing.fields.deleted !== true) {
+                    if (append({ type: r.type, id: r.id }, { deleted: true }))
+                        report.removed += 1;
+                }
+                else
+                    report.unchanged += 1;
+                continue;
+            }
+            const changed = {};
+            for (const [k, v] of Object.entries(r.fields))
+                if (v !== undefined && (existing === undefined || stable(existing.fields[k]) !== stable(v)))
+                    changed[k] = v;
+            if (Object.keys(changed).length === 0 && existing !== undefined && existing.fields.deleted !== true) {
+                report.unchanged += 1;
+                continue;
+            }
+            if (existing?.fields.deleted === true && Object.keys(changed).length === 0)
+                Object.assign(changed, r.fields); // resurrected as it stands
+            if (append({ type: r.type, id: r.id }, changed))
+                report.appended += 1;
+            else
+                report.unchanged += 1;
+        }
+        for (const type of opts.complete ?? []) {
+            for (const s of tree.values()) {
+                if (s.type !== type || seen.has(`${s.type}:${s.id}`) || s.fields.deleted === true)
+                    continue;
+                if (append({ type: s.type, id: s.id }, { deleted: true }))
+                    report.removed += 1;
+            }
+        }
+        return report;
+    });
+}

package/dist/src/pack-assets.d.ts

@@ -0,0 +1,30 @@
+export interface PackAssetStore {
+    /** The asset at `relPath` inside the pack `vendor`'s directory (e.g. `client/clerk.browser.js`),
+     *  as a Response carrying the bytes and a content type — or null when the pack ships no such
+     *  file. `relPath` is confined to the pack's own tree: a traversal never resolves. */
+    fetch(vendor: string, relPath: string): Promise<Response | null>;
+}
+export declare function assetContentType(relPath: string): string;
+/** A relative path confined to a pack's tree: no absolute, no `..`, no empty segment. */
+export declare function confinedAssetPath(relPath: string): string | null;
+/** The Bun shell's store: the pack's own directory under the catalog (`packages/twin/<vendor>`).
+ *  `twinDir` ends with a slash. */
+export declare class LocalPackAssets implements PackAssetStore {
+    private readonly twinDir;
+    constructor(twinDir: string);
+    fetch(vendor: string, relPath: string): Promise<Response | null>;
+}
+/** The workerd shell's store: the static-assets binding, where the deploy step places each
+ *  pack's declared assets under `/{vendor}/pack/<relPath>` beside the mirror shells. */
+export declare class BindingPackAssets implements PackAssetStore {
+    private readonly assets;
+    constructor(assets: {
+        fetch(request: Request): Promise<Response>;
+    });
+    fetch(vendor: string, relPath: string): Promise<Response | null>;
+}
+/** The bound store — the Bun shell's local tree unless a shell bound another. */
+export declare function getActivePackAssets(): PackAssetStore;
+export declare function setActivePackAssets(store: PackAssetStore): PackAssetStore | undefined;
+/** `getActivePackAssets().fetch(...)` with the pack's declared fallback: the first path that exists. */
+export declare function packAsset(vendor: string, ...candidates: string[]): Promise<Response | null>;

package/dist/src/pack-assets.js

@@ -0,0 +1,88 @@
+// THE PACK-ASSET SEAM (runtime contract R20). A pack may ship bytes it serves byte-for-byte —
+// clerk's vendored clerk-js dist (136 files, 14.5 MB), a mirror shell — that are neither
+// committed text (size) nor world-state blobs (R11's seam is keyed under a world's state root
+// and filled by requests). They are PACK assets: read-only, versioned with the package, the
+// same on every world. This seam is how a pack reaches them without touching a host: the
+// pack declares them on its descriptor (`assets`), reads them through `getActivePackAssets()`,
+// and the SHELL binds the store — the Bun shell reads the pack's own tree, workerd the
+// static-assets binding the mirror shells already deploy through. A pack that reads its tree
+// with Bun.file or import.meta is host-bound (R12b); one that reads through here is not.
+// No node builtins at module scope: `@volter/world-core`'s index re-exports this module and every mirror
+// client bundle (browser target) pulls the index in — a static `node:fs`/`node:url` import here
+// broke every mirror bundle the day the seam landed. The local store reads through Bun's file
+// API at call time; the worker store never touches a filesystem.
+import { existsSync, readFileSync, statSync } from 'node:fs';
+const CONTENT_TYPES = {
+    '.js': 'application/javascript; charset=utf-8', '.mjs': 'application/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8',
+    '.html': 'text/html; charset=utf-8', '.json': 'application/json; charset=utf-8', '.map': 'application/json; charset=utf-8',
+    '.svg': 'image/svg+xml', '.png': 'image/png', '.ico': 'image/x-icon', '.woff2': 'font/woff2', '.woff': 'font/woff', '.txt': 'text/plain; charset=utf-8',
+};
+export function assetContentType(relPath) {
+    const dot = relPath.lastIndexOf('.');
+    return (dot >= 0 ? CONTENT_TYPES[relPath.slice(dot)] : undefined) ?? 'application/octet-stream';
+}
+/** A relative path confined to a pack's tree: no absolute, no `..`, no empty segment. */
+export function confinedAssetPath(relPath) {
+    if (relPath.startsWith('/') || relPath.includes('\\') || relPath.includes('\0'))
+        return null;
+    const segs = relPath.split('/');
+    if (segs.some((s) => s === '' || s === '.' || s === '..'))
+        return null;
+    return segs.join('/');
+}
+/** The Bun shell's store: the pack's own directory under the catalog (`packages/twin/<vendor>`).
+ *  `twinDir` ends with a slash. */
+export class LocalPackAssets {
+    twinDir;
+    constructor(twinDir) {
+        this.twinDir = twinDir;
+    }
+    async fetch(vendor, relPath) {
+        const safe = confinedAssetPath(relPath);
+        if (safe === null || !/^[a-z][a-z0-9-]*$/.test(vendor))
+            return null;
+        const file = `${this.twinDir}${vendor}/${safe}`; // confined: no `..`, no absolute, no empty segment (above)
+        if (!existsSync(file) || !statSync(file).isFile())
+            return null;
+        return new Response(readFileSync(file), { status: 200, headers: { 'content-type': assetContentType(safe) } });
+    }
+}
+/** The workerd shell's store: the static-assets binding, where the deploy step places each
+ *  pack's declared assets under `/{vendor}/pack/<relPath>` beside the mirror shells. */
+export class BindingPackAssets {
+    assets;
+    constructor(assets) {
+        this.assets = assets;
+    }
+    async fetch(vendor, relPath) {
+        const safe = confinedAssetPath(relPath);
+        if (safe === null)
+            return null;
+        const res = await this.assets.fetch(new Request(`https://pack-assets/${vendor}/pack/${safe}`));
+        if (res.status !== 200)
+            return null;
+        return new Response(res.body, { status: 200, headers: { 'content-type': assetContentType(safe) } });
+    }
+}
+let active;
+/** The bound store — the Bun shell's local tree unless a shell bound another. */
+export function getActivePackAssets() {
+    if (active === undefined)
+        active = new LocalPackAssets(new URL('../../twin/', import.meta.url).pathname);
+    return active;
+}
+export function setActivePackAssets(store) {
+    const previous = active;
+    active = store;
+    return previous;
+}
+/** `getActivePackAssets().fetch(...)` with the pack's declared fallback: the first path that exists. */
+export async function packAsset(vendor, ...candidates) {
+    const store = getActivePackAssets();
+    for (const c of candidates) {
+        const r = await store.fetch(vendor, c);
+        if (r !== null)
+            return r;
+    }
+    return null;
+}