@volter/world-core 2.0.12 → 2.0.14

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

@@ -163,8 +163,7 @@ export type DerivedManifest = {
         template: string;
         acceptProvided?: boolean;
     };
-    /** operations the derived core must not claim though their resource is declared: served by
-     *  the pack's existing code, or a gap, until someone models them */
+    /** operations the derived core must not claim though their resource is declared: a gap until someone models them */
     unmodeled?: string[];
     /** operations that only read though nothing in the spec says so (a POST that returns data):
      *  a read-only twin answers them */
@@ -297,6 +296,9 @@ export type DerivedManifest = {
         root?: string;
         occurredAt: string;
         request: Request;
+        /** the writing call's context, narrow as a handler's, at the write's moment: what the hook reads to render the event
+         *  it sends (until `declared-semantics` makes events data the kernel renders) */
+        context(): Promise<WriteHookContext>;
     }) => Promise<void>;
 };
 /** A form body's bracket notation (`a[b][0][c]=v`, `expand[]=x`) as nested objects and arrays. A form carries only
@@ -429,12 +431,31 @@ export type SemanticsContext = {
     expand(resource: string, body: Record<string, unknown>): Record<string, unknown>;
     /** This context at another moment of the World clock (ISO): a move time makes is written at the moment it fell due. */
     at(when: string): Promise<SemanticsContext>;
+    /** This call's context over another manifest of the same service, at the same moment: a lane over its vendor's
+     *  state reads and writes the vendor's resources through the vendor's manifest ("Pack layout"). */
+    over(other: DerivedManifest): Promise<SemanticsContext>;
     /** The generic core's answer to this call, or undefined where the core does not serve it. */
     core(): Promise<Response | undefined>;
     /** A stored row's own fields, as the vendor's object carries them (an `id`, `type` or `updatedAt` of its own restored). */
     own(row: Record<string, unknown>): Record<string, unknown>;
 };
 export type Semantics = (ctx: SemanticsContext) => Promise<Response>;
+/** The context a derived pack's handler is given ("What an author writes, and how"): the kernel's own members
+ *  (`now`, `core`, `atomically`, `tree`, `writeDetailed`) and the tree's location (`root`) are not on it, so a handler
+ *  typed `Handler` cannot reach them. Its reads are those the contract lists (`row`, `rowsRaw`, `rows`, `get`,
+ *  `history`, `resolve`, `expand`); `at` and `over` give the same narrow context at another moment or over the
+ *  vendor's manifest. */
+export type HandlerContext = Omit<SemanticsContext, 'now' | 'core' | 'atomically' | 'tree' | 'writeDetailed' | 'root' | 'at' | 'over'> & {
+    /** This context at another moment of the World clock (ISO): a move time makes is written at the moment it fell due. */
+    at(when: string): Promise<HandlerContext>;
+    /** This call's context over the manifest of the vendor whose state a lane shares, at the same moment. */
+    over(other: DerivedManifest): Promise<HandlerContext>;
+};
+/** What a write hook reads: the writing call's context without its ways to write, so a hook that renders an event
+ *  cannot write again (and run itself again). */
+export type WriteHookContext = Omit<HandlerContext, 'write' | 'record' | 'at' | 'over'>;
+/** A derived pack's handler: one operation, by its operationId, over the contract's context. */
+export type Handler = (ctx: HandlerContext) => Promise<Response>;
 /** A pack's semantics handlers as the dispatch's handlers. */
 export declare function bindSemantics(m: DerivedManifest, handlers: Record<string, Semantics>, scope?: CoreScope): Record<string, DerivedHandler>;
 /** The derived core as the dispatch's core: it owns every operation on a resource the manifest declares. */

package/dist/src/derived-core.js

@@ -311,7 +311,7 @@ async function writeDetailed(m, call, resource, id, fields, operation, params, r
     { operation, subjectType: storedType(m, resource), subjectId: id, fields, input: { operationId: call.operation.id, params: call.params, body: params }, occurredAt, actor: { kind: 'agent', ...(m.identity ? { id: m.identity(call.request.headers.get('authorization'), root) } : {}) } }, root);
     const body = view(m, resource, row);
     if (m.onWrite)
-        await m.onWrite({ operation, storedType: storedType(m, resource), body, ...(root !== undefined ? { root } : {}), occurredAt, request: call.request });
+        await m.onWrite({ operation, storedType: storedType(m, resource), body, ...(root !== undefined ? { root } : {}), occurredAt, request: call.request, context: () => contextFor(m, { ...call, request: call.request.clone() }, { ...(root !== undefined ? { root } : {}), clock: () => occurredAt }) });
     // the subject's id as it stands after the write: the vendor's, when a live head minted one
     return { body, id: result.externalId ?? row.id, ...(result.vendorData !== undefined ? { vendorData: result.vendorData } : {}) };
 }
@@ -428,7 +428,8 @@ export async function serveCore(m, call, scope = {}) {
     if (!resource || !decl)
         return { unmodeled: `no manifest entry for resource ${resource ?? '(none)'}` };
     call = adoptedPath(m, call, root);
-    const params = await boundaryParams(m, call, root);
+    // the body is read from a copy, so the call's own request is still unread for the write hook's context
+    const params = await boundaryParams(m, { ...call, request: call.request.clone() }, root);
     const idParam = subjectOf(m, resource, call);
     const orphan = missingParent(m, resource, call, root);
     if (orphan)
@@ -601,6 +602,7 @@ export function sse(m, events, operationId) {
 }
 async function contextFor(m, call, scope) {
     const root = scope.root;
+    const asAsked = call;
     call = adoptedPath(m, call, root);
     const at = (scope.clock ?? worldNow)();
     const text = await call.request.clone().text().catch(() => '');
@@ -680,6 +682,7 @@ async function contextFor(m, call, scope) {
         sse: (events) => sse(m, events, call.operation.id),
         expand: (resource, body) => (paths.length ? expand(m, resource, body, paths, root) : body),
         at: (when) => contextFor(m, { ...call, request: new Request(call.request.url) }, { ...scope, clock: () => when }),
+        over: (other) => contextFor(other, { ...asAsked, request: asAsked.request.clone() }, { ...scope, clock: () => at }),
         core: async () => { const out = await serveCore(m, { ...call, request: pristine.clone() }, { ...scope, clock: () => at }); return 'served' in out ? out.served : undefined; },
         own: (row) => ownFields(row),
     };

package/dist/src/derived.d.ts

@@ -54,10 +54,8 @@ export type DerivedFetchOptions = {
     };
     /** An RPC wire: every method is reached by any HTTP method (Slack's clients POST reads too). */
     anyMethod?: boolean;
-    /** The pack's existing fetch while it moves: everything no handler or core owns, and what the core cannot model. */
-    legacy?: (request: Request) => Promise<Response>;
     /** What every operation a handler or the core serves passes through (read-only refusal, version
-     *  checks, idempotent replay); the pack's existing fetch keeps its own while it moves. */
+     *  checks, idempotent replay). */
     around?: (call: DerivedCall, next: () => Promise<Response>) => Promise<Response>;
     /** The vendor's answer for an operation nothing models: the pack's gap. */
     gap: (request: Request, operation: DerivedOperation | undefined, reason: string) => Response;
@@ -74,7 +72,7 @@ export declare function matchOperation(routes: Map<string, Route[]>, method: str
     operation: DerivedOperation;
     params: Record<string, string>;
 } | undefined;
-export type DerivedOwner = 'handler' | 'core' | 'legacy' | 'gap';
+export type DerivedOwner = 'handler' | 'core' | 'gap';
 export type DerivedFetch = ((request: Request) => Promise<Response>) & {
     /** Per operationId, who serves it: a semantics handler, the derived core, the pack's existing
      *  fetch while it moves, or nothing (the vendor's gap). */

package/dist/src/derived.js

@@ -85,7 +85,7 @@ export function createDerivedFetch(options) {
     if (unknown.length)
         throw new Error(`derived dispatch: handlers name operations the surface does not have: ${unknown.sort().join(', ')}`);
     const routes = compileSurface(options.surface);
-    const fallback = (request, operation, reason) => options.legacy ? options.legacy(request) : Promise.resolve(options.gap(request, operation, reason));
+    const fallback = (request, operation, reason) => Promise.resolve(options.gap(request, operation, reason));
     // a valid incoming W3C traceparent scopes the dispatch, so every entry it appends records it (trace-context.ts)
     const fetch = ((request) => runWithRequestTrace(request, () => dispatch(request)));
     const dispatch = async (request) => {
@@ -120,6 +120,6 @@ export function createDerivedFetch(options) {
         }
         return fallback(request, matched.operation, 'no handler');
     };
-    fetch.owners = () => Object.fromEntries(options.surface.operations.map((o) => [o.id, handlers[o.id] ? 'handler' : options.core?.owns(o) ? 'core' : options.legacy ? 'legacy' : 'gap']));
+    fetch.owners = () => Object.fromEntries(options.surface.operations.map((o) => [o.id, handlers[o.id] ? 'handler' : options.core?.owns(o) ? 'core' : 'gap']));
     return fetch;
 }

package/dist/src/index.d.ts

@@ -10,7 +10,7 @@ export { currentTraceparent, deliveryTraceHeaders, parseTraceparent, runWithRequ
 export type { Traceparent } from './trace-context.js';
 export type { DerivedCall, DerivedCoreOutcome, DerivedFetch, DerivedFetchOptions, DerivedHandler, DerivedOperation, DerivedOwner, DerivedSurface } from './derived.js';
 export { bindSemantics, coreFor, crossCutting, derivedRequestScopes, observeTransitions, resourcesOfType as twinResourcesOfType, semanticsContext, stateOf, transitionFor, parseBracketForm, readParams, render as renderDerived, serveCore, sse, vendorError } from './derived-core.js';
-export type { Actor, CoreScope, DerivedManifest, ErrorSpec, FieldRule, ResourceDecl, ScreenDecl, Semantics, SemanticsContext, StateField, Transition, TransitionObserver } from './derived-core.js';
+export type { Actor, CoreScope, DerivedManifest, ErrorSpec, FieldRule, Handler, HandlerContext, ResourceDecl, WriteHookContext, ScreenDecl, Semantics, SemanticsContext, StateField, Transition, TransitionObserver } from './derived-core.js';
 export type { RemoteExecute, RemoteExecuteRequest, RemoteExecuteResponse } from './remote-execute.js';
 export type { TwinFetchAdapterConfig, TwinFetchHandlerRequest, TwinFetchHandlerResult, TwinStream, TwinStreamConnection, TwinStreamSink } from './twin-fetch.js';
 export type { PackScenarioAdapter, ScenarioDecision, ScenarioDocument, ScenarioExtractorSpec, ScenarioFault, ScenarioFaultResult, ScenarioFeatures, ScenarioHandler, ScenarioMatcher, ScenarioMissRecord, ScenarioStatus } from './scenario.js';

package/package.json

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

@@ -147,8 +147,7 @@ export type DerivedManifest = {
    *  (`{prefix}_{n}`), or is `{uuid}` for a vendor whose ids are UUIDs: the next is derived from the resource and its
    *  count, so a World mints the same ids every run */
   ids: { template: string; acceptProvided?: boolean };
-  /** operations the derived core must not claim though their resource is declared: served by
-   *  the pack's existing code, or a gap, until someone models them */
+  /** operations the derived core must not claim though their resource is declared: a gap until someone models them */
   unmodeled?: string[];
   /** operations that only read though nothing in the spec says so (a POST that returns data):
    *  a read-only twin answers them */
@@ -227,7 +226,12 @@ export type DerivedManifest = {
   /** the vendor's screens this pack serves or owes (demand decides which exist) */
   screens?: ScreenDecl[];
   /** called after every stored write with the rendered resource, its stored type and the kernel operation name */
-  onWrite?: (write: { operation: string; storedType: string; body: Record<string, unknown>; root?: string; occurredAt: string; request: Request }) => Promise<void>;
+  onWrite?: (write: {
+    operation: string; storedType: string; body: Record<string, unknown>; root?: string; occurredAt: string; request: Request;
+    /** the writing call's context, narrow as a handler's, at the write's moment: what the hook reads to render the event
+     *  it sends (until `declared-semantics` makes events data the kernel renders) */
+    context(): Promise<WriteHookContext>;
+  }) => Promise<void>;
 };
 
 // ── request parsing ──────────────────────────────────────────────────────────────────────────
@@ -505,7 +509,7 @@ async function writeDetailed(m: DerivedManifest, call: DerivedCall, resource: st
     root,
   );
   const body = view(m, resource, row);
-  if (m.onWrite) await m.onWrite({ operation, storedType: storedType(m, resource), body, ...(root !== undefined ? { root } : {}), occurredAt, request: call.request });
+  if (m.onWrite) await m.onWrite({ operation, storedType: storedType(m, resource), body, ...(root !== undefined ? { root } : {}), occurredAt, request: call.request, context: () => contextFor(m, { ...call, request: call.request.clone() }, { ...(root !== undefined ? { root } : {}), clock: () => occurredAt }) });
   // the subject's id as it stands after the write: the vendor's, when a live head minted one
   return { body, id: result.externalId ?? row.id, ...(result.vendorData !== undefined ? { vendorData: result.vendorData } : {}) };
 }
@@ -621,7 +625,8 @@ export async function serveCore(m: DerivedManifest, call: DerivedCall, scope: Co
   const decl = resource ? m.resources[resource] : undefined;
   if (!resource || !decl) return { unmodeled: `no manifest entry for resource ${resource ?? '(none)'}` };
   call = adoptedPath(m, call, root);
-  const params = await boundaryParams(m, call, root);
+  // the body is read from a copy, so the call's own request is still unread for the write hook's context
+  const params = await boundaryParams(m, { ...call, request: call.request.clone() }, root);
   const idParam = subjectOf(m, resource, call);
   const orphan = missingParent(m, resource, call, root);
   if (orphan) return { served: orphan };
@@ -835,6 +840,9 @@ export type SemanticsContext = {
   expand(resource: string, body: Record<string, unknown>): Record<string, unknown>;
   /** This context at another moment of the World clock (ISO): a move time makes is written at the moment it fell due. */
   at(when: string): Promise<SemanticsContext>;
+  /** This call's context over another manifest of the same service, at the same moment: a lane over its vendor's
+   *  state reads and writes the vendor's resources through the vendor's manifest ("Pack layout"). */
+  over(other: DerivedManifest): Promise<SemanticsContext>;
   /** The generic core's answer to this call, or undefined where the core does not serve it. */
   core(): Promise<Response | undefined>;
   /** A stored row's own fields, as the vendor's object carries them (an `id`, `type` or `updatedAt` of its own restored). */
@@ -842,8 +850,26 @@ export type SemanticsContext = {
 };
 export type Semantics = (ctx: SemanticsContext) => Promise<Response>;
 
+/** The context a derived pack's handler is given ("What an author writes, and how"): the kernel's own members
+ *  (`now`, `core`, `atomically`, `tree`, `writeDetailed`) and the tree's location (`root`) are not on it, so a handler
+ *  typed `Handler` cannot reach them. Its reads are those the contract lists (`row`, `rowsRaw`, `rows`, `get`,
+ *  `history`, `resolve`, `expand`); `at` and `over` give the same narrow context at another moment or over the
+ *  vendor's manifest. */
+export type HandlerContext = Omit<SemanticsContext, 'now' | 'core' | 'atomically' | 'tree' | 'writeDetailed' | 'root' | 'at' | 'over'> & {
+  /** This context at another moment of the World clock (ISO): a move time makes is written at the moment it fell due. */
+  at(when: string): Promise<HandlerContext>;
+  /** This call's context over the manifest of the vendor whose state a lane shares, at the same moment. */
+  over(other: DerivedManifest): Promise<HandlerContext>;
+};
+/** What a write hook reads: the writing call's context without its ways to write, so a hook that renders an event
+ *  cannot write again (and run itself again). */
+export type WriteHookContext = Omit<HandlerContext, 'write' | 'record' | 'at' | 'over'>;
+/** A derived pack's handler: one operation, by its operationId, over the contract's context. */
+export type Handler = (ctx: HandlerContext) => Promise<Response>;
+
 async function contextFor(m: DerivedManifest, call: DerivedCall, scope: CoreScope): Promise<SemanticsContext> {
   const root = scope.root;
+  const asAsked = call;
   call = adoptedPath(m, call, root);
   const at = (scope.clock ?? worldNow)();
   const text = await call.request.clone().text().catch(() => '');
@@ -916,6 +942,7 @@ async function contextFor(m: DerivedManifest, call: DerivedCall, scope: CoreScop
     sse: (events) => sse(m, events, call.operation.id),
     expand: (resource, body) => (paths.length ? expand(m, resource, body, paths, root) : body),
     at: (when) => contextFor(m, { ...call, request: new Request(call.request.url) }, { ...scope, clock: () => when }),
+    over: (other) => contextFor(other, { ...asAsked, request: asAsked.request.clone() }, { ...scope, clock: () => at }),
     core: async () => { const out = await serveCore(m, { ...call, request: pristine.clone() }, { ...scope, clock: () => at }); return 'served' in out ? out.served : undefined; },
     own: (row) => ownFields(row as unknown as TwinResource),
   };

package/src/derived.ts

@@ -46,10 +46,8 @@ export type DerivedFetchOptions = {
   core?: { owns: (operation: DerivedOperation) => boolean; serve: (call: DerivedCall) => Promise<DerivedCoreOutcome> };
   /** An RPC wire: every method is reached by any HTTP method (Slack's clients POST reads too). */
   anyMethod?: boolean;
-  /** The pack's existing fetch while it moves: everything no handler or core owns, and what the core cannot model. */
-  legacy?: (request: Request) => Promise<Response>;
   /** What every operation a handler or the core serves passes through (read-only refusal, version
-   *  checks, idempotent replay); the pack's existing fetch keeps its own while it moves. */
+   *  checks, idempotent replay). */
   around?: (call: DerivedCall, next: () => Promise<Response>) => Promise<Response>;
   /** The vendor's answer for an operation nothing models: the pack's gap. */
   gap: (request: Request, operation: DerivedOperation | undefined, reason: string) => Response;
@@ -126,7 +124,7 @@ export function matchOperation(routes: Map<string, Route[]>, method: string, pat
   return undefined;
 }
 
-export type DerivedOwner = 'handler' | 'core' | 'legacy' | 'gap';
+export type DerivedOwner = 'handler' | 'core' | 'gap';
 
 export type DerivedFetch = ((request: Request) => Promise<Response>) & {
   /** Per operationId, who serves it: a semantics handler, the derived core, the pack's existing
@@ -141,7 +139,7 @@ export function createDerivedFetch(options: DerivedFetchOptions): DerivedFetch {
   if (unknown.length) throw new Error(`derived dispatch: handlers name operations the surface does not have: ${unknown.sort().join(', ')}`);
   const routes = compileSurface(options.surface);
   const fallback = (request: Request, operation: DerivedOperation | undefined, reason: string): Promise<Response> =>
-    options.legacy ? options.legacy(request) : Promise.resolve(options.gap(request, operation, reason));
+    Promise.resolve(options.gap(request, operation, reason));
   // a valid incoming W3C traceparent scopes the dispatch, so every entry it appends records it (trace-context.ts)
   const fetch = ((request: Request): Promise<Response> => runWithRequestTrace(request, () => dispatch(request))) as DerivedFetch;
   const dispatch = async (request: Request): Promise<Response> => {
@@ -173,7 +171,7 @@ export function createDerivedFetch(options: DerivedFetchOptions): DerivedFetch {
   };
   fetch.owners = () =>
     Object.fromEntries(
-      options.surface.operations.map((o) => [o.id, handlers[o.id] ? 'handler' : options.core?.owns(o) ? 'core' : options.legacy ? 'legacy' : 'gap'] as const),
+      options.surface.operations.map((o) => [o.id, handlers[o.id] ? 'handler' : options.core?.owns(o) ? 'core' : 'gap'] as const),
     );
   return fetch;
 }

package/src/index.ts

@@ -22,7 +22,7 @@ export { currentTraceparent, deliveryTraceHeaders, parseTraceparent, runWithRequ
 export type { Traceparent } from './trace-context.ts';
 export type { DerivedCall, DerivedCoreOutcome, DerivedFetch, DerivedFetchOptions, DerivedHandler, DerivedOperation, DerivedOwner, DerivedSurface } from './derived.ts';
 export { bindSemantics, coreFor, crossCutting, derivedRequestScopes, observeTransitions, resourcesOfType as twinResourcesOfType, semanticsContext, stateOf, transitionFor, parseBracketForm, readParams, render as renderDerived, serveCore, sse, vendorError } from './derived-core.ts';
-export type { Actor, CoreScope, DerivedManifest, ErrorSpec, FieldRule, ResourceDecl, ScreenDecl, Semantics, SemanticsContext, StateField, Transition, TransitionObserver } from './derived-core.ts';
+export type { Actor, CoreScope, DerivedManifest, ErrorSpec, FieldRule, Handler, HandlerContext, ResourceDecl, WriteHookContext, ScreenDecl, Semantics, SemanticsContext, StateField, Transition, TransitionObserver } from './derived-core.ts';
 export type { RemoteExecute, RemoteExecuteRequest, RemoteExecuteResponse } from './remote-execute.ts';
 export type { TwinFetchAdapterConfig, TwinFetchHandlerRequest, TwinFetchHandlerResult, TwinStream, TwinStreamConnection, TwinStreamSink } from './twin-fetch.ts';
 export type { PackScenarioAdapter, ScenarioDecision, ScenarioDocument, ScenarioExtractorSpec, ScenarioFault, ScenarioFaultResult, ScenarioFeatures, ScenarioHandler, ScenarioMatcher, ScenarioMissRecord, ScenarioStatus } from './scenario.ts';