@volter/world-core 2.0.13 → 2.0.15

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

@@ -296,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
@@ -428,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/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.13",
+  "version": "2.0.15",
   "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",
@@ -48,7 +48,7 @@
     "url": "git+https://github.com/volter-ai/twin.git",
     "directory": "packages/world-core"
   },
-  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/world-core#readme",
+  "homepage": "https://world.volter.ai/docs/README",
   "type": "module",
   "exports": {
     ".": {

package/src/derived-core.ts

@@ -226,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 ──────────────────────────────────────────────────────────────────────────
@@ -504,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 } : {}) };
 }
@@ -620,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 };
@@ -834,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). */
@@ -841,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(() => '');
@@ -915,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/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';