@volter/world-core 3.0.4 → 3.0.5

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

@@ -296,6 +296,21 @@ export type ScreenDecl = {
     /** the vendor's documentation of the round trip or the screen */
     source: string;
 };
+/** A protocol hook's arguments: the root's executor (it applies the sealed credential; `issued` carries one the vendor
+ *  issued instead), the group and its first entry's recorded input, the perform's context, the derived perform of an
+ *  input (`send`: the recorded request, or one the hook changed), the stored id the World's id of a type resolves to,
+ *  the surface's base path, and the World's blobs of this twin. */
+export type PerformHookArgs = {
+    execute: import('./remote-execute.js').RemoteExecute;
+    group: import('./actions.js').TwinAction[];
+    input: Record<string, unknown>;
+    ctx: import('./head.js').PerformContext;
+    send: (input: Record<string, unknown>) => Promise<import('./head.js').PushOutcome>;
+    resolve: (type: string, localId: string) => string;
+    basePath: string;
+    blob: (key: string) => Promise<Uint8Array | null>;
+};
+export type PerformHook = (args: PerformHookArgs) => Promise<import('./head.js').PushOutcome>;
 export type DerivedManifest = {
     /** The pack's descriptor, as data (docs/contributing/architecture.md, "The descriptor"), every field but `vendor`, which
      *  is the manifest's: the pack registers `packOf(manifest)`, so its index is a fixed file. A lane has none. */
@@ -384,6 +399,14 @@ export type DerivedManifest = {
     vendorBacked?: {
         none: string;
     };
+    /** the resource the vendor's paths name the account by (Cloudflare's `accounts/{account_id}`): with a root, the
+     *  World's account is the one account the root's credential reaches, which refresh observes ("The account a root
+     *  is", architecture) */
+    account?: string;
+    /** a vendor protocol one recorded request cannot express, by the operation that ends it: a session whose answer
+     *  issues the credential its next calls carry (Cloudflare's assets upload), performed by the hook in place of the
+     *  derived request, which it composes (`send`) ("Protocols a request cannot express", architecture) */
+    performs?: Record<string, PerformHook>;
     /** `withParam`: the error names the path parameter that held the unknown id */
     notFound: {
         status: number;

package/dist/src/derived-real.js

@@ -77,7 +77,9 @@ function resolvedDeep(value, resolve) {
     const o = object(value);
     return o ? Object.fromEntries(Object.entries(o).map(([k, v]) => [k, resolvedDeep(v, resolve)])) : value;
 }
-/** A multipart body: the recorded fields, then each recorded file part read back from the World's blob store. */
+/** A multipart body: the recorded fields, then each recorded file part read back from the World's blob store. An
+ *  operation the vendor takes as multipart is sent so with no file part too (a Workers upload of assets alone carries
+ *  only its `metadata` field). */
 async function multipart(body, files, ctx) {
     const boundary = `----volter${hashFieldValue({ body, files }).slice(0, 24)}`;
     const chunks = [];
@@ -123,9 +125,9 @@ function unitOf(units, input) {
         ?? (input.graphql ? units[0] : undefined);
 }
 function performOf(units) {
-    return async (execute, group, ctx) => {
+    // the request a group's first entry recorded (or one a protocol hook changed), sent to the vendor
+    const derived = async (execute, group, ctx, input) => {
         const first = group[0];
-        const input = (first.input ?? {});
         const unit = unitOf(units, input);
         if (!unit)
             throw new RefusedWriteError('vendor', `the write records no operation of the vendor's surface (${String(input.operationId ?? 'none')})`, first.id);
@@ -183,7 +185,7 @@ function performOf(units) {
         const asCame = object(input.body);
         const raw = asCame && typeof asCame.$text === 'string' ? { body: asCame.$text } : asCame && typeof asCame.$base64 === 'string' ? { body: new Uint8Array(Buffer.from(asCame.$base64, 'base64')) } : undefined;
         const sent = raw ? { ...raw, ...(typeof input.contentType === 'string' ? { type: input.contentType } : {}) }
-            : files.length ? await multipart(body, files, ctx) : op ? encode(op, body) : { body: JSON.stringify(body), type: 'application/json' };
+            : files.length || op?.bodyEncoding === 'multipart' ? await multipart(body, files, ctx) : op ? encode(op, body) : { body: JSON.stringify(body), type: 'application/json' };
         const headers = { ...(object(input.headers) ?? {}), ...(sent.type ? { 'content-type': sent.type } : {}) };
         // a retried deploy makes nothing twice, and two Worlds deploying into one account never collide
         if (m.idempotency)
@@ -228,6 +230,22 @@ function performOf(units) {
         }
         return { externalId, actionId: primary.id, data: obj, ...(also.length ? { also } : {}) };
     };
+    return async (execute, group, ctx) => {
+        const input = (group[0].input ?? {});
+        const unit = unitOf(units, input);
+        // a protocol one request cannot express is the pack's hook, which composes the derived perform ("Protocols a
+        // request cannot express")
+        const hook = unit && typeof input.operationId === 'string' ? unit.manifest.performs?.[input.operationId] : undefined;
+        if (!hook || !unit)
+            return derived(execute, group, ctx, input);
+        return hook({
+            execute, group, input, ctx,
+            send: (changed) => derived(execute, group, ctx, changed),
+            resolve: (type, localId) => ctx.resolve(type, localId),
+            basePath: unit.surface.basePath ?? '',
+            blob: (key) => readResourceBlob(ctx.service ?? '', key, ctx.root),
+        });
+    };
 }
 /** Path parameters that name a subject by a field rather than its id, sent as the vendor's value of that field, read
  *  from the adopted landed copy ("Perform", step 1): a parent found by `parent.where` (a repository addressed as
@@ -400,6 +418,21 @@ function adopt(service, root, units, observed) {
             list.push({ id: e.subject.id, fields: held.fields });
         pending.set(e.subject.type, list);
     }
+    // the account a root is ("The account a root is"): the root's credential reaches one account of the type the pack's
+    // paths name it by; observed alone, it is the World's own account (made by the World's door, so no deploy settled it)
+    for (const u of units) {
+        if (!u.manifest.account)
+            continue;
+        const type = storedType(u.manifest, u.manifest.account);
+        const seen = observed.filter((o) => o.type === type);
+        if (seen.length !== 1 || tree.has(`${type}:${seen[0].id}`))
+            continue;
+        const local = readTree(service, root).find((r) => r.type === type && r.deleted !== true && !aliases.has(`${type}:${String(r.id)}`) && String(r.id) !== seen[0].id);
+        if (local) {
+            seen[0].adopts = String(local.id);
+            aliases.set(`${type}:${String(local.id)}`, seen[0].id);
+        }
+    }
     if (!pending.size)
         return;
     const declOf = (type) => {

package/dist/src/executor.js

@@ -148,7 +148,7 @@ function budgeted(vendor, execute, token) {
 }
 /** The call made as the root's credential is applied by the strategy (header replacement when none). */
 function direct(origin, credential, auth, vendorHosts) {
-    return async ({ method, path, headers, body, responseType, presigned }) => {
+    return async ({ method, path, headers, body, responseType, presigned, issued }) => {
         // A PRESIGNED UPLOAD URL the vendor returned: its own signature is its authorization, so the
         // sealed credential never goes with it, whatever host it names. A host other than the root's
         // passes the same validation the root does; the root's own origin (a twin standing in for the
@@ -205,8 +205,12 @@ function direct(origin, credential, auth, vendorHosts) {
                 throw new Error('remote execute: path escaped the validated origin');
         }
         const outbound = new Headers(headers ?? {});
-        for (const [name, value] of Object.entries(credential.headers))
-            outbound.set(name, value);
+        // a credential the vendor issued in this perform is the request's authorization; the sealed one stays home
+        if (issued !== undefined)
+            outbound.set('authorization', issued);
+        else
+            for (const [name, value] of Object.entries(credential.headers))
+                outbound.set(name, value);
         // ── THE STRATEGIES BEYOND HEADER REPLACEMENT ──────────────────────────────────────────────
         // Applied AFTER the anchoring check above, so nothing here can move the request off the
         // validated origin: `searchParams.set` only ever touches the query, and a header is a header.
@@ -214,7 +218,7 @@ function direct(origin, credential, auth, vendorHosts) {
         // FAIL CLOSED. A strategy with no secret must never send a request that merely LOOKS
         // authenticated — that silence is the whole defect this exists to remove. The refusals name the
         // strategy and the parameter, never the secret.
-        if (auth !== undefined) {
+        if (auth !== undefined && issued === undefined) {
             const secret = credential.secret;
             if (typeof secret !== 'string' || secret === '') {
                 throw new Error(`remote execute: the ${auth.in} credential strategy needs \`secret\` on the sealed credential, and it is absent`);
@@ -379,7 +383,7 @@ function exchangeExecute(origin, sealed, auth, vendorHosts, custody) {
         return anchored({ ...request, headers });
     };
     return async (request) => {
-        if (request.presigned)
+        if (request.presigned || request.issued !== undefined)
             return anchored(request);
         const held = current();
         const first = await call(request, held);

package/dist/src/index.d.ts

@@ -14,7 +14,7 @@ export declare const packOf: (manifest: {
 }>) => PackDescriptor;
 /** The pack registered, so the World finds it. */
 export declare const registerPack: (pack: PackDescriptor) => PackDescriptor;
-export type { Actor, CoreScope, DerivedManifest, ErrorSpec, LaneRoute, LanesDecl, VendorManifest, FieldRule, ResourceDecl, ScreenDecl, SeedCall, StateField, Transition } from './derived-core.js';
+export type { Actor, CoreScope, DerivedManifest, PerformHook, PerformHookArgs, ErrorSpec, LaneRoute, LanesDecl, VendorManifest, FieldRule, ResourceDecl, ScreenDecl, SeedCall, StateField, Transition } from './derived-core.js';
 export type { ApplicationAnswer, EndpointsDecl, EventRender, EventScheme, EventsDecl, EventTransport, EventValues, EventWrite } from './events.js';
 export { verifyEvent } from './events.js';
 export { deriveStateSystem, deriveVendorStateSystem } from './derived-real.js';

package/dist/src/remote-execute.d.ts

@@ -12,6 +12,10 @@ export type RemoteExecuteRequest = {
      *  the API, and the request goes WITHOUT the sealed credential. An upload the vendor authorizes
      *  with the API token (LinkedIn's images) is not presigned and cannot use this. */
     presigned?: true;
+    /** An Authorization the vendor ISSUED earlier in the same perform (Cloudflare's assets upload session answers a JWT
+     *  that its upload calls carry instead of the API token), on the root's own origin: it is sent as the request's
+     *  Authorization and the sealed credential does not go with it. */
+    issued?: string;
 };
 export type RemoteExecuteResponse = {
     status: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-core",
-  "version": "3.0.4",
+  "version": "3.0.5",
   "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

@@ -239,6 +239,22 @@ export type ScreenDecl = {
   source: string;
 };
 
+/** A protocol hook's arguments: the root's executor (it applies the sealed credential; `issued` carries one the vendor
+ *  issued instead), the group and its first entry's recorded input, the perform's context, the derived perform of an
+ *  input (`send`: the recorded request, or one the hook changed), the stored id the World's id of a type resolves to,
+ *  the surface's base path, and the World's blobs of this twin. */
+export type PerformHookArgs = {
+  execute: import('./remote-execute.ts').RemoteExecute;
+  group: import('./actions.ts').TwinAction[];
+  input: Record<string, unknown>;
+  ctx: import('./head.ts').PerformContext;
+  send: (input: Record<string, unknown>) => Promise<import('./head.ts').PushOutcome>;
+  resolve: (type: string, localId: string) => string;
+  basePath: string;
+  blob: (key: string) => Promise<Uint8Array | null>;
+};
+export type PerformHook = (args: PerformHookArgs) => Promise<import('./head.ts').PushOutcome>;
+
 export type DerivedManifest = {
   /** The pack's descriptor, as data (docs/contributing/architecture.md, "The descriptor"), every field but `vendor`, which
    *  is the manifest's: the pack registers `packOf(manifest)`, so its index is a fixed file. A lane has none. */
@@ -293,6 +309,14 @@ export type DerivedManifest = {
   /** a pack whose wire has no derived perform (a socket, a line protocol, a managed database): binding a root is refused
    *  with this reason */
   vendorBacked?: { none: string };
+  /** the resource the vendor's paths name the account by (Cloudflare's `accounts/{account_id}`): with a root, the
+   *  World's account is the one account the root's credential reaches, which refresh observes ("The account a root
+   *  is", architecture) */
+  account?: string;
+  /** a vendor protocol one recorded request cannot express, by the operation that ends it: a session whose answer
+   *  issues the credential its next calls carry (Cloudflare's assets upload), performed by the hook in place of the
+   *  derived request, which it composes (`send`) ("Protocols a request cannot express", architecture) */
+  performs?: Record<string, PerformHook>;
   /** `withParam`: the error names the path parameter that held the unknown id */
   notFound: { status: number; message: string; code?: string; kind?: string; withParam?: boolean };
   /** the list envelope (placeholders `{data}`, `{has_more}`, `{url}`, `{first_id}`, `{last_id}`),

package/src/derived-real.ts

@@ -70,7 +70,9 @@ function resolvedDeep(value: unknown, resolve: (v: string) => string): unknown {
   return o ? Object.fromEntries(Object.entries(o).map(([k, v]) => [k, resolvedDeep(v, resolve)])) : value;
 }
 
-/** A multipart body: the recorded fields, then each recorded file part read back from the World's blob store. */
+/** A multipart body: the recorded fields, then each recorded file part read back from the World's blob store. An
+ *  operation the vendor takes as multipart is sent so with no file part too (a Workers upload of assets alone carries
+ *  only its `metadata` field). */
 async function multipart(body: unknown, files: Row[], ctx: PerformContext): Promise<{ body: Uint8Array; type: string }> {
   const boundary = `----volter${hashFieldValue({ body, files }).slice(0, 24)}`;
   const chunks: Uint8Array[] = [];
@@ -110,9 +112,9 @@ function unitOf(units: Unit[], input: Row): Unit | undefined {
 }
 
 function performOf(units: Unit[]): PerformAction {
-  return async (execute: RemoteExecute, group: TwinAction[], ctx: PerformContext): Promise<PushOutcome> => {
+  // the request a group's first entry recorded (or one a protocol hook changed), sent to the vendor
+  const derived = async (execute: RemoteExecute, group: TwinAction[], ctx: PerformContext, input: Row): Promise<PushOutcome> => {
     const first = group[0]!;
-    const input = (first.input ?? {}) as Row;
     const unit = unitOf(units, input);
     if (!unit) throw new RefusedWriteError('vendor', `the write records no operation of the vendor's surface (${String(input.operationId ?? 'none')})`, first.id);
     const { manifest: m, surface } = unit;
@@ -153,7 +155,7 @@ function performOf(units: Unit[]): PerformAction {
     const asCame = object(input.body);
     const raw = asCame && typeof asCame.$text === 'string' ? { body: asCame.$text as string } : asCame && typeof asCame.$base64 === 'string' ? { body: new Uint8Array(Buffer.from(asCame.$base64 as string, 'base64')) } : undefined;
     const sent: { body?: string | Uint8Array; type?: string } = raw ? { ...raw, ...(typeof input.contentType === 'string' ? { type: input.contentType } : {}) }
-      : files.length ? await multipart(body, files, ctx) : op ? encode(op, body) : { body: JSON.stringify(body), type: 'application/json' };
+      : files.length || op?.bodyEncoding === 'multipart' ? await multipart(body, files, ctx) : op ? encode(op, body) : { body: JSON.stringify(body), type: 'application/json' };
     const headers: Record<string, string> = { ...((object(input.headers) ?? {}) as Record<string, string>), ...(sent.type ? { 'content-type': sent.type } : {}) };
     // a retried deploy makes nothing twice, and two Worlds deploying into one account never collide
     if (m.idempotency) headers[m.idempotency.header] = hashFieldValue({ credential: ctx.credential ?? '', entry: first.id });
@@ -193,6 +195,21 @@ function performOf(units: Unit[]): PerformAction {
     }
     return { externalId, actionId: primary.id, data: obj, ...(also.length ? { also } : {}) };
   };
+  return async (execute: RemoteExecute, group: TwinAction[], ctx: PerformContext): Promise<PushOutcome> => {
+    const input = (group[0]!.input ?? {}) as Row;
+    const unit = unitOf(units, input);
+    // a protocol one request cannot express is the pack's hook, which composes the derived perform ("Protocols a
+    // request cannot express")
+    const hook = unit && typeof input.operationId === 'string' ? unit.manifest.performs?.[input.operationId] : undefined;
+    if (!hook || !unit) return derived(execute, group, ctx, input);
+    return hook({
+      execute, group, input, ctx,
+      send: (changed) => derived(execute, group, ctx, changed),
+      resolve: (type, localId) => ctx.resolve(type, localId),
+      basePath: unit.surface.basePath ?? '',
+      blob: (key) => readResourceBlob(ctx.service ?? '', key, ctx.root),
+    });
+  };
 }
 
 /** Path parameters that name a subject by a field rather than its id, sent as the vendor's value of that field, read
@@ -336,6 +353,16 @@ function adopt(service: string, root: string | undefined, units: Unit[], observe
     if (!list.some((p) => p.id === e.subject.id)) list.push({ id: e.subject.id, fields: held.fields });
     pending.set(e.subject.type, list);
   }
+  // the account a root is ("The account a root is"): the root's credential reaches one account of the type the pack's
+  // paths name it by; observed alone, it is the World's own account (made by the World's door, so no deploy settled it)
+  for (const u of units) {
+    if (!u.manifest.account) continue;
+    const type = storedType(u.manifest, u.manifest.account);
+    const seen = observed.filter((o) => o.type === type);
+    if (seen.length !== 1 || tree.has(`${type}:${seen[0]!.id}`)) continue;
+    const local = (readTree(service, root) as Row[]).find((r) => r.type === type && r.deleted !== true && !aliases.has(`${type}:${String(r.id)}`) && String(r.id) !== seen[0]!.id);
+    if (local) { seen[0]!.adopts = String(local.id); aliases.set(`${type}:${String(local.id)}`, seen[0]!.id); }
+  }
   if (!pending.size) return;
   const declOf = (type: string): { m: DerivedManifest; decl: ResourceDecl } | undefined => {
     for (const u of units) { const hit = Object.entries(u.manifest.resources).find(([r]) => storedType(u.manifest, r) === type); if (hit) return { m: u.manifest, decl: hit[1] }; }

package/src/executor.ts

@@ -243,7 +243,7 @@ function budgeted(vendor: string, execute: RemoteExecute, token: string): Remote
 
 /** The call made as the root's credential is applied by the strategy (header replacement when none). */
 function direct(origin: URL, credential: CredentialPayload, auth?: Exclude<TwinAuthStrategy, { in: 'exchange' }>, vendorHosts?: readonly HostRule[]): RemoteExecute {
-  return async ({ method, path, headers, body, responseType, presigned }) => {
+  return async ({ method, path, headers, body, responseType, presigned, issued }) => {
     // A PRESIGNED UPLOAD URL the vendor returned: its own signature is its authorization, so the
     // sealed credential never goes with it, whatever host it names. A host other than the root's
     // passes the same validation the root does; the root's own origin (a twin standing in for the
@@ -288,7 +288,9 @@ function direct(origin: URL, credential: CredentialPayload, auth?: Exclude<TwinA
       if (target.origin !== origin.origin || !target.pathname.startsWith(origin.pathname.replace(/\/+$/, ''))) throw new Error('remote execute: path escaped the validated origin');
     }
     const outbound = new Headers(headers ?? {});
-    for (const [name, value] of Object.entries(credential.headers)) outbound.set(name, value);
+    // a credential the vendor issued in this perform is the request's authorization; the sealed one stays home
+    if (issued !== undefined) outbound.set('authorization', issued);
+    else for (const [name, value] of Object.entries(credential.headers)) outbound.set(name, value);
 
     // ── THE STRATEGIES BEYOND HEADER REPLACEMENT ──────────────────────────────────────────────
     // Applied AFTER the anchoring check above, so nothing here can move the request off the
@@ -297,7 +299,7 @@ function direct(origin: URL, credential: CredentialPayload, auth?: Exclude<TwinA
     // FAIL CLOSED. A strategy with no secret must never send a request that merely LOOKS
     // authenticated — that silence is the whole defect this exists to remove. The refusals name the
     // strategy and the parameter, never the secret.
-    if (auth !== undefined) {
+    if (auth !== undefined && issued === undefined) {
       const secret = credential.secret;
       if (typeof secret !== 'string' || secret === '') {
         throw new Error(`remote execute: the ${auth.in} credential strategy needs \`secret\` on the sealed credential, and it is absent`);
@@ -437,7 +439,7 @@ function exchangeExecute(origin: URL, sealed: CredentialPayload, auth: Extract<T
     return anchored({ ...request, headers });
   };
   return async (request) => {
-    if (request.presigned) return anchored(request);
+    if (request.presigned || request.issued !== undefined) return anchored(request);
     const held = current();
     const first = await call(request, held);
     if (!retryOn.includes(first.status)) return first;

package/src/index.ts

@@ -21,7 +21,7 @@ export const packOf = (
 export const registerPack = (pack: PackDescriptor): PackDescriptor => registerAny(pack);
 
 // ── the manifest ───────────────────────────────────────────────────────────────────────────────
-export type { Actor, CoreScope, DerivedManifest, ErrorSpec, LaneRoute, LanesDecl, VendorManifest, FieldRule, ResourceDecl, ScreenDecl, SeedCall, StateField, Transition } from './derived-core.ts';
+export type { Actor, CoreScope, DerivedManifest, PerformHook, PerformHookArgs, ErrorSpec, LaneRoute, LanesDecl, VendorManifest, FieldRule, ResourceDecl, ScreenDecl, SeedCall, StateField, Transition } from './derived-core.ts';
 export type { ApplicationAnswer, EndpointsDecl, EventRender, EventScheme, EventsDecl, EventTransport, EventValues, EventWrite } from './events.ts';
 export { verifyEvent } from './events.ts';
 export { deriveStateSystem, deriveVendorStateSystem } from './derived-real.ts';

package/src/remote-execute.ts

@@ -16,6 +16,10 @@ export type RemoteExecuteRequest = {
    *  the API, and the request goes WITHOUT the sealed credential. An upload the vendor authorizes
    *  with the API token (LinkedIn's images) is not presigned and cannot use this. */
   presigned?: true;
+  /** An Authorization the vendor ISSUED earlier in the same perform (Cloudflare's assets upload session answers a JWT
+   *  that its upload calls carry instead of the API token), on the root's own origin: it is sent as the request's
+   *  Authorization and the sealed credential does not go with it. */
+  issued?: string;
 };
 export type RemoteExecuteResponse = {
   status: number;