@volter/world-core 3.0.140 → 3.0.142

package/dist/src/head.js

@@ -233,6 +233,9 @@ export class RefusedWriteError extends Error {
 export class HeadError extends Error {
     constructor(message) { super(message); this.name = 'HeadError'; }
 }
+/** A selected live request can retry after the earlier write finishes; its local group must roll back. */
+class DeploymentOrderError extends HeadError {
+}
 /** The vendor refused or failed the write: the entry is in the log as failed, with the vendor's words. */
 export class VendorWriteError extends Error {
     actionId;
@@ -323,24 +326,10 @@ async function performNow(opts) {
     const adapters = opts.adapters ?? stateSystemFor(vendor) ?? stateSystemFor(service);
     if (!adapters?.perform)
         throw new Error(`the ${vendor} twin has no perform adapter — a pack names one in its descriptor and registers itself (registerPack)`);
-    // the caller's executor, or the one built over the sealed credential; an unsealed root has no other
-    const execute = opts.execute ?? buildRemoteExecute(validateRemoteOrigin(bound.sealed.url, { allowInsecureLoopback: true }), await openRootCredential(bound.sealed, vendor), authStrategyFor(vendor), getPack(vendor)?.hosts, { custody: rootCustody(bound.sealed, vendor), vendor });
-    // an unsealed root's World is where its state resolves (the root given, PROJECT_ROOT, or the working directory)
-    const checks = opts.checks ?? (await loadChecks(bound.sealed ? worldRootOf(bound.sealed) : worldPaths(service, root).root));
     const settling = settlingEntries(service, root);
-    const pick = (list) => (opts.actionIds === undefined ? list : opts.actionIds.map((id) => list.find((a) => a.id === id)).filter((a) => a !== undefined));
-    const report = { pushed: 0, deployed: [], skipped: [], replayed: [], worldOnly: pick(settling.worldOnly).map((e) => e.id) };
-    if (opts.actionIds) {
-        const settled = receiptsByEntry(parentEntries(service, root));
-        for (const id of opts.actionIds)
-            if (settled.get(id)?.status === 'deployed')
-                report.replayed.push(id);
-    }
-    const settle = (action, at, receipt, fields = action.fields ?? {}, vendorSubjectId) => {
-        confirmAction({ service, actionId: action.id, subject: action.subject, fields, occurredAt: at, ...(vendorSubjectId ? { vendorSubjectId } : {}), receipt, ...(root !== undefined ? { root } : {}) });
-    };
-    // the subjects the vendor refused and never took: a request naming one is the World's alone, never sent (the
-    // real-system adapters, "Perform" 3), settled as it landed here
+    const selected = opts.actionIds === undefined ? undefined : new Set(opts.actionIds);
+    const pick = (list) => selected === undefined ? list : list.filter((action) => selected.has(action.id));
+    // Classify the World's own writes before enforcing vendor order, using the same rules as settlement below.
     const parent = parentEntries(service, root);
     const taken = new Set();
     const refusedIds = new Set();
@@ -357,26 +346,60 @@ async function performNow(opts) {
     else if (v && typeof v === 'object')
         for (const x of Object.values(v))
             walk(x); }; const i = (action.input ?? {}); walk(i.path); walk(i.query); walk(i.body); return out; };
+    const ownWrite = (group, refused) => {
+        const unsent = adapters.unsent?.(group[0].input);
+        if (unsent)
+            return { reason: unsent, refusedSubject: false };
+        return named(group[0]).some((v) => refused.has(v)) ? { reason: 'names a subject the vendor refused: the World\'s alone', refusedSubject: true } : undefined;
+    };
+    const classifiedOwn = new Map();
+    if (selected !== undefined) {
+        const orderingRefused = new Set(refusedIds);
+        const offered = groupsOf(settling.offered).filter((group) => {
+            const own = ownWrite(group, orderingRefused);
+            if (!own)
+                return true;
+            for (const action of group)
+                classifiedOwn.set(action.id, own);
+            if (own.refusedSubject)
+                for (const action of group)
+                    orderingRefused.add(action.subject.id);
+            return false;
+        }).flat();
+        const last = offered.reduce((index, action, at) => selected.has(action.id) ? at : index, -1);
+        const earlier = offered.slice(0, last + 1).find((action) => !selected.has(action.id));
+        if (earlier)
+            throw new DeploymentOrderError(`the ${service} twin has an earlier undeployed entry (${earlier.operation ?? earlier.subject.type}, ${earlier.id}); deploy its changeset first. Selected deployment cannot skip earlier writes on the same vendor.`);
+    }
+    // the caller's executor, or the one built over the sealed credential; an unsealed root has no other
+    const execute = opts.execute ?? buildRemoteExecute(validateRemoteOrigin(bound.sealed.url, { allowInsecureLoopback: true }), await openRootCredential(bound.sealed, vendor), authStrategyFor(vendor), getPack(vendor)?.hosts, { custody: rootCustody(bound.sealed, vendor), vendor });
+    // an unsealed root's World is where its state resolves (the root given, PROJECT_ROOT, or the working directory)
+    const checks = opts.checks ?? (await loadChecks(bound.sealed ? worldRootOf(bound.sealed) : worldPaths(service, root).root));
+    const report = { pushed: 0, deployed: [], skipped: [], replayed: [], worldOnly: pick(settling.worldOnly).map((e) => e.id) };
+    if (opts.actionIds) {
+        const settled = receiptsByEntry(parentEntries(service, root));
+        for (const id of opts.actionIds)
+            if (settled.get(id)?.status === 'deployed')
+                report.replayed.push(id);
+    }
+    const settle = (action, at, receipt, fields = action.fields ?? {}, vendorSubjectId) => {
+        confirmAction({ service, actionId: action.id, subject: action.subject, fields, occurredAt: at, ...(vendorSubjectId ? { vendorSubjectId } : {}), receipt, ...(root !== undefined ? { root } : {}) });
+    };
+    // the subjects the vendor refused and never took: a request naming one is the World's alone, never sent (the
+    // real-system adapters, "Perform" 3), settled as it landed here
     let stopped = false;
     for (const group of groupsOf(pick(settling.offered))) {
         if (stopped) {
             report.skipped.push(...group.map((a) => a.id));
             continue;
         }
-        // a write of a unit the pack sends nowhere (`vendorBacked.none` beside vendor-backed lanes) is the World's alone
-        const unsent = adapters.unsent?.(group[0].input);
-        if (unsent) {
-            const at = opts.at ?? worldNow();
-            for (const action of group)
-                settle(action, at, { status: 'landed', reason: unsent });
-            report.worldOnly.push(...group.map((a) => a.id));
-            continue;
-        }
-        if (named(group[0]).some((v) => refusedIds.has(v))) {
+        const own = classifiedOwn.get(group[0].id) ?? ownWrite(group, refusedIds);
+        if (own) {
             const at = opts.at ?? worldNow();
             for (const action of group) {
-                settle(action, at, { status: 'landed', reason: 'names a subject the vendor refused: the World\'s alone' });
-                refusedIds.add(action.subject.id);
+                settle(action, at, { status: 'landed', reason: own.reason });
+                if (own.refusedSubject)
+                    refusedIds.add(action.subject.id);
             }
             report.worldOnly.push(...group.map((a) => a.id));
             continue;
@@ -457,6 +480,10 @@ export async function performAtHead(service, action, root) {
         report = await performEntries({ service, actionIds: [action.id], ...(root !== undefined ? { root } : {}) });
     }
     catch (error) {
+        if (error instanceof DeploymentOrderError) {
+            revertAction({ service, actionId: action.id, occurredAt: worldNow(), ...(root !== undefined ? { root } : {}) });
+            throw new VendorWriteError(`An earlier ${service} write is still pending; this request was rolled back before reaching the vendor. Retry after that write finishes.`, action.id);
+        }
         throw error instanceof HeadError ? error : new HeadError(error instanceof Error ? error.message : String(error));
     }
     // under live use an entry the vendor did not take does not stay in the tree: the app was told no, the
@@ -502,6 +529,11 @@ export async function performRequestGroup(service, request, root) {
         report = await performEntries({ service, actionIds: group.map((e) => e.id), ...(root !== undefined ? { root } : {}) });
     }
     catch (error) {
+        if (error instanceof DeploymentOrderError) {
+            for (const e of [...group].reverse())
+                revertAction({ service, actionId: e.id, occurredAt: worldNow(), ...(root !== undefined ? { root } : {}) });
+            return new VendorWriteError(`An earlier ${service} write is still pending; this request was rolled back before reaching the vendor. Retry after that write finishes.`, group[0].id);
+        }
         throw error instanceof HeadError ? error : new HeadError(error instanceof Error ? error.message : String(error));
     }
     if (report.refused || report.failed) {

package/package.json

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

@@ -247,6 +247,9 @@ export class RefusedWriteError extends Error {
 export class HeadError extends Error {
   constructor(message: string) { super(message); this.name = 'HeadError'; }
 }
+
+/** A selected live request can retry after the earlier write finishes; its local group must roll back. */
+class DeploymentOrderError extends HeadError {}
 /** The vendor refused or failed the write: the entry is in the log as failed, with the vendor's words. */
 export class VendorWriteError extends Error {
   constructor(message: string, readonly actionId: string) { super(message); this.name = 'VendorWriteError'; }
@@ -355,12 +358,38 @@ async function performNow(opts: Parameters<typeof performEntries>[0]): Promise<D
   const vendor = bound.vendor;
   const adapters = opts.adapters ?? stateSystemFor(vendor) ?? stateSystemFor(service);
   if (!adapters?.perform) throw new Error(`the ${vendor} twin has no perform adapter — a pack names one in its descriptor and registers itself (registerPack)`);
+  const settling = settlingEntries(service, root);
+  const selected = opts.actionIds === undefined ? undefined : new Set(opts.actionIds);
+  const pick = (list: TwinAction[]): TwinAction[] => selected === undefined ? list : list.filter((action) => selected.has(action.id));
+  // Classify the World's own writes before enforcing vendor order, using the same rules as settlement below.
+  const parent = parentEntries(service, root);
+  const taken = new Set<string>(); const refusedIds = new Set<string>();
+  for (const e of parent) { if (e.receipt?.status === 'deployed') taken.add(e.aliasOf ?? e.subject.id); else if (e.receipt?.status === 'refused') refusedIds.add(e.subject.id); }
+  for (const id of taken) refusedIds.delete(id);
+  const named = (action: TwinAction): string[] => { const out: string[] = []; const walk = (v: unknown): void => { if (typeof v === 'string') out.push(v); else if (v && typeof v === 'object') for (const x of Object.values(v)) walk(x); }; const i = (action.input ?? {}) as Record<string, unknown>; walk(i.path); walk(i.query); walk(i.body); return out; };
+  const ownWrite = (group: TwinAction[], refused: Set<string>): { reason: string; refusedSubject: boolean } | undefined => {
+    const unsent = adapters.unsent?.(group[0]!.input as Record<string, unknown> | undefined);
+    if (unsent) return { reason: unsent, refusedSubject: false };
+    return named(group[0]!).some((v) => refused.has(v)) ? { reason: 'names a subject the vendor refused: the World\'s alone', refusedSubject: true } : undefined;
+  };
+  const classifiedOwn = new Map<string, { reason: string; refusedSubject: boolean }>();
+  if (selected !== undefined) {
+    const orderingRefused = new Set(refusedIds);
+    const offered = groupsOf(settling.offered).filter((group) => {
+      const own = ownWrite(group, orderingRefused);
+      if (!own) return true;
+      for (const action of group) classifiedOwn.set(action.id, own);
+      if (own.refusedSubject) for (const action of group) orderingRefused.add(action.subject.id);
+      return false;
+    }).flat();
+    const last = offered.reduce((index, action, at) => selected.has(action.id) ? at : index, -1);
+    const earlier = offered.slice(0, last + 1).find((action) => !selected.has(action.id));
+    if (earlier) throw new DeploymentOrderError(`the ${service} twin has an earlier undeployed entry (${earlier.operation ?? earlier.subject.type}, ${earlier.id}); deploy its changeset first. Selected deployment cannot skip earlier writes on the same vendor.`);
+  }
   // the caller's executor, or the one built over the sealed credential; an unsealed root has no other
   const execute = opts.execute ?? buildRemoteExecute(validateRemoteOrigin(bound.sealed!.url, { allowInsecureLoopback: true }), await openRootCredential(bound.sealed!, vendor), authStrategyFor(vendor), getPack(vendor)?.hosts, { custody: rootCustody(bound.sealed!, vendor), vendor });
   // an unsealed root's World is where its state resolves (the root given, PROJECT_ROOT, or the working directory)
   const checks = opts.checks ?? (await loadChecks(bound.sealed ? worldRootOf(bound.sealed) : worldPaths(service, root).root));
-  const settling = settlingEntries(service, root);
-  const pick = (list: TwinAction[]): TwinAction[] => (opts.actionIds === undefined ? list : opts.actionIds.map((id) => list.find((a) => a.id === id)).filter((a): a is TwinAction => a !== undefined));
   const report: DeployReport = { pushed: 0, deployed: [], skipped: [], replayed: [], worldOnly: pick(settling.worldOnly).map((e) => e.id) };
   if (opts.actionIds) {
     const settled = receiptsByEntry(parentEntries(service, root));
@@ -371,25 +400,13 @@ async function performNow(opts: Parameters<typeof performEntries>[0]): Promise<D
   };
   // the subjects the vendor refused and never took: a request naming one is the World's alone, never sent (the
   // real-system adapters, "Perform" 3), settled as it landed here
-  const parent = parentEntries(service, root);
-  const taken = new Set<string>(); const refusedIds = new Set<string>();
-  for (const e of parent) { if (e.receipt?.status === 'deployed') taken.add(e.aliasOf ?? e.subject.id); else if (e.receipt?.status === 'refused') refusedIds.add(e.subject.id); }
-  for (const id of taken) refusedIds.delete(id);
-  const named = (action: TwinAction): string[] => { const out: string[] = []; const walk = (v: unknown): void => { if (typeof v === 'string') out.push(v); else if (v && typeof v === 'object') for (const x of Object.values(v)) walk(x); }; const i = (action.input ?? {}) as Record<string, unknown>; walk(i.path); walk(i.query); walk(i.body); return out; };
   let stopped = false;
   for (const group of groupsOf(pick(settling.offered))) {
     if (stopped) { report.skipped.push(...group.map((a) => a.id)); continue; }
-    // a write of a unit the pack sends nowhere (`vendorBacked.none` beside vendor-backed lanes) is the World's alone
-    const unsent = adapters.unsent?.(group[0]!.input as Record<string, unknown> | undefined);
-    if (unsent) {
-      const at = opts.at ?? worldNow();
-      for (const action of group) settle(action, at, { status: 'landed', reason: unsent });
-      report.worldOnly.push(...group.map((a) => a.id));
-      continue;
-    }
-    if (named(group[0]!).some((v) => refusedIds.has(v))) {
+    const own = classifiedOwn.get(group[0]!.id) ?? ownWrite(group, refusedIds);
+    if (own) {
       const at = opts.at ?? worldNow();
-      for (const action of group) { settle(action, at, { status: 'landed', reason: 'names a subject the vendor refused: the World\'s alone' }); refusedIds.add(action.subject.id); }
+      for (const action of group) { settle(action, at, { status: 'landed', reason: own.reason }); if (own.refusedSubject) refusedIds.add(action.subject.id); }
       report.worldOnly.push(...group.map((a) => a.id));
       continue;
     }
@@ -453,7 +470,13 @@ export async function performAtHead(service: string, action: Pick<TwinAction, 'i
   if (head.kind !== 'real' || head.deploy !== 'auto') return { performed: false };
   let report: DeployReport;
   try { report = await performEntries({ service, actionIds: [action.id], ...(root !== undefined ? { root } : {}) }); }
-  catch (error) { throw error instanceof HeadError ? error : new HeadError(error instanceof Error ? error.message : String(error)); }
+  catch (error) {
+    if (error instanceof DeploymentOrderError) {
+      revertAction({ service, actionId: action.id, occurredAt: worldNow(), ...(root !== undefined ? { root } : {}) });
+      throw new VendorWriteError(`An earlier ${service} write is still pending; this request was rolled back before reaching the vendor. Retry after that write finishes.`, action.id);
+    }
+    throw error instanceof HeadError ? error : new HeadError(error instanceof Error ? error.message : String(error));
+  }
   // under live use an entry the vendor did not take does not stay in the tree: the app was told no, the
   // world says no — a revert lands (the receipt stays on the original, so the log shows what happened)
   const undone = report.refused?.actionId === action.id || report.failed?.actionId === action.id;
@@ -485,7 +508,13 @@ export async function performRequestGroup(service: string, request: string, root
   if (!group.length) return { ids };
   let report: DeployReport;
   try { report = await performEntries({ service, actionIds: group.map((e) => e.id), ...(root !== undefined ? { root } : {}) }); }
-  catch (error) { throw error instanceof HeadError ? error : new HeadError(error instanceof Error ? error.message : String(error)); }
+  catch (error) {
+    if (error instanceof DeploymentOrderError) {
+      for (const e of [...group].reverse()) revertAction({ service, actionId: e.id, occurredAt: worldNow(), ...(root !== undefined ? { root } : {}) });
+      return new VendorWriteError(`An earlier ${service} write is still pending; this request was rolled back before reaching the vendor. Retry after that write finishes.`, group[0]!.id);
+    }
+    throw error instanceof HeadError ? error : new HeadError(error instanceof Error ? error.message : String(error));
+  }
   if (report.refused || report.failed) {
     for (const e of [...group].reverse()) revertAction({ service, actionId: e.id, occurredAt: worldNow(), ...(root !== undefined ? { root } : {}) });
     return report.refused ? new RefusedWriteError(report.refused.check, report.refused.reason, report.refused.actionId) : new VendorWriteError(report.failed!.error, report.failed!.actionId);