@volter/world-core 3.0.28 → 3.0.30

package/dist/src/actions.d.ts

@@ -167,7 +167,9 @@ export type AtomicActionDecision<T> = {
  * supplied snapshot. Durable state changes only through the returned action, which this helper
  * appends before releasing the lock.
  */
-export declare function decideAndAppendAction<T>(service: string, decide: (resources: TwinResource[]) => AtomicActionDecision<T>, root?: string): {
+export declare function decideAndAppendAction<T>(service: string, decide: (resources: TwinResource[]) => AtomicActionDecision<T>, root?: string, 
+/** A narrower indexed snapshot, read under the same lock; it must cover every decision and precondition. */
+read?: () => TwinResource[]): {
     value: T;
     action?: TwinAction;
     appended: boolean;

package/dist/src/actions.js

@@ -252,9 +252,11 @@ export function occurrenceId(base, ordinal) {
  * supplied snapshot. Durable state changes only through the returned action, which this helper
  * appends before releasing the lock.
  */
-export function decideAndAppendAction(service, decide, root) {
+export function decideAndAppendAction(service, decide, root, 
+/** A narrower indexed snapshot, read under the same lock; it must cover every decision and precondition. */
+read = () => projectResources(service, root)) {
     return withProjection(service, root, () => withFileLock(actionsLock(service, root), () => {
-        const resources = projectResources(service, root);
+        const resources = read();
         const decision = decide(resources);
         if (decision.kind === 'skip')
             return { value: decision.value, appended: false };

package/dist/src/browser-session-permit.d.ts

@@ -0,0 +1,13 @@
+export declare const BROWSER_SESSION_HEADER = "x-volter-browser-session-permit";
+export declare const BROWSER_SESSION_PATH = "/_twin/browser-session";
+export type BrowserSessionChoice = {
+    person: string | null;
+    land: string;
+    until: number;
+};
+/** No inbound route can supply the host's forwarding permit. Preserve streamed request bodies. */
+export declare function stripBrowserSessionPermit(request: Request): Request;
+/** Forward once with a secret permit; even a failed forward leaves no live permit behind. */
+export declare function withBrowserSessionPermit<T>(service: string, root: string, choice: BrowserSessionChoice, forward: (permit: string) => Promise<T>): Promise<T>;
+/** The twin takes the host's choice once, under the store's cross-process lock. No header alone grants it. */
+export declare function takeBrowserSessionPermit(request: Request, service: string, root?: string): BrowserSessionChoice | null;

package/dist/src/browser-session-permit.js

@@ -0,0 +1,51 @@
+// A host-only permission to change a browser session. Kept outside the twin's log and never sent to a browser.
+import { withHeaders } from "./with-headers.js";
+import { join } from 'node:path';
+import { getActiveWorldStore } from "./world-store.js";
+import { worldPaths } from "./storage.js";
+export const BROWSER_SESSION_HEADER = 'x-volter-browser-session-permit';
+export const BROWSER_SESSION_PATH = '/_twin/browser-session';
+const directory = (service, root) => join(worldPaths(service, root).dir, 'browser-session-permits');
+/** No inbound route can supply the host's forwarding permit. Preserve streamed request bodies. */
+export function stripBrowserSessionPermit(request) {
+    if (!request.headers.has(BROWSER_SESSION_HEADER))
+        return request;
+    const headers = new Headers(request.headers);
+    headers.delete(BROWSER_SESSION_HEADER);
+    return withHeaders(request, headers);
+}
+/** Forward once with a secret permit; even a failed forward leaves no live permit behind. */
+export async function withBrowserSessionPermit(service, root, choice, forward) {
+    const store = getActiveWorldStore();
+    const permit = Buffer.from(globalThis.crypto.getRandomValues(new Uint8Array(32))).toString('hex');
+    const path = join(directory(service, root), permit);
+    store.write(path, JSON.stringify(choice), { secret: true });
+    try {
+        return await forward(permit);
+    }
+    finally {
+        store.remove(path);
+    }
+}
+/** The twin takes the host's choice once, under the store's cross-process lock. No header alone grants it. */
+export function takeBrowserSessionPermit(request, service, root) {
+    const permit = request.headers.get(BROWSER_SESSION_HEADER);
+    if (!permit || !/^[0-9a-f]{64}$/.test(permit))
+        return null;
+    const store = getActiveWorldStore();
+    const dir = directory(service, root);
+    return store.withLock(`${dir}.lock`, () => {
+        const path = join(dir, permit);
+        const held = store.read(path);
+        if (held === null)
+            return null;
+        store.remove(path);
+        try {
+            const choice = JSON.parse(held);
+            return choice.until > Date.now() && (choice.person === null || typeof choice.person === 'string') && typeof choice.land === 'string' ? choice : null;
+        }
+        catch {
+            return null;
+        }
+    });
+}

package/dist/src/browser-session.d.ts

@@ -0,0 +1,9 @@
+import type { HandlerContext } from './derived-core.js';
+type Writer = Pick<HandlerContext, 'record' | 'secret' | 'occurredAt'>;
+/** The named cookie, without interpreting any other vendor's cookie. */
+export declare function browserSessionToken(request: Request, name: string): string | undefined;
+/** A new, independent sign-in, returning the cookie the vendor places on its response. */
+export declare function startBrowserSession(ctx: Writer, email: string, cookie: string, scope?: string): Promise<string>;
+/** End the session the request holds, then clear its cookie. Unknown cookies create no rows. */
+export declare function endBrowserSession(ctx: Pick<HandlerContext, 'call' | 'record' | 'rowsRaw' | 'occurredAt'>, cookie: string): Promise<string>;
+export {};

package/dist/src/browser-session.js

@@ -0,0 +1,30 @@
+/** The named cookie, without interpreting any other vendor's cookie. */
+export function browserSessionToken(request, name) {
+    for (const part of (request.headers.get('cookie') ?? '').split(';')) {
+        const at = part.indexOf('=');
+        if (at > 0 && part.slice(0, at).trim() === name) {
+            try {
+                return decodeURIComponent(part.slice(at + 1).trim());
+            }
+            catch {
+                return undefined;
+            }
+        }
+    }
+    return undefined;
+}
+/** A new, independent sign-in, returning the cookie the vendor places on its response. */
+export async function startBrowserSession(ctx, email, cookie, scope) {
+    const issued = await ctx.record('_web_session_issue', { email, ...(scope !== undefined ? { scope } : {}) });
+    const token = await ctx.secret(`web-session:${issued}`);
+    await ctx.record('_web_session', { token, email, ...(scope !== undefined ? { scope } : {}), created_at: ctx.occurredAt }, `websession:${token}`);
+    return `${cookie}=${token}; path=/; HttpOnly; Secure; SameSite=Lax`;
+}
+/** End the session the request holds, then clear its cookie. Unknown cookies create no rows. */
+export async function endBrowserSession(ctx, cookie) {
+    const token = browserSessionToken(ctx.call.request, cookie);
+    const session = token ? ctx.rowsRaw('_web_session').find((s) => s.token === token) : undefined;
+    if (session)
+        await ctx.record('_web_session', { token: null, ended_at: ctx.occurredAt }, String(session.id));
+    return `${cookie}=; path=/; Max-Age=0; HttpOnly; Secure; SameSite=Lax`;
+}

package/dist/src/derived-core.d.ts

@@ -268,6 +268,7 @@ export type VendorManifest = {
     descriptor: Omit<PackDescriptor, 'vendor'>;
     ingest?: IngestDecl;
     rateBudget?: RateBudgetDeclaration;
+    browserSession?: DerivedManifest['browserSession'];
     /** the vendor has no vendor-backed half (architecture, "The descriptor"): packOf copies it, and derives no state system */
     vendorBacked?: DerivedManifest['vendorBacked'];
 };
@@ -543,6 +544,11 @@ export type DerivedManifest = {
         owner: string;
         resource: string;
     }>;
+    /** The browser session of a World's person, issued with world-ui's kit. Declaring it lets the World offer View as. */
+    browserSession?: {
+        cookie: string;
+        scope?: string;
+    };
     /** the vendor's screens this pack serves or owes (demand decides which exist) */
     screens?: ScreenDecl[];
     /** The discovery door's facts (`GET /twin`): what the twin is of, what it stores, and how it is authenticated. */

package/dist/src/derived-core.js

@@ -1166,7 +1166,6 @@ export async function contextFor(m, call, scope) {
         body,
         text,
         root,
-        occurredAt: at,
         publicBase: twinPublicBase(call.request),
         scenario: scenarioDecisionOf(call.request),
         deliver: (url, init) => deliverToApplication(url, init),
@@ -1204,7 +1203,33 @@ export async function contextFor(m, call, scope) {
             }
             return id;
         },
+        occurredAt: at,
         secret: async (label) => hmac(await worldSeed(m.service, root, at), label, 'base64url'),
+        record: async (type, fields, id) => {
+            if (!type.startsWith('_'))
+                throw new Error(`semantics: ${type} is not a bookkeeping type (bookkeeping types start with _)`);
+            if (id !== undefined) {
+                await applyTwinWrite(m.service, { operation: `${type.slice(1)}.record`, subjectType: type, subjectId: id, fields, occurredAt: at, actor: { kind: 'system' } }, root);
+                return id;
+            }
+            const { value } = await applyTwinWriteAtomic(m.service, (resources) => {
+                // Allocate and append under the same state lock: concurrent sign-ins must never share an issue id.
+                const subject = (() => {
+                    const prefix = `${type.slice(1)}_`;
+                    let max = 0;
+                    for (const r of resources) {
+                        if (r.type !== type)
+                            continue;
+                        const n = r.id.startsWith(prefix) ? Number(r.id.slice(prefix.length)) : NaN;
+                        if (Number.isInteger(n) && n > max)
+                            max = n;
+                    }
+                    return `${prefix}${max + 1}`;
+                })();
+                return { kind: 'write', value: subject, write: { operation: `${type.slice(1)}.record`, subjectType: type, subjectId: subject, fields, occurredAt: at, actor: { kind: 'system' } } };
+            }, root, () => resourcesOfType(m.service, type, root));
+            return value;
+        },
         get machines() {
             const enrolled = resourcesOfType(m.service, MACHINE_POOL, root).find((r) => r.id === 'pool');
             return poolFor(m.service, root, enrolled?.kind ?? 'none');
@@ -1237,24 +1262,6 @@ export async function contextFor(m, call, scope) {
         rowsRaw: (resource, opts) => stored(m, resource, root, opts),
         tree: () => twinResources(m.service, root),
         history: (resource, id) => subjectHistory(m.service, { type: storedType(m, resource), id }, root).map((e) => ({ ...(e.operation ? { operation: e.operation } : {}), ...(e.fields ? { fields: e.fields } : {}), ...(e.occurredAt ? { occurredAt: e.occurredAt } : {}) })),
-        record: async (type, fields, id) => {
-            if (!type.startsWith('_'))
-                throw new Error(`semantics: ${type} is not a bookkeeping type (bookkeeping types start with _)`);
-            // an id the caller does not give is the next past every one of this type the tree holds (as `{n}` ids are minted),
-            // never a count of the rows, which a removed row would make repeat
-            const subject = id ?? (() => {
-                const prefix = `${type.slice(1)}_`;
-                let max = 0;
-                for (const r of resourcesOfType(m.service, type, root)) {
-                    const n = r.id.startsWith(prefix) ? Number(r.id.slice(prefix.length)) : NaN;
-                    if (Number.isInteger(n) && n > max)
-                        max = n;
-                }
-                return `${prefix}${max + 1}`;
-            })();
-            await applyTwinWrite(m.service, { operation: `${type.slice(1)}.record`, subjectType: type, subjectId: subject, fields, occurredAt: at, actor: { kind: 'system' } }, root);
-            return subject;
-        },
         raw: (body, init = {}) => new Response(body, { status: init.status ?? 200, headers: init.headers ?? {} }),
         atomically: async (decide) => {
             const { value } = await applyTwinWriteAtomic(m.service, (resources) => {

package/dist/src/index.d.ts

@@ -64,3 +64,4 @@ export * as redis from './redis/index.js';
 export * as git from './git/index.js';
 export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError } from './scenario.js';
 export type { PackScenarioAdapter, ScenarioDecision, ScenarioDocument, ScenarioExtractorSpec, ScenarioFault, ScenarioFaultResult, ScenarioFeatures, ScenarioHandler, ScenarioMatcher, ScenarioMissRecord, ScenarioStatus } from './scenario.js';
+export { browserSessionToken, startBrowserSession, endBrowserSession } from './browser-session.js';

package/dist/src/index.js

@@ -59,3 +59,4 @@ export * as redis from "./redis/index.js";
 export * as git from "./git/index.js";
 // ── the scenario grammar (architecture, "Behaviour") ───────────────────────────────────────────
 export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError } from "./scenario.js";
+export { browserSessionToken, startBrowserSession, endBrowserSession } from "./browser-session.js";

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

@@ -56,9 +56,12 @@ export type LanePart = {
     fetch: ((request: Request) => Promise<Response>) & {
         serves?: (method: string, path: string) => boolean;
         boards?: boolean;
+        drawsScreens?: boolean;
         draws?: (url: string) => boolean;
         /** the hosts the lane's built content screens name: its vendor's router sends `<base>/@<host>/` there */
         contentHosts?: ReadonlyArray<string>;
+        /** A vendor's browser session applies to its lanes without a lane importing its parent's manifest. */
+        sessionDeclaration?: (session: NonNullable<DerivedManifest['browserSession']>) => void;
     };
     manifest: {
         doors?: ReadonlyArray<{

package/dist/src/pack-fetch.js

@@ -5,6 +5,8 @@
 // `screens/<id>.tsx`), and the API (the derived dispatch over the generated surface, the handlers and the core). Every
 // one of them is answered over the contract's context, which the kernel opens: a pack opens none, reads the tree and
 // writes it only through one.
+import { startBrowserSession, endBrowserSession } from "./browser-session.js";
+import { BROWSER_SESSION_PATH, takeBrowserSessionPermit } from "./browser-session-permit.js";
 import { ORIGINAL_PATH_HEADER } from "./sigv4.js";
 import { placedCookies, TWIN_PREFIX_HEADER } from "./twin-fetch.js";
 import { PREFIX_PARAMS_HEADER } from "./derived.js";
@@ -110,6 +112,7 @@ async function encoded(m, request, res) {
 /** A pack's HTTP surface, as the kernel serves it from the pack's parts. */
 export function createPackFetch(parts, options = {}) {
     const m = parts.manifest;
+    let browserSession = m.browserSession;
     const scope = {
         ...(options.root !== undefined ? { root: options.root } : {}),
         ...(options.clock ? { clock: options.clock } : {}),
@@ -228,6 +231,7 @@ export function createPackFetch(parts, options = {}) {
         const hosts = [s.host, ...(s.hosts ?? [])].map(hostMatcher);
         return { root: s.path.replace(/\/+$/, '') === '', host: (h) => hosts.some((match) => match(h)), path: pathMatcher(s.path, true) };
     });
+    const drawsScreens = viewed.length > 0 || Object.values(parts.lanes ?? {}).some((l) => l.fetch.drawsScreens);
     const drawsUrl = (at) => {
         try {
             const u = new URL(at);
@@ -377,7 +381,7 @@ export function createPackFetch(parts, options = {}) {
         if (request.method === 'GET' && path === '/twin' && m.discovery) {
             const d = m.discovery;
             // the workspaces a person can be shown (Viewing a World): each built workspace screen's id and path
-            const shown = workspaces().length ? { screens: workspaces() } : {};
+            const shown = { drawsScreens, ...(workspaces().length ? { screens: workspaces() } : {}), ...(browserSession ? { browserSession } : {}) };
             // a model vendor's: its state, and what its scenario scripts, with the scenario's live counts
             if (parts.scenario && d.behavior) {
                 return Response.json({ ...shown, ...twinManifest({
@@ -395,6 +399,20 @@ export function createPackFetch(parts, options = {}) {
         // header would make a payout time makes the caller's), but a tenant's, when the vendor keeps tenants apart
         if (parts.clock)
             await runAsVendorMove(async () => parts.clock(await open(new Request(request.url, m.tenant ? { headers: request.headers } : {}), 'clock', 'POST', '/_twin/clock', {})));
+        if (path === BROWSER_SESSION_PATH && browserSession) {
+            if (request.method !== 'POST' || readOnly)
+                return Response.json({ error: 'a browser session needs a permitted write' }, { status: 403 });
+            const choice = takeBrowserSessionPermit(request, m.service, options.root);
+            if (!choice)
+                return Response.json({ error: 'only the World can change this browser session' }, { status: 403 });
+            const ctx = await open(request, 'browser-session', 'POST', BROWSER_SESSION_PATH, {});
+            const person = choice.person === null ? null : ctx.rowsRaw('_person').find((p) => p.id === choice.person && typeof p.email === 'string');
+            if (person === undefined)
+                return Response.json({ error: 'that person is no longer in the World' }, { status: 404 });
+            const cleared = await endBrowserSession(ctx, browserSession.cookie);
+            const cookie = person ? await startBrowserSession(ctx, String(person.email), browserSession.cookie, browserSession.scope) : cleared;
+            return new Response(null, { status: 303, headers: { location: choice.land, 'set-cookie': cookie } });
+        }
         if (path.startsWith('/_twin/')) {
             // the World's machine pool, enrolled by the kernel for a vendor that runs images (machines.ts)
             if (m.machines && path === '/_twin/machine-pool' && request.method === 'POST') {
@@ -513,7 +531,7 @@ export function createPackFetch(parts, options = {}) {
     async (asked) => engineOf()?.serve(asked)) : undefined;
     // what serves each operation: the pack's own, and each lane's
     const owners = () => ({ ...api.owners(), ...lanesOwners(parts.lanes ?? {}) });
-    return derivedRequestScopes(m, Object.assign(served, { owners, serves, workspaces, boards: Boolean(parts.board), draws: drawsUrl, contentHosts, ...(upgrade ? { upgrade } : {}) }));
+    return derivedRequestScopes(m, Object.assign(served, { sessionDeclaration: (session) => { browserSession ??= session; }, owners, serves, workspaces, boards: Boolean(parts.board), drawsScreens, draws: drawsUrl, contentHosts, ...(upgrade ? { upgrade } : {}) }));
 }
 /** The vendor's gateway over its lanes: the lane a request goes to (a door to the lane that declares it, then the first
  *  route whose conditions all hold, then the default), behind the gateway's CORS; undefined when none takes it. */
@@ -573,6 +591,9 @@ const lanesOwners = (lanes) => Object.assign({}, ...Object.values(lanes).map((l)
 /** The workspaces a vendor's lanes draw, as one list. */
 const lanesWorkspaces = (lanes) => Object.values(lanes).flatMap((l) => l.fetch.workspaces?.() ?? []);
 export function createVendorFetch(manifest, lanes) {
+    if (manifest.browserSession)
+        for (const part of Object.values(lanes))
+            part.fetch.sessionDeclaration?.(manifest.browserSession);
     const lane = laneRouter(manifest.vendor, manifest.lanes, lanes);
     return Object.assign(async (request) => {
         const path = new URL(request.url).pathname.replace(/\/+$/, '') || '/';
@@ -595,7 +616,7 @@ export function createVendorFetch(manifest, lanes) {
         if (request.method === 'GET' && path === '/twin' && manifest.discovery) {
             // the vendor's screens are its lanes' (a dashboard drawn by one lane is the vendor's)
             const screens = lanesWorkspaces(lanes);
-            return Response.json({ ...statefulTwinManifest({ vendor: manifest.vendor, ...manifest.discovery }), ...(screens.length ? { screens } : {}) });
+            return Response.json({ ...statefulTwinManifest({ vendor: manifest.vendor, ...manifest.discovery }), drawsScreens: Object.values(lanes).some((l) => l.fetch.drawsScreens), ...(manifest.browserSession ? { browserSession: manifest.browserSession } : {}), ...(screens.length ? { screens } : {}) });
         }
         const to = lane(request);
         return to ? to(request) : Response.json({ error: `${manifest.vendor}: no lane serves ${request.method} ${path}` }, { status: 404 });

package/dist/src/runtime.d.ts

@@ -4,7 +4,7 @@ export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioErr
 export { WORLD_CLOCK_ENV, worldNow } from './world-clock.js';
 export { WORLD_ENV_NAMES_ENV, worldEnvValue } from './world-env.js';
 export { ORIGINAL_PATH_HEADER } from './sigv4.js';
-export { createTwinFetchFromHandler, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, TWIN_SITES_HEADER, siteLabel, siteUrlOf, twinPublicBase, twinSiteUrl, withRequestScopes } from './twin-fetch.js';
+export { createTwinFetchFromHandler, placedCookies, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, TWIN_SITES_HEADER, siteLabel, siteUrlOf, twinPublicBase, twinSiteUrl, withRequestScopes } from './twin-fetch.js';
 export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, ReadOnlyRequestError, runAsReadOnlyRequest, runAsVendorMove, writesRefused } from './request-scope.js';
 export { compileSurface, createDerivedFetch, matchOperation } from './derived.js';
 export { currentTraceparent, deliveryTraceHeaders, newTraceparent, parseTraceparent, runWithRequestTrace, runWithTraceparent, TRACEPARENT_HEADER, traceparentForDelivery, validTraceparent } from './trace-context.js';
@@ -84,3 +84,4 @@ export { captureHistory, captureParentHistory, historyChanges, historyAtInstant,
 export type { HistoryView, HistoryLayout, HistoryReference, HistoryOrigin } from './history.js';
 export { foldHistory } from './log.js';
 export { volterHome } from './volter-home.js';
+export { BROWSER_SESSION_HEADER, BROWSER_SESSION_PATH, stripBrowserSessionPermit, withBrowserSessionPermit } from './browser-session-permit.js';

package/dist/src/runtime.js

@@ -12,7 +12,7 @@ export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioErr
 export { WORLD_CLOCK_ENV, worldNow } from "./world-clock.js";
 export { WORLD_ENV_NAMES_ENV, worldEnvValue } from "./world-env.js";
 export { ORIGINAL_PATH_HEADER } from "./sigv4.js";
-export { createTwinFetchFromHandler, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, TWIN_SITES_HEADER, siteLabel, siteUrlOf, twinPublicBase, twinSiteUrl, withRequestScopes } from "./twin-fetch.js";
+export { createTwinFetchFromHandler, placedCookies, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, TWIN_SITES_HEADER, siteLabel, siteUrlOf, twinPublicBase, twinSiteUrl, withRequestScopes } from "./twin-fetch.js";
 export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, ReadOnlyRequestError, runAsReadOnlyRequest, runAsVendorMove, writesRefused } from "./request-scope.js";
 export { compileSurface, createDerivedFetch, matchOperation } from "./derived.js";
 export { currentTraceparent, deliveryTraceHeaders, newTraceparent, parseTraceparent, runWithRequestTrace, runWithTraceparent, TRACEPARENT_HEADER, traceparentForDelivery, validTraceparent } from "./trace-context.js";
@@ -103,3 +103,4 @@ export { assertStateRemovable, checkParent, stateGeneration, withAncestryLock, w
 export { captureHistory, captureParentHistory, historyChanges, historyAtInstant, historyDigest, historyEntries, historyLength, historyPrefix, inheritedHistory, originHead, publishOriginHistory, readHistoryView } from "./history.js";
 export { foldHistory } from "./log.js";
 export { volterHome } from "./volter-home.js";
+export { BROWSER_SESSION_HEADER, BROWSER_SESSION_PATH, stripBrowserSessionPermit, withBrowserSessionPermit } from "./browser-session-permit.js";

package/dist/src/serve.d.ts

@@ -168,7 +168,9 @@ export declare function recordedInput(input: unknown): Promise<unknown>;
  * Use this when acceptance or the new fields depend on current projected state; a caller-side
  * read followed by `applyTwinWrite` is not atomic across processes.
  */
-export declare function applyTwinWriteAtomic<T>(service: string, prepare: (resources: readonly TwinResource[]) => AtomicTwinWriteDecision<T>, root?: string): Promise<{
+export declare function applyTwinWriteAtomic<T>(service: string, prepare: (resources: readonly TwinResource[]) => AtomicTwinWriteDecision<T>, root?: string, 
+/** A type index when the decision and its preconditions need only that type, read inside the state lock. */
+read?: () => TwinResource[]): Promise<{
     value: T;
     result?: TwinWriteResult;
 }>;

package/dist/src/serve.js

@@ -498,7 +498,9 @@ function actionForTwinWrite(service, write) {
  * Use this when acceptance or the new fields depend on current projected state; a caller-side
  * read followed by `applyTwinWrite` is not atomic across processes.
  */
-export async function applyTwinWriteAtomic(service, prepare, root) {
+export async function applyTwinWriteAtomic(service, prepare, root, 
+/** A type index when the decision and its preconditions need only that type, read inside the state lock. */
+read) {
     // Same ruling as applyTwinWrite: a local write is an OCCURRENCE unless the caller supplied
     // identity. The mode rides on the decision because only the callback knows which write it chose.
     const committed = decideAndAppendAction(service, (resources) => {
@@ -511,7 +513,7 @@ export async function applyTwinWriteAtomic(service, prepare, root) {
             action: actionForTwinWrite(service, decision.write),
             identity: decision.write.idempotencyKey || decision.write.actionId ? 'caller' : 'occurrence',
         };
-    }, root);
+    }, root, read);
     // as applyTwinWrite: a seed's write is the placeholder's default data, never performed
     const head = committed.action && committed.appended && !committed.placeholder ? await performAtHead(service, committed.action, root) : { performed: false };
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-core",
-  "version": "3.0.28",
+  "version": "3.0.30",
   "description": "The kernel of Volter World: one log per twin, branches as pointers, checkpoints, the fold that keeps a twin current, the head that performs a write against the vendor, references, and the git plane. A twin package builds on it; the runtime serves it.",
   "keywords": [
     "twin",

package/src/actions.ts

@@ -361,9 +361,11 @@ export function decideAndAppendAction<T>(
   service: string,
   decide: (resources: TwinResource[]) => AtomicActionDecision<T>,
   root?: string,
+  /** A narrower indexed snapshot, read under the same lock; it must cover every decision and precondition. */
+  read: () => TwinResource[] = () => projectResources(service, root),
 ): { value: T; action?: TwinAction; appended: boolean; placeholder?: true } {
   return withProjection(service, root, () => withFileLock(actionsLock(service, root), () => {
-    const resources = projectResources(service, root);
+    const resources = read();
     const decision = decide(resources);
     if (decision.kind === 'skip') return { value: decision.value, appended: false };
     refuseReadOnlyWrite(service); // a decision to write is the write a read-only request may not make

package/src/browser-session-permit.ts

@@ -0,0 +1,43 @@
+// A host-only permission to change a browser session. Kept outside the twin's log and never sent to a browser.
+import { withHeaders } from './with-headers.ts';
+import { join } from 'node:path';
+import { getActiveWorldStore } from './world-store.ts';
+import { worldPaths } from './storage.ts';
+
+export const BROWSER_SESSION_HEADER = 'x-volter-browser-session-permit';
+export const BROWSER_SESSION_PATH = '/_twin/browser-session';
+export type BrowserSessionChoice = { person: string | null; land: string; until: number };
+const directory = (service: string, root?: string): string => join(worldPaths(service, root).dir, 'browser-session-permits');
+
+/** No inbound route can supply the host's forwarding permit. Preserve streamed request bodies. */
+export function stripBrowserSessionPermit(request: Request): Request {
+  if (!request.headers.has(BROWSER_SESSION_HEADER)) return request;
+  const headers = new Headers(request.headers);
+  headers.delete(BROWSER_SESSION_HEADER);
+  return withHeaders(request, headers);
+}
+
+/** Forward once with a secret permit; even a failed forward leaves no live permit behind. */
+export async function withBrowserSessionPermit<T>(service: string, root: string, choice: BrowserSessionChoice, forward: (permit: string) => Promise<T>): Promise<T> {
+  const store = getActiveWorldStore();
+  const permit = Buffer.from(globalThis.crypto.getRandomValues(new Uint8Array(32))).toString('hex');
+  const path = join(directory(service, root), permit);
+  store.write(path, JSON.stringify(choice), { secret: true });
+  try { return await forward(permit); } finally { store.remove(path); }
+}
+
+/** The twin takes the host's choice once, under the store's cross-process lock. No header alone grants it. */
+export function takeBrowserSessionPermit(request: Request, service: string, root?: string): BrowserSessionChoice | null {
+  const permit = request.headers.get(BROWSER_SESSION_HEADER);
+  if (!permit || !/^[0-9a-f]{64}$/.test(permit)) return null;
+  const store = getActiveWorldStore(); const dir = directory(service, root);
+  return store.withLock(`${dir}.lock`, () => {
+    const path = join(dir, permit); const held = store.read(path);
+    if (held === null) return null;
+    store.remove(path);
+    try {
+      const choice = JSON.parse(held) as BrowserSessionChoice;
+      return choice.until > Date.now() && (choice.person === null || typeof choice.person === 'string') && typeof choice.land === 'string' ? choice : null;
+    } catch { return null; }
+  });
+}

package/src/browser-session.ts

@@ -0,0 +1,31 @@
+// A vendor's browser session: the bookkeeping used by its sign-in page and the World's View as door.
+import type { HandlerContext } from './derived-core.ts';
+
+type Writer = Pick<HandlerContext, 'record' | 'secret' | 'occurredAt'>;
+
+/** The named cookie, without interpreting any other vendor's cookie. */
+export function browserSessionToken(request: Request, name: string): string | undefined {
+  for (const part of (request.headers.get('cookie') ?? '').split(';')) {
+    const at = part.indexOf('=');
+    if (at > 0 && part.slice(0, at).trim() === name) {
+      try { return decodeURIComponent(part.slice(at + 1).trim()); } catch { return undefined; }
+    }
+  }
+  return undefined;
+}
+
+/** A new, independent sign-in, returning the cookie the vendor places on its response. */
+export async function startBrowserSession(ctx: Writer, email: string, cookie: string, scope?: string): Promise<string> {
+  const issued = await ctx.record('_web_session_issue', { email, ...(scope !== undefined ? { scope } : {}) });
+  const token = await ctx.secret(`web-session:${issued}`);
+  await ctx.record('_web_session', { token, email, ...(scope !== undefined ? { scope } : {}), created_at: ctx.occurredAt }, `websession:${token}`);
+  return `${cookie}=${token}; path=/; HttpOnly; Secure; SameSite=Lax`;
+}
+
+/** End the session the request holds, then clear its cookie. Unknown cookies create no rows. */
+export async function endBrowserSession(ctx: Pick<HandlerContext, 'call' | 'record' | 'rowsRaw' | 'occurredAt'>, cookie: string): Promise<string> {
+  const token = browserSessionToken(ctx.call.request, cookie);
+  const session = token ? ctx.rowsRaw('_web_session').find((s) => s.token === token) : undefined;
+  if (session) await ctx.record('_web_session', { token: null, ended_at: ctx.occurredAt }, String(session.id));
+  return `${cookie}=; path=/; Max-Age=0; HttpOnly; Secure; SameSite=Lax`;
+}

package/src/derived-core.ts

@@ -214,7 +214,7 @@ export type LaneRoute = {
 export type LanesDecl = { cors?: CorsDecl; routes: ReadonlyArray<LaneRoute>; default?: string };
 /** The manifest of a vendor whose every API is a lane (Cloudflare's API v4 and R2, AWS's services): no API of its own,
  *  only what the vendor's front says — its discovery facts, its lanes and its descriptor. */
-export type VendorManifest = { vendor: string; discovery?: DerivedManifest['discovery']; lanes: LanesDecl; descriptor: Omit<PackDescriptor, 'vendor'>; ingest?: IngestDecl; rateBudget?: RateBudgetDeclaration;
+export type VendorManifest = { vendor: string; discovery?: DerivedManifest['discovery']; lanes: LanesDecl; descriptor: Omit<PackDescriptor, 'vendor'>; ingest?: IngestDecl; rateBudget?: RateBudgetDeclaration; browserSession?: DerivedManifest['browserSession'];
   /** the vendor has no vendor-backed half (architecture, "The descriptor"): packOf copies it, and derives no state system */
   vendorBacked?: DerivedManifest['vendorBacked'] };
 
@@ -395,6 +395,8 @@ export type DerivedManifest = {
   resources: Record<string, ResourceDecl>;
   /** Read-only cross-pack credential subjects of the same vendor (architecture A3); no root is exposed to handlers. */
   ownerReads?: ReadonlyArray<{ owner: string; resource: string }>;
+  /** The browser session of a World's person, issued with world-ui's kit. Declaring it lets the World offer View as. */
+  browserSession?: { cookie: string; scope?: string };
   /** the vendor's screens this pack serves or owes (demand decides which exist) */
   screens?: ScreenDecl[];
   /** The discovery door's facts (`GET /twin`): what the twin is of, what it stores, and how it is authenticated. */
@@ -1702,7 +1704,6 @@ export async function contextFor(m: DerivedManifest, call: DerivedCall, scope: C
     body,
     text,
     root,
-    occurredAt: at,
     publicBase: twinPublicBase(call.request),
     scenario: scenarioDecisionOf(call.request),
     deliver: (url, init) => deliverToApplication(url, init),
@@ -1737,7 +1738,30 @@ export async function contextFor(m: DerivedManifest, call: DerivedCall, scope: C
       }
       return id;
     },
+    occurredAt: at,
     secret: async (label) => hmac(await worldSeed(m.service, root, at), label, 'base64url'),
+    record: async (type, fields, id) => {
+      if (!type.startsWith('_')) throw new Error(`semantics: ${type} is not a bookkeeping type (bookkeeping types start with _)`);
+      if (id !== undefined) {
+        await applyTwinWrite(m.service, { operation: `${type.slice(1)}.record`, subjectType: type, subjectId: id, fields, occurredAt: at, actor: { kind: 'system' } }, root);
+        return id;
+      }
+      const { value } = await applyTwinWriteAtomic(m.service, (resources) => {
+        // Allocate and append under the same state lock: concurrent sign-ins must never share an issue id.
+        const subject = (() => {
+          const prefix = `${type.slice(1)}_`;
+          let max = 0;
+          for (const r of resources) {
+            if (r.type !== type) continue;
+            const n = r.id.startsWith(prefix) ? Number(r.id.slice(prefix.length)) : NaN;
+            if (Number.isInteger(n) && n > max) max = n;
+          }
+          return `${prefix}${max + 1}`;
+        })();
+        return { kind: 'write', value: subject, write: { operation: `${type.slice(1)}.record`, subjectType: type, subjectId: subject, fields, occurredAt: at, actor: { kind: 'system' } } };
+      }, root, () => resourcesOfType(m.service, type, root));
+      return value;
+    },
     get machines() {
       const enrolled = resourcesOfType(m.service, MACHINE_POOL, root).find((r) => r.id === 'pool') as unknown as { kind?: MachinePool['kind'] } | undefined;
       return poolFor(m.service, root, enrolled?.kind ?? 'none');
@@ -1767,19 +1791,6 @@ export async function contextFor(m: DerivedManifest, call: DerivedCall, scope: C
     rowsRaw: (resource, opts) => stored(m, resource, root, opts) as Array<Record<string, unknown>>,
     tree: () => twinResources(m.service, root) as Array<Record<string, unknown>>,
     history: (resource, id) => subjectHistory(m.service, { type: storedType(m, resource), id }, root).map((e) => ({ ...(e.operation ? { operation: e.operation } : {}), ...(e.fields ? { fields: e.fields as Record<string, unknown> } : {}), ...(e.occurredAt ? { occurredAt: e.occurredAt } : {}) })),
-    record: async (type, fields, id) => {
-      if (!type.startsWith('_')) throw new Error(`semantics: ${type} is not a bookkeeping type (bookkeeping types start with _)`);
-      // an id the caller does not give is the next past every one of this type the tree holds (as `{n}` ids are minted),
-      // never a count of the rows, which a removed row would make repeat
-      const subject = id ?? (() => {
-        const prefix = `${type.slice(1)}_`;
-        let max = 0;
-        for (const r of resourcesOfType(m.service, type, root)) { const n = r.id.startsWith(prefix) ? Number(r.id.slice(prefix.length)) : NaN; if (Number.isInteger(n) && n > max) max = n; }
-        return `${prefix}${max + 1}`;
-      })();
-      await applyTwinWrite(m.service, { operation: `${type.slice(1)}.record`, subjectType: type, subjectId: subject, fields, occurredAt: at, actor: { kind: 'system' } }, root);
-      return subject;
-    },
     raw: (body, init = {}) => new Response(body, { status: init.status ?? 200, headers: init.headers ?? {} }),
     atomically: async (decide) => {
       const { value } = await applyTwinWriteAtomic(

package/src/index.ts

@@ -89,3 +89,5 @@ export * as git from './git/index.ts';
 // ── the scenario grammar (architecture, "Behaviour") ───────────────────────────────────────────
 export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError } from './scenario.ts';
 export type { PackScenarioAdapter, ScenarioDecision, ScenarioDocument, ScenarioExtractorSpec, ScenarioFault, ScenarioFaultResult, ScenarioFeatures, ScenarioHandler, ScenarioMatcher, ScenarioMissRecord, ScenarioStatus } from './scenario.ts';
+
+export { browserSessionToken, startBrowserSession, endBrowserSession } from './browser-session.ts';

package/src/pack-fetch.ts

@@ -5,6 +5,8 @@
 // `screens/<id>.tsx`), and the API (the derived dispatch over the generated surface, the handlers and the core). Every
 // one of them is answered over the contract's context, which the kernel opens: a pack opens none, reads the tree and
 // writes it only through one.
+import { startBrowserSession, endBrowserSession } from './browser-session.ts';
+import { BROWSER_SESSION_PATH, takeBrowserSessionPermit } from './browser-session-permit.ts';
 import { ORIGINAL_PATH_HEADER } from './sigv4.ts';
 import { placedCookies, TWIN_PREFIX_HEADER } from './twin-fetch.ts';
 import { PREFIX_PARAMS_HEADER } from './derived.ts';
@@ -77,9 +79,11 @@ export type PackScenario<Req = any> = { adapter: PackScenarioAdapter<Req>; opera
 /** A lane as its vendor's fetch is given it: its own pack fetch, and its manifest (the doors it declares). */
 export type LanePart = {
   fetch: ((request: Request) => Promise<Response>) & {
-    serves?: (method: string, path: string) => boolean; boards?: boolean; draws?: (url: string) => boolean;
+    serves?: (method: string, path: string) => boolean; boards?: boolean; drawsScreens?: boolean; draws?: (url: string) => boolean;
     /** the hosts the lane's built content screens name: its vendor's router sends `<base>/@<host>/` there */
     contentHosts?: ReadonlyArray<string>;
+    /** A vendor's browser session applies to its lanes without a lane importing its parent's manifest. */
+    sessionDeclaration?: (session: NonNullable<DerivedManifest['browserSession']>) => void;
   };
   manifest: { doors?: ReadonlyArray<{ method: string; path: string }> };
 };
@@ -173,6 +177,7 @@ async function encoded(m: DerivedManifest, request: Request, res: Response): Pro
 /** A pack's HTTP surface, as the kernel serves it from the pack's parts. */
 export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}): DerivedFetch {
   const m = parts.manifest;
+  let browserSession = m.browserSession;
   const scope: CoreScope = {
     ...(options.root !== undefined ? { root: options.root } : {}),
     ...(options.clock ? { clock: options.clock } : {}),
@@ -278,6 +283,7 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     const hosts = [s.host, ...(s.hosts ?? [])].map(hostMatcher);
     return { root: s.path.replace(/\/+$/, '') === '', host: (h: string) => hosts.some((match) => match(h)), path: pathMatcher(s.path, true) };
   });
+  const drawsScreens = viewed.length > 0 || Object.values(parts.lanes ?? {}).some((l) => l.fetch.drawsScreens);
   const drawsUrl = (at: string): boolean => {
     try {
       const u = new URL(at); const path = u.pathname.replace(/\/+$/, '') || '/';
@@ -406,7 +412,7 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     if (request.method === 'GET' && path === '/twin' && m.discovery) {
       const d = m.discovery;
       // the workspaces a person can be shown (Viewing a World): each built workspace screen's id and path
-      const shown = workspaces().length ? { screens: workspaces() } : {};
+      const shown = { drawsScreens, ...(workspaces().length ? { screens: workspaces() } : {}), ...(browserSession ? { browserSession } : {}) };
       // a model vendor's: its state, and what its scenario scripts, with the scenario's live counts
       if (parts.scenario && d.behavior) {
         return Response.json({ ...shown, ...twinManifest({
@@ -422,6 +428,17 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     // the vendor's own moves, not the caller's: its context carries none of the request's headers (a Stripe-Account
     // header would make a payout time makes the caller's), but a tenant's, when the vendor keeps tenants apart
     if (parts.clock) await runAsVendorMove(async () => parts.clock!(await open(new Request(request.url, m.tenant ? { headers: request.headers } : {}), 'clock', 'POST', '/_twin/clock', {})));
+    if (path === BROWSER_SESSION_PATH && browserSession) {
+      if (request.method !== 'POST' || readOnly) return Response.json({ error: 'a browser session needs a permitted write' }, { status: 403 });
+      const choice = takeBrowserSessionPermit(request, m.service, options.root);
+      if (!choice) return Response.json({ error: 'only the World can change this browser session' }, { status: 403 });
+      const ctx = await open(request, 'browser-session', 'POST', BROWSER_SESSION_PATH, {});
+      const person = choice.person === null ? null : ctx.rowsRaw('_person').find((p) => p.id === choice.person && typeof p.email === 'string');
+      if (person === undefined) return Response.json({ error: 'that person is no longer in the World' }, { status: 404 });
+      const cleared = await endBrowserSession(ctx, browserSession.cookie);
+      const cookie = person ? await startBrowserSession(ctx, String(person.email), browserSession.cookie, browserSession.scope) : cleared;
+      return new Response(null, { status: 303, headers: { location: choice.land, 'set-cookie': cookie } });
+    }
     if (path.startsWith('/_twin/')) {
       // the World's machine pool, enrolled by the kernel for a vendor that runs images (machines.ts)
       if (m.machines && path === '/_twin/machine-pool' && request.method === 'POST') {
@@ -519,7 +536,7 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     async (asked) => engineOf()?.serve(asked)) : undefined;
   // what serves each operation: the pack's own, and each lane's
   const owners = (): Record<string, DerivedOwner> => ({ ...api.owners(), ...lanesOwners(parts.lanes ?? {}) });
-  return derivedRequestScopes(m, Object.assign(served, { owners, serves, workspaces, boards: Boolean(parts.board), draws: drawsUrl, contentHosts, ...(upgrade ? { upgrade } : {}) }));
+  return derivedRequestScopes(m, Object.assign(served, { sessionDeclaration: (session: NonNullable<DerivedManifest['browserSession']>) => { browserSession ??= session; }, owners, serves, workspaces, boards: Boolean(parts.board), drawsScreens, draws: drawsUrl, contentHosts, ...(upgrade ? { upgrade } : {}) }));
 }
 
 /** The vendor's gateway over its lanes: the lane a request goes to (a door to the lane that declares it, then the first
@@ -583,6 +600,7 @@ const lanesWorkspaces = (lanes: Record<string, LanePart>): Workspace[] =>
   Object.values(lanes).flatMap((l) => (l.fetch as { workspaces?: () => Workspace[] }).workspaces?.() ?? []);
 
 export function createVendorFetch(manifest: VendorManifest, lanes: Record<string, LanePart>): ((request: Request) => Promise<Response>) & { owners: () => Record<string, DerivedOwner>; workspaces: () => Workspace[] } {
+  if (manifest.browserSession) for (const part of Object.values(lanes)) part.fetch.sessionDeclaration?.(manifest.browserSession);
   const lane = laneRouter(manifest.vendor, manifest.lanes, lanes);
   return Object.assign(async (request: Request): Promise<Response> => {
     const path = new URL(request.url).pathname.replace(/\/+$/, '') || '/';
@@ -602,7 +620,7 @@ export function createVendorFetch(manifest: VendorManifest, lanes: Record<string
     if (request.method === 'GET' && path === '/twin' && manifest.discovery) {
       // the vendor's screens are its lanes' (a dashboard drawn by one lane is the vendor's)
       const screens = lanesWorkspaces(lanes);
-      return Response.json({ ...statefulTwinManifest({ vendor: manifest.vendor, ...manifest.discovery }), ...(screens.length ? { screens } : {}) });
+      return Response.json({ ...statefulTwinManifest({ vendor: manifest.vendor, ...manifest.discovery }), drawsScreens: Object.values(lanes).some((l) => l.fetch.drawsScreens), ...(manifest.browserSession ? { browserSession: manifest.browserSession } : {}), ...(screens.length ? { screens } : {}) });
     }
     const to = lane(request);
     return to ? to(request) : Response.json({ error: `${manifest.vendor}: no lane serves ${request.method} ${path}` }, { status: 404 });

package/src/runtime.ts

@@ -13,7 +13,7 @@ export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioErr
 export { WORLD_CLOCK_ENV, worldNow } from './world-clock.ts';
 export { WORLD_ENV_NAMES_ENV, worldEnvValue } from './world-env.ts';
 export { ORIGINAL_PATH_HEADER } from './sigv4.ts';
-export { createTwinFetchFromHandler, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, TWIN_SITES_HEADER, siteLabel, siteUrlOf, twinPublicBase, twinSiteUrl, withRequestScopes } from './twin-fetch.ts';
+export { createTwinFetchFromHandler, placedCookies, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, TWIN_SITES_HEADER, siteLabel, siteUrlOf, twinPublicBase, twinSiteUrl, withRequestScopes } from './twin-fetch.ts';
 export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, ReadOnlyRequestError, runAsReadOnlyRequest, runAsVendorMove, writesRefused } from './request-scope.ts';
 export { compileSurface, createDerivedFetch, matchOperation } from './derived.ts';
 export { currentTraceparent, deliveryTraceHeaders, newTraceparent, parseTraceparent, runWithRequestTrace, runWithTraceparent, TRACEPARENT_HEADER, traceparentForDelivery, validTraceparent } from './trace-context.ts';
@@ -343,3 +343,5 @@ export { captureHistory, captureParentHistory, historyChanges, historyAtInstant,
 export type { HistoryView, HistoryLayout, HistoryReference, HistoryOrigin } from './history.ts';
 export { foldHistory } from './log.ts';
 export { volterHome } from './volter-home.ts';
+
+export { BROWSER_SESSION_HEADER, BROWSER_SESSION_PATH, stripBrowserSessionPermit, withBrowserSessionPermit } from './browser-session-permit.ts';

package/src/serve.ts

@@ -594,6 +594,8 @@ export async function applyTwinWriteAtomic<T>(
   service: string,
   prepare: (resources: readonly TwinResource[]) => AtomicTwinWriteDecision<T>,
   root?: string,
+  /** A type index when the decision and its preconditions need only that type, read inside the state lock. */
+  read?: () => TwinResource[],
 ): Promise<{ value: T; result?: TwinWriteResult }> {
   // Same ruling as applyTwinWrite: a local write is an OCCURRENCE unless the caller supplied
   // identity. The mode rides on the decision because only the callback knows which write it chose.
@@ -606,7 +608,7 @@ export async function applyTwinWriteAtomic<T>(
       action: actionForTwinWrite(service, decision.write),
       identity: decision.write.idempotencyKey || decision.write.actionId ? 'caller' : 'occurrence',
     };
-  }, root);
+  }, root, read);
   // as applyTwinWrite: a seed's write is the placeholder's default data, never performed
   const head = committed.action && committed.appended && !committed.placeholder ? await performAtHead(service, committed.action, root) : { performed: false };
   return {