@volter/world-core 3.0.9 → 3.0.11

package/dist/src/derived.d.ts

@@ -113,11 +113,41 @@ export type DerivedFetch = ((request: Request) => Promise<Response>) & {
     upgrade?: WebSocketUpgrade;
     /** The workspace screens it draws, its lanes' too (`GET /twin`'s `screens`). */
     workspaces?(): Workspace[];
+    /** Whether it lays out frames of the World's board (`semantics/board.ts`). */
+    boards?: boolean;
+    /** Whether a built screen of it takes a URL: a board frame it draws. */
+    draws?(url: string): boolean;
 };
 /** A workspace screen a pack draws, as `GET /twin` lists it: its id and path (Viewing a World). */
 export type Workspace = {
     id: string;
     path: string;
 };
+/** A frame of the World's board (architecture, "The board"): one thing of the vendor's where a person sees it, as the
+ *  vendor's pack lays out its default board (`semantics/board.ts`), the editorial choice of which views of the vendor a
+ *  person keeps open (a Worker's site, a repository's page, a Jira board). `GET /twin/board` lists them. */
+export type BoardFrame = {
+    /** stable within the vendor, whatever the World's ids: what a saved board names the frame by */
+    id: string;
+    /** what it is, in the vendor's own word (a site, a repository, a board) */
+    kind: string;
+    title: string;
+    /** the vendor's container it is grouped under (an account, an organization, a project); `aka`, the ids it was known
+     *  by before (an account a deploy adopted), so a board that included it under one still holds it */
+    section: {
+        id: string;
+        title: string;
+        aka?: string[];
+    };
+    /** where the vendor shows it: an absolute URL on the vendor's host, or on a hostname the vendor serves for its customer */
+    url: string;
+    /** the records whose changes are this frame's changes */
+    covers: Array<{
+        type: string;
+        id: string;
+    }>;
+    /** set by the kernel, never the pack: whether a built screen of the vendor's (any of its lanes') draws the url */
+    drawn?: boolean;
+};
 export declare function createDerivedFetch(options: DerivedFetchOptions): DerivedFetch;
 export {};

package/dist/src/index.d.ts

@@ -28,7 +28,7 @@ export type { MultipartPart } from './multipart.js';
 export declare const bindSemantics: (m: Parameters<typeof bindAny>[0], handlers: Record<string, Handler>, scope?: CoreScope) => Record<string, DerivedHandler>;
 export { createPackFetch, createVendorFetch, type LanePart, type PackFetchOptions, type PackParts, type PackScenario } from './pack-fetch.js';
 export { createDerivedFetch } from './derived.js';
-export type { DerivedCall, DerivedFetch, DerivedFetchOptions, DerivedHandler, DerivedOperation, DerivedSurface } from './derived.js';
+export type { DerivedCall, DerivedFetch, DerivedFetchOptions, DerivedHandler, DerivedOperation, DerivedSurface, BoardFrame } from './derived.js';
 export { coreFor, crossCutting, derivedRequestScopes, vendorError } from './derived-core.js';
 export { answerVendorErrors, RefusedWriteError } from './head.js';
 export { GraphqlError, type GraphqlPart, type GraphqlResolver } from './graphql-wire.js';

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

@@ -1,5 +1,5 @@
 import { type DerivedManifest, type Handler, type HandlerContext, type VendorManifest } from './derived-core.js';
-import { type DerivedFetch, type DerivedOwner, type DerivedSurface, type Workspace } from './derived.js';
+import { type DerivedFetch, type DerivedOwner, type DerivedSurface, type Workspace, type BoardFrame } from './derived.js';
 import { type PackScenarioAdapter } from './scenario.js';
 import { type SocketEngine } from './sockets.js';
 import { type GraphqlPart } from './graphql-wire.js';
@@ -39,6 +39,8 @@ export type PackParts = {
     };
     /** `semantics/sockets.ts`: each socket's engine, by the id the manifest's `sockets` gives it (sockets.ts). */
     sockets?: Record<string, SocketEngine<HandlerContext>>;
+    /** `semantics/board.ts`: the vendor's frames on the World's board, read from its state (`GET /twin/board`). */
+    board?: (ctx: HandlerContext) => BoardFrame[] | Promise<BoardFrame[]>;
 };
 /** A pack's scenario (`semantics/scenario.ts` exports `scenario`): the adapter the kernel's engine reads the World's
  *  scenario document with, the operations it decides a turn of, and the request an operation is to it (undefined when
@@ -52,6 +54,8 @@ export type PackScenario<Req = any> = {
 export type LanePart = {
     fetch: ((request: Request) => Promise<Response>) & {
         serves?: (method: string, path: string) => boolean;
+        boards?: boolean;
+        draws?: (url: string) => boolean;
     };
     manifest: {
         doors?: ReadonlyArray<{

package/dist/src/pack-fetch.js

@@ -211,7 +211,19 @@ export function createPackFetch(parts, options = {}) {
     // the workspaces a person can be shown (Viewing a World): each built workspace screen's id and path, the pack's own
     // and its lanes'
     const workspaces = () => [...(m.screens ?? []).filter((s) => s.kind === 'workspace' && s.status === 'done' && parts.screens?.[s.id]).map((s) => ({ id: s.id, path: s.path })), ...lanesWorkspaces(parts.lanes ?? {})];
-    // a context the kernel opens for what no surface operation names: a door, a screen, the clock
+    /** Whether a built screen a person views (a workspace or a flow, never content an API client reads) draws a url: its host
+     *  one the screen names, its path the screen's or under it (a root screen draws its root alone). */
+    const drawsUrl = (at) => {
+        try {
+            const u = new URL(at);
+            const path = u.pathname.replace(/\/+$/, '') || '/';
+            return screens.some((s) => s.decl.kind !== 'content' && Boolean(s.host(u.hostname.toLowerCase())) && (s.decl.path.replace(/\/+$/, '') === '' ? path === '/' : Boolean(s.path(path))));
+        }
+        catch {
+            return false;
+        }
+    };
+    // a context the kernel opens for what no surface operation names: a door, a screen, the clock, the board
     const open = (request, id, method, path, params) => contextFor(m, { request, operation: { id, method, path, class: method === 'GET' ? 'retrieve' : 'action' }, params }, scope);
     const refusedReadOnly = () => vendorError(m, m.readOnly);
     const prefix = m.pathPrefix ? new RegExp(`^(?:${m.pathPrefix})(?=/)`) : undefined;
@@ -246,6 +258,15 @@ export function createPackFetch(parts, options = {}) {
         // the discovery door is the pack's own, whichever lane would take its path
         const asked = new URL(arrived.url).pathname.replace(/\/+$/, '') || '/';
         const discovery = arrived.method === 'GET' && m.discovery !== undefined && (asked === '/twin' || asked === '/twin/scenario');
+        // the board is read from the state as it stands, before anything else runs (the clock, a lane, the API): a read,
+        // whoever asks, each frame drawn when a built screen takes its url; a pack that lays out none has an empty board
+        if (arrived.method === 'GET' && asked === '/twin/board') {
+            if (!parts.board)
+                return Response.json({ frames: [] });
+            const request = withHeaders(arrived, new Headers([...arrived.headers, [READ_ONLY_REQUEST_HEADER, '1']]));
+            const frames = await parts.board(await open(request, 'board', 'GET', '/twin/board', {}));
+            return Response.json({ frames: frames.map((f) => ({ ...f, drawn: drawsUrl(f.url) })) });
+        }
         const toLane = discovery ? undefined : lane?.(arrived);
         if (toLane)
             return toLane(arrived);
@@ -400,7 +421,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, ...(upgrade ? { upgrade } : {}) }));
+    return derivedRequestScopes(m, Object.assign(served, { owners, serves, workspaces, boards: Boolean(parts.board), draws: drawsUrl, ...(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. */
@@ -456,6 +477,22 @@ export function createVendorFetch(manifest, lanes) {
     const lane = laneRouter(manifest.vendor, manifest.lanes, lanes);
     return Object.assign(async (request) => {
         const path = new URL(request.url).pathname.replace(/\/+$/, '') || '/';
+        // the vendor's board is the frames of the lanes that lay one out, each drawn when any lane's screen takes its url
+        if (request.method === 'GET' && path === '/twin/board') {
+            const frames = [];
+            for (const l of Object.values(lanes)) {
+                if (!l.fetch.boards)
+                    continue;
+                try {
+                    const answer = await l.fetch(new Request(request.url, { headers: request.headers }));
+                    if (answer.ok)
+                        frames.push(...((await answer.json()).frames ?? []));
+                }
+                catch { /* a lane whose board does not answer lays out nothing */ }
+            }
+            const draws = (url) => Object.values(lanes).some((l) => l.fetch.draws?.(url) ?? false);
+            return Response.json({ frames: frames.map((f) => ({ ...f, drawn: draws(f.url) })) });
+        }
         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);

package/dist/src/runtime.d.ts

@@ -8,7 +8,7 @@ export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, ReadOnlyRequestError, runA
 export { compileSurface, createDerivedFetch, matchOperation } from './derived.js';
 export { currentTraceparent, deliveryTraceHeaders, newTraceparent, parseTraceparent, runWithRequestTrace, runWithTraceparent, TRACEPARENT_HEADER, traceparentForDelivery, validTraceparent } from './trace-context.js';
 export type { Traceparent } from './trace-context.js';
-export type { DerivedCall, DerivedCoreOutcome, DerivedFetch, DerivedFetchOptions, DerivedHandler, DerivedOperation, DerivedOwner, DerivedSurface } from './derived.js';
+export type { DerivedCall, DerivedCoreOutcome, DerivedFetch, DerivedFetchOptions, DerivedHandler, DerivedOperation, DerivedOwner, DerivedSurface, BoardFrame } from './derived.js';
 export { authRefusal, bindSemantics, coreFor, crossCutting, flagOf, derivedRequestScopes, observeTransitions, resourcesOfType as twinResourcesOfType, semanticsContext, stateOf, transitionFor, parseBracketForm, readParams, render as renderDerived, serveCore, sse, vendorError } from './derived-core.js';
 export { deliverEvents, fillEnvelope, signEvent, signEventAll, verifyEvent } from './events.js';
 export { equalSecrets, hmac, jwks, jwtDecode, jwtSign, jwtVerify, keyId, lettersFrom, md5, sha256, SIGNING_ALGORITHMS, uuidFrom } from './signing.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-core",
-  "version": "3.0.9",
+  "version": "3.0.11",
   "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/derived.ts

@@ -198,11 +198,35 @@ export type DerivedFetch = ((request: Request) => Promise<Response>) & {
   upgrade?: WebSocketUpgrade;
   /** The workspace screens it draws, its lanes' too (`GET /twin`'s `screens`). */
   workspaces?(): Workspace[];
+  /** Whether it lays out frames of the World's board (`semantics/board.ts`). */
+  boards?: boolean;
+  /** Whether a built screen of it takes a URL: a board frame it draws. */
+  draws?(url: string): boolean;
 };
 
 /** A workspace screen a pack draws, as `GET /twin` lists it: its id and path (Viewing a World). */
 export type Workspace = { id: string; path: string };
 
+/** A frame of the World's board (architecture, "The board"): one thing of the vendor's where a person sees it, as the
+ *  vendor's pack lays out its default board (`semantics/board.ts`), the editorial choice of which views of the vendor a
+ *  person keeps open (a Worker's site, a repository's page, a Jira board). `GET /twin/board` lists them. */
+export type BoardFrame = {
+  /** stable within the vendor, whatever the World's ids: what a saved board names the frame by */
+  id: string;
+  /** what it is, in the vendor's own word (a site, a repository, a board) */
+  kind: string;
+  title: string;
+  /** the vendor's container it is grouped under (an account, an organization, a project); `aka`, the ids it was known
+   *  by before (an account a deploy adopted), so a board that included it under one still holds it */
+  section: { id: string; title: string; aka?: string[] };
+  /** where the vendor shows it: an absolute URL on the vendor's host, or on a hostname the vendor serves for its customer */
+  url: string;
+  /** the records whose changes are this frame's changes */
+  covers: Array<{ type: string; id: string }>;
+  /** set by the kernel, never the pack: whether a built screen of the vendor's (any of its lanes') draws the url */
+  drawn?: boolean;
+};
+
 export function createDerivedFetch(options: DerivedFetchOptions): DerivedFetch {
   const handlers = options.handlers ?? {};
   const known = new Set(options.surface.operations.map((o) => o.id));

package/src/index.ts

@@ -39,7 +39,7 @@ export const bindSemantics = (m: Parameters<typeof bindAny>[0], handlers: Record
 // ── the derived fetch ──────────────────────────────────────────────────────────────────────────
 export { createPackFetch, createVendorFetch, type LanePart, type PackFetchOptions, type PackParts, type PackScenario } from './pack-fetch.ts';
 export { createDerivedFetch } from './derived.ts';
-export type { DerivedCall, DerivedFetch, DerivedFetchOptions, DerivedHandler, DerivedOperation, DerivedSurface } from './derived.ts';
+export type { DerivedCall, DerivedFetch, DerivedFetchOptions, DerivedHandler, DerivedOperation, DerivedSurface, BoardFrame } from './derived.ts';
 export { coreFor, crossCutting, derivedRequestScopes, vendorError } from './derived-core.ts';
 export { answerVendorErrors, RefusedWriteError } from './head.ts';
 // a GraphQL API's resolvers (`semantics/graphql.ts`), and the error one answers with the vendor's type

package/src/pack-fetch.ts

@@ -10,7 +10,7 @@ import { TWIN_PREFIX_HEADER } from './twin-fetch.ts';
 import { PREFIX_PARAMS_HEADER } from './derived.ts';
 import { withHeaders } from './with-headers.ts';
 import { authRefusal, bindSemantics, contextFor, LANE_HEADER, SCENARIO_DECISION_HEADER, coreFor, crossCutting, derivedRequestScopes, vendorError, type CoreScope, type DerivedManifest, type ErrorSpec, type Handler, type HandlerContext, type LanesDecl, type VendorManifest } from './derived-core.ts';
-import { compileSurface, createDerivedFetch, matchOperation, type DerivedFetch, type DerivedOperation, type DerivedOwner, type DerivedSurface, type Workspace } from './derived.ts';
+import { compileSurface, createDerivedFetch, matchOperation, type DerivedFetch, type DerivedOperation, type DerivedOwner, type DerivedSurface, type Workspace, type BoardFrame } from './derived.ts';
 import { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, runAsVendorMove } from './request-scope.ts';
 import { parseScenarioDocument, ScenarioEngine, ScenarioError, statefulTwinManifest, twinManifest, type PackScenarioAdapter } from './scenario.ts';
 import { getActiveWorldStore } from './world-store.ts';
@@ -57,6 +57,8 @@ export type PackParts = {
   graphql?: GraphqlPart<HandlerContext> & { sdl: string };
   /** `semantics/sockets.ts`: each socket's engine, by the id the manifest's `sockets` gives it (sockets.ts). */
   sockets?: Record<string, SocketEngine<HandlerContext>>;
+  /** `semantics/board.ts`: the vendor's frames on the World's board, read from its state (`GET /twin/board`). */
+  board?: (ctx: HandlerContext) => BoardFrame[] | Promise<BoardFrame[]>;
 };
 
 /** A pack's scenario (`semantics/scenario.ts` exports `scenario`): the adapter the kernel's engine reads the World's
@@ -66,7 +68,7 @@ export type PackParts = {
 export type PackScenario<Req = any> = { adapter: PackScenarioAdapter<Req>; operations: ReadonlyArray<string>; request: (ctx: HandlerContext) => Req | undefined };
 
 /** 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 }; manifest: { doors?: ReadonlyArray<{ method: string; path: string }> } };
+export type LanePart = { fetch: ((request: Request) => Promise<Response>) & { serves?: (method: string, path: string) => boolean; boards?: boolean; draws?: (url: string) => boolean }; manifest: { doors?: ReadonlyArray<{ method: string; path: string }> } };
 
 /** Where a pack serves: its World's root, whether it was started read-only, the World instant when a caller pins it, the
  *  World's managed Postgres the runtime binds a pack declaring `managedDatabase` to (a handler's `ctx.engine`), and the
@@ -245,7 +247,15 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
   // the workspaces a person can be shown (Viewing a World): each built workspace screen's id and path, the pack's own
   // and its lanes'
   const workspaces = (): Workspace[] => [...(m.screens ?? []).filter((s) => s.kind === 'workspace' && s.status === 'done' && parts.screens?.[s.id]).map((s) => ({ id: s.id, path: s.path })), ...lanesWorkspaces(parts.lanes ?? {})];
-  // a context the kernel opens for what no surface operation names: a door, a screen, the clock
+  /** Whether a built screen a person views (a workspace or a flow, never content an API client reads) draws a url: its host
+   *  one the screen names, its path the screen's or under it (a root screen draws its root alone). */
+  const drawsUrl = (at: string): boolean => {
+    try {
+      const u = new URL(at); const path = u.pathname.replace(/\/+$/, '') || '/';
+      return screens.some((s) => s.decl.kind !== 'content' && Boolean(s.host(u.hostname.toLowerCase())) && (s.decl.path.replace(/\/+$/, '') === '' ? path === '/' : Boolean(s.path(path))));
+    } catch { return false; }
+  };
+  // a context the kernel opens for what no surface operation names: a door, a screen, the clock, the board
   const open = (request: Request, id: string, method: string, path: string, params: Record<string, string>): Promise<HandlerContext> =>
     contextFor(m, { request, operation: { id, method, path, class: method === 'GET' ? 'retrieve' : 'action' } as DerivedOperation, params }, scope);
   const refusedReadOnly = (): Response => vendorError(m, m.readOnly);
@@ -278,6 +288,14 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     // the discovery door is the pack's own, whichever lane would take its path
     const asked = new URL(arrived.url).pathname.replace(/\/+$/, '') || '/';
     const discovery = arrived.method === 'GET' && m.discovery !== undefined && (asked === '/twin' || asked === '/twin/scenario');
+    // the board is read from the state as it stands, before anything else runs (the clock, a lane, the API): a read,
+    // whoever asks, each frame drawn when a built screen takes its url; a pack that lays out none has an empty board
+    if (arrived.method === 'GET' && asked === '/twin/board') {
+      if (!parts.board) return Response.json({ frames: [] });
+      const request = withHeaders(arrived, new Headers([...arrived.headers, [READ_ONLY_REQUEST_HEADER, '1']]));
+      const frames = await parts.board(await open(request, 'board', 'GET', '/twin/board', {}));
+      return Response.json({ frames: frames.map((f) => ({ ...f, drawn: drawsUrl(f.url) })) });
+    }
     const toLane = discovery ? undefined : lane?.(arrived);
     if (toLane) return toLane(arrived);
     // only the kernel names a scenario's decision, or a path prefix's parameters
@@ -407,7 +425,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, ...(upgrade ? { upgrade } : {}) }));
+  return derivedRequestScopes(m, Object.assign(served, { owners, serves, workspaces, boards: Boolean(parts.board), draws: drawsUrl, ...(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
@@ -468,6 +486,19 @@ export function createVendorFetch(manifest: VendorManifest, lanes: Record<string
   const lane = laneRouter(manifest.vendor, manifest.lanes, lanes);
   return Object.assign(async (request: Request): Promise<Response> => {
     const path = new URL(request.url).pathname.replace(/\/+$/, '') || '/';
+    // the vendor's board is the frames of the lanes that lay one out, each drawn when any lane's screen takes its url
+    if (request.method === 'GET' && path === '/twin/board') {
+      const frames: BoardFrame[] = [];
+      for (const l of Object.values(lanes)) {
+        if (!l.fetch.boards) continue;
+        try {
+          const answer = await l.fetch(new Request(request.url, { headers: request.headers }));
+          if (answer.ok) frames.push(...(((await answer.json()) as { frames?: BoardFrame[] }).frames ?? []));
+        } catch { /* a lane whose board does not answer lays out nothing */ }
+      }
+      const draws = (url: string): boolean => Object.values(lanes).some((l) => l.fetch.draws?.(url) ?? false);
+      return Response.json({ frames: frames.map((f) => ({ ...f, drawn: draws(f.url) })) });
+    }
     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);

package/src/runtime.ts

@@ -17,7 +17,7 @@ export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, ReadOnlyRequestError, runA
 export { compileSurface, createDerivedFetch, matchOperation } from './derived.ts';
 export { currentTraceparent, deliveryTraceHeaders, newTraceparent, parseTraceparent, runWithRequestTrace, runWithTraceparent, TRACEPARENT_HEADER, traceparentForDelivery, validTraceparent } from './trace-context.ts';
 export type { Traceparent } from './trace-context.ts';
-export type { DerivedCall, DerivedCoreOutcome, DerivedFetch, DerivedFetchOptions, DerivedHandler, DerivedOperation, DerivedOwner, DerivedSurface } from './derived.ts';
+export type { DerivedCall, DerivedCoreOutcome, DerivedFetch, DerivedFetchOptions, DerivedHandler, DerivedOperation, DerivedOwner, DerivedSurface, BoardFrame } from './derived.ts';
 export { authRefusal, bindSemantics, coreFor, crossCutting, flagOf, derivedRequestScopes, observeTransitions, resourcesOfType as twinResourcesOfType, semanticsContext, stateOf, transitionFor, parseBracketForm, readParams, render as renderDerived, serveCore, sse, vendorError } from './derived-core.ts';
 export { deliverEvents, fillEnvelope, signEvent, signEventAll, verifyEvent } from './events.ts';
 export { equalSecrets, hmac, jwks, jwtDecode, jwtSign, jwtVerify, keyId, lettersFrom, md5, sha256, SIGNING_ALGORITHMS, uuidFrom } from './signing.ts';