@volter/world-core 3.0.5 → 3.0.6

package/dist/src/derived-real.js

@@ -124,6 +124,33 @@ function unitOf(units, input) {
         ?? units.find((u) => u.surface.operations.some((o) => o.id === id))
         ?? (input.graphql ? units[0] : undefined);
 }
+/** The account a root is, before a perform sends a path naming the World's ("The account a root is"): the World's
+ *  account its own doors made, unadopted, adopts the one account the root's credential lists. Read once per deploy (an
+ *  adopted account is not asked again); a list the vendor refuses, or one naming several accounts, adopts none. */
+async function adoptAccount(units, execute, ctx) {
+    if (ctx.service === undefined)
+        return;
+    for (const u of units) {
+        const m = u.manifest;
+        const decl = m.account ? m.resources[m.account] : undefined;
+        if (!m.account || !decl)
+            continue;
+        const type = storedType(m, m.account);
+        const local = readTree(ctx.service, ctx.root).filter((r) => r.type === type && r.deleted !== true && ctx.resolve(type, String(r.id)) === String(r.id));
+        const scope = decl.refresh;
+        const op = scope && 'list' in scope ? u.surface.operations.find((o) => o.id === scope.list) : undefined;
+        if (!local.length || !op)
+            continue;
+        const answer = await execute({ method: op.method.toUpperCase(), path: `${op.basePath ?? u.surface.basePath ?? ''}${op.path}`, ...(u.lane ? { lane: u.lane } : {}) });
+        if (answer.status >= 400)
+            continue;
+        const items = itemsOf(op, parse(answer));
+        const id = items.length === 1 ? storedIdOf(decl, items[0]) : undefined;
+        if (id === undefined || local.some((l) => String(l.id) === id))
+            continue;
+        observeResources(ctx.service, [{ type, id, fields: items[0], adopts: String(local[0].id) }], ctx.root !== undefined ? { root: ctx.root } : {});
+    }
+}
 function performOf(units) {
     // 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) => {
@@ -190,7 +217,7 @@ function performOf(units) {
         // 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 });
-        const answer = await execute({ method, path, headers, ...(sent.body !== undefined ? { body: sent.body } : {}) });
+        const answer = await execute({ method, path, headers, ...(sent.body !== undefined ? { body: sent.body } : {}), ...(unit.lane ? { lane: unit.lane } : {}) });
         const parsed = parse(answer);
         const shape = refusalShape(m);
         const refused = answer.status >= 400 || (shape.length > 0 && shape.every(([p, v]) => at(parsed, p) === v));
@@ -231,6 +258,7 @@ function performOf(units) {
         return { externalId, actionId: primary.id, data: obj, ...(also.length ? { also } : {}) };
     };
     return async (execute, group, ctx) => {
+        await adoptAccount(units, execute, 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
@@ -297,7 +325,8 @@ function refreshOf(units, service) {
     return async (execute, opts) => {
         const observed = [];
         const complete = [];
-        for (const { manifest: m, surface } of units) {
+        for (const unit of units) {
+            const { manifest: m, surface } = unit;
             // parents before children, however deep
             const scoped = Object.entries(m.resources).filter(([, d]) => d.refresh && !('none' in d.refresh));
             const depth = (r, seen = new Set()) => { const p = m.resources[r]?.parent?.resource; return p && !seen.has(p) ? 1 + depth(p, seen.add(r)) : 0; };
@@ -319,7 +348,7 @@ function refreshOf(units, service) {
                         // a parent the operation names in its query, not its path (Slack's conversations.history `channel`)
                         const byQuery = decl.parent?.param && parent !== undefined && !op.path.includes(`{${decl.parent.param}}`) ? { [decl.parent.param]: String(parent) } : {};
                         const q = new URLSearchParams({ ...page, ...byQuery });
-                        const answer = await execute({ method: op.method.toUpperCase(), path: [...q].length ? `${path}?${q}` : path });
+                        const answer = await execute({ method: op.method.toUpperCase(), path: [...q].length ? `${path}?${q}` : path, ...(unit.lane ? { lane: unit.lane } : {}) });
                         if (answer.status === 401 || answer.status === 403)
                             throw new Error(`${answer.status}: the vendor refused the root's credential; nothing folded`);
                         if (answer.status === 429)

package/dist/src/executor.d.ts

@@ -12,8 +12,14 @@ import type { HostRule } from './packRegistry.js';
  * and no sealed credential migrates.
  */
 export type TwinAuthStrategy = 
-/** the key rides in the query string (`?key=…`, `?appid=…`) — no header will do */
+/** A vendor of lanes whose lanes authenticate apart (Cloudflare's API by bearer, its R2 by SigV4): a lane named takes
+ *  its own strategy, every other call the sealed headers; the request names its lane (`RemoteExecuteRequest.lane`). */
 {
+    in: 'lanes';
+    lanes: Record<string, TwinAuthStrategy>;
+}
+/** the key rides in the query string (`?key=…`, `?appid=…`) — no header will do */
+ | {
     in: 'query';
     name: string;
 }
@@ -23,7 +29,10 @@ export type TwinAuthStrategy =
  | {
     in: 'signature';
     algorithm: 'aws-sigv4';
-    scope: (req: {
+    scope: {
+        region: string;
+        service: string;
+    } | ((req: {
         method: string;
         path: string;
         host: string;
@@ -32,7 +41,7 @@ export type TwinAuthStrategy =
     }) => {
         region: string;
         service: string;
-    };
+    });
 }
 /** a signature computed PER REQUEST over bytes only the pack can canonicalize */
  | {

package/dist/src/executor.js

@@ -130,6 +130,14 @@ async function awsSigV4Headers(input) {
     };
 }
 export function buildRemoteExecute(origin, credential, auth, vendorHosts, options = {}) {
+    if (auth?.in === 'lanes') {
+        // each lane's strategy over the same origin and credential, the budget charged once, around them all
+        const own = { ...options, vendor: undefined };
+        const byLane = new Map(Object.entries(auth.lanes).map(([lane, strategy]) => [lane, buildRemoteExecute(origin, credential, strategy, vendorHosts, own)]));
+        const headers = buildRemoteExecute(origin, credential, undefined, vendorHosts, own);
+        const execute = (request) => (byLane.get(request.lane ?? '') ?? headers)(request);
+        return options.vendor === undefined ? execute : budgeted(options.vendor, execute, options.custody?.key ?? JSON.stringify(credential.headers));
+    }
     const execute = auth?.in === 'exchange' ? exchangeExecute(origin, credential, auth, vendorHosts, options.custody) : direct(origin, credential, auth, vendorHosts);
     return options.vendor === undefined ? execute : budgeted(options.vendor, execute, options.custody?.key ?? JSON.stringify(credential.headers));
 }
@@ -234,7 +242,7 @@ function direct(origin, credential, auth, vendorHosts) {
                     throw new Error('remote execute: the aws-sigv4 credential strategy needs `keyId` on the sealed credential, and it is absent');
                 }
                 // the HOST goes with it: an AWS endpoint names its own region, and only the pack knows how
-                const { region, service } = auth.scope({ method, path, host: target.host, headers: Object.fromEntries(outbound.entries()), ...(body === undefined ? {} : { body }) });
+                const { region, service } = typeof auth.scope === 'function' ? auth.scope({ method, path, host: target.host, headers: Object.fromEntries(outbound.entries()), ...(body === undefined ? {} : { body }) }) : auth.scope;
                 const signed = await awsSigV4Headers({ method, url: target, ...(body === undefined ? {} : { body }), keyId, secret, region, service, headers: outbound, at: new Date() });
                 for (const [name, value] of Object.entries(signed))
                     outbound.set(name, value);

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

@@ -16,6 +16,8 @@ export type RemoteExecuteRequest = {
      *  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;
+    /** the lane of a vendor of lanes the request is (its strategy, when its lanes authenticate apart) */
+    lane?: string;
 };
 export type RemoteExecuteResponse = {
     status: number;

package/package.json

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

@@ -111,6 +111,29 @@ function unitOf(units: Unit[], input: Row): Unit | undefined {
     ?? (input.graphql ? units[0] : undefined);
 }
 
+/** The account a root is, before a perform sends a path naming the World's ("The account a root is"): the World's
+ *  account its own doors made, unadopted, adopts the one account the root's credential lists. Read once per deploy (an
+ *  adopted account is not asked again); a list the vendor refuses, or one naming several accounts, adopts none. */
+async function adoptAccount(units: Unit[], execute: RemoteExecute, ctx: PerformContext): Promise<void> {
+  if (ctx.service === undefined) return;
+  for (const u of units) {
+    const m = u.manifest;
+    const decl = m.account ? m.resources[m.account] : undefined;
+    if (!m.account || !decl) continue;
+    const type = storedType(m, m.account);
+    const local = (readTree(ctx.service, ctx.root) as Row[]).filter((r) => r.type === type && r.deleted !== true && ctx.resolve(type, String(r.id)) === String(r.id));
+    const scope = decl.refresh;
+    const op = scope && 'list' in scope ? u.surface.operations.find((o) => o.id === scope.list) : undefined;
+    if (!local.length || !op) continue;
+    const answer = await execute({ method: op.method.toUpperCase(), path: `${op.basePath ?? u.surface.basePath ?? ''}${op.path}`, ...(u.lane ? { lane: u.lane } : {}) });
+    if (answer.status >= 400) continue;
+    const items = itemsOf(op, parse(answer));
+    const id = items.length === 1 ? storedIdOf(decl, items[0]!) : undefined;
+    if (id === undefined || local.some((l) => String(l.id) === id)) continue;
+    observeResources(ctx.service, [{ type, id, fields: items[0] as ObservedResource['fields'], adopts: String(local[0]!.id) }], ctx.root !== undefined ? { root: ctx.root } : {});
+  }
+}
+
 function performOf(units: Unit[]): PerformAction {
   // 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> => {
@@ -159,7 +182,7 @@ function performOf(units: Unit[]): PerformAction {
     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 });
-    const answer = await execute({ method, path, headers, ...(sent.body !== undefined ? { body: sent.body } : {}) });
+    const answer = await execute({ method, path, headers, ...(sent.body !== undefined ? { body: sent.body } : {}), ...(unit.lane ? { lane: unit.lane } : {}) });
     const parsed = parse(answer);
     const shape = refusalShape(m);
     const refused = answer.status >= 400 || (shape.length > 0 && shape.every(([p, v]) => at(parsed, p) === v));
@@ -196,6 +219,7 @@ 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> => {
+    await adoptAccount(units, execute, ctx);
     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
@@ -256,7 +280,8 @@ function refreshOf(units: Unit[], service: string): NonNullable<StateSystemAdapt
   return async (execute, opts) => {
     const observed: ObservedResource[] = [];
     const complete: Completed[] = [];
-    for (const { manifest: m, surface } of units) {
+    for (const unit of units) {
+      const { manifest: m, surface } = unit;
       // parents before children, however deep
       const scoped = Object.entries(m.resources).filter(([, d]) => d.refresh && !('none' in d.refresh));
       const depth = (r: string, seen = new Set<string>()): number => { const p = m.resources[r]?.parent?.resource; return p && !seen.has(p) ? 1 + depth(p, seen.add(r)) : 0; };
@@ -277,7 +302,7 @@ function refreshOf(units: Unit[], service: string): NonNullable<StateSystemAdapt
             // a parent the operation names in its query, not its path (Slack's conversations.history `channel`)
             const byQuery = decl.parent?.param && parent !== undefined && !op.path.includes(`{${decl.parent.param}}`) ? { [decl.parent.param]: String(parent) } : {};
             const q = new URLSearchParams({ ...page, ...byQuery });
-            const answer = await execute({ method: op.method.toUpperCase(), path: [...q].length ? `${path}?${q}` : path });
+            const answer = await execute({ method: op.method.toUpperCase(), path: [...q].length ? `${path}?${q}` : path, ...(unit.lane ? { lane: unit.lane } : {}) });
             if (answer.status === 401 || answer.status === 403) throw new Error(`${answer.status}: the vendor refused the root's credential; nothing folded`);
             if (answer.status === 429) throw new Error(`429: rate limited${answer.headers['retry-after'] ? `, retry after ${answer.headers['retry-after']}s` : ''}`);
             if (answer.status >= 400) throw new Error(`${answer.status}: ${refusalWords(m, parse(answer))}`);

package/src/executor.ts

@@ -21,12 +21,15 @@ import { RateBudget } from './rateBudget.ts';
  * and no sealed credential migrates.
  */
 export type TwinAuthStrategy =
+  /** A vendor of lanes whose lanes authenticate apart (Cloudflare's API by bearer, its R2 by SigV4): a lane named takes
+   *  its own strategy, every other call the sealed headers; the request names its lane (`RemoteExecuteRequest.lane`). */
+  | { in: 'lanes'; lanes: Record<string, TwinAuthStrategy> }
   /** the key rides in the query string (`?key=…`, `?appid=…`) — no header will do */
   | { in: 'query'; name: string }
   /** AWS Signature Version 4 — a signature computed per request over the whole canonical request.
    *  `scope` answers which region and service THIS request is for, because a pack may route several
    *  services over one executor (aws routes six); it is pure and is handed no secret. */
-  | { in: 'signature'; algorithm: 'aws-sigv4'; scope: (req: { method: string; path: string; host: string; headers: Record<string, string>; body?: string | Uint8Array }) => { region: string; service: string } }
+  | { in: 'signature'; algorithm: 'aws-sigv4'; scope: { region: string; service: string } | ((req: { method: string; path: string; host: string; headers: Record<string, string>; body?: string | Uint8Array }) => { region: string; service: string }) }
   /** a signature computed PER REQUEST over bytes only the pack can canonicalize */
   | {
     in: 'signature';
@@ -223,6 +226,14 @@ export type CredentialCustody = { key: string; open: () => Promise<CredentialPay
  *  made, refused when the budget is spent, and settled with the vendor's answer (its back-off honoured). */
 export type RemoteExecuteOptions = { custody?: CredentialCustody; vendor?: string };
 export function buildRemoteExecute(origin: URL, credential: CredentialPayload, auth?: TwinAuthStrategy, vendorHosts?: readonly HostRule[], options: RemoteExecuteOptions = {}): RemoteExecute {
+  if (auth?.in === 'lanes') {
+    // each lane's strategy over the same origin and credential, the budget charged once, around them all
+    const own = { ...options, vendor: undefined };
+    const byLane = new Map(Object.entries(auth.lanes).map(([lane, strategy]) => [lane, buildRemoteExecute(origin, credential, strategy, vendorHosts, own)]));
+    const headers = buildRemoteExecute(origin, credential, undefined, vendorHosts, own);
+    const execute: RemoteExecute = (request) => (byLane.get(request.lane ?? '') ?? headers)(request);
+    return options.vendor === undefined ? execute : budgeted(options.vendor, execute, options.custody?.key ?? JSON.stringify(credential.headers));
+  }
   const execute = auth?.in === 'exchange' ? exchangeExecute(origin, credential, auth, vendorHosts, options.custody) : direct(origin, credential, auth, vendorHosts);
   return options.vendor === undefined ? execute : budgeted(options.vendor, execute, options.custody?.key ?? JSON.stringify(credential.headers));
 }
@@ -242,7 +253,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 {
+function direct(origin: URL, credential: CredentialPayload, auth?: Exclude<TwinAuthStrategy, { in: 'exchange' | 'lanes' }>, vendorHosts?: readonly HostRule[]): RemoteExecute {
   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
@@ -314,7 +325,7 @@ function direct(origin: URL, credential: CredentialPayload, auth?: Exclude<TwinA
           throw new Error('remote execute: the aws-sigv4 credential strategy needs `keyId` on the sealed credential, and it is absent');
         }
         // the HOST goes with it: an AWS endpoint names its own region, and only the pack knows how
-        const { region, service } = auth.scope({ method, path, host: target.host, headers: Object.fromEntries(outbound.entries()), ...(body === undefined ? {} : { body }) });
+        const { region, service } = typeof auth.scope === 'function' ? auth.scope({ method, path, host: target.host, headers: Object.fromEntries(outbound.entries()), ...(body === undefined ? {} : { body }) }) : auth.scope;
         const signed = await awsSigV4Headers({ method, url: target, ...(body === undefined ? {} : { body }), keyId, secret, region, service, headers: outbound, at: new Date() });
         for (const [name, value] of Object.entries(signed)) outbound.set(name, value);
       } else {

package/src/remote-execute.ts

@@ -20,6 +20,8 @@ export type RemoteExecuteRequest = {
    *  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;
+  /** the lane of a vendor of lanes the request is (its strategy, when its lanes authenticate apart) */
+  lane?: string;
 };
 export type RemoteExecuteResponse = {
   status: number;