@real-life/trust-protocol 0.4.0 → 0.6.0

package/dist/adapters/vti-mediator.js

@@ -1,17 +1,36 @@
 // RLTP transport adapter: VTI mediator — published as
 // @real-life/trust-protocol/adapters/vti-mediator (lib Stage 2, note §4.6).
 //
-// Its reports reach the holder as the ports' DeliveryReport: submitOutbound
-// files an Outbound under its document digest and returns the
-// SubmissionRef (submission id ↔ digest); report(id) maps the adapter's
-// SubmissionState onto DeliveryReport (deliveryReportOf), which the app
-// hands to holder.report(). An adapter's `delivered` is its claim about
-// transport; the holder's receive core verifies the delivery-ack itself.
+// It takes the holder's documents from the holder's custody (Delivery 0.83
+// RLTP-DEL-6120 to 6135, lib 0.6.0): reconcile(view, gate, now) files every
+// entry of holder.pendingTransport(when) not yet filed, and withdraws every
+// filed submission still before the trias whose digest the view no longer
+// names — a missing entry means stop, never keep sending. Before every
+// deposit it asks gate.mayHandOver(entry, now) (the holder): false
+// withdraws the submission, an error skips the attempt. It keeps no
+// custody of its own: its copies are volatile and bound to the holder's
+// opening: bound to the holder of its first reconcile, it refuses another,
+// so after holder.close() nothing it holds goes out, and the next opening
+// gets a new adapter (restored from ackState like any other). Its give-up horizon counts
+// from the entry's first submission (`since`), never from when it took the
+// entry over (RLTP-DEL-6130). Its reports reach the holder as the ports'
+// DeliveryReport: report(id) maps the adapter's SubmissionState onto
+// DeliveryReport (deliveryReportOf), keyed by the document digest, which
+// the app hands to holder.report(). An adapter's `delivered` is its claim
+// about transport; the holder's receive core verifies the delivery-ack
+// itself.
 //
 // Profile: spec/adapter-vti-mediator.md v0.23 (twenty-third casting;
 // round journals under design/adapter-review*). A
 // transport adapter contract — NOT a carrier at the port.
 //
+// Beyond the profile (lib 0.5.0): conclude(collection, now, {keep}) leaves
+// the items whose disposition is transient unconcluded and offers them
+// again (Delivery 0.82 RLTP-DEL-5810, 5820: failed(rate-limited) is never
+// concluded); `concludable(result)` says which receive outcomes are
+// terminal. The profile's §4 concludes a collection whole; its next
+// casting is to take this up.
+//
 // Structural rules (reviews 3+4):
 //   · No port operation ever awaits the mediator — including
 //     register: keylist synchronization is a recorded intent with a
@@ -26,14 +45,15 @@ import { jcs } from '../core.js';
 import { sha } from '../crypto.js';
 import { carrierPrincipal, carrierScopedIdentity } from '../carrier-identity.js';
 // ── Declared constants (profile §2) — promises of THIS casting ──────
-export const DECLARED = {
+// frozen: the declared promises cannot be changed at run time either
+export const DECLARED = Object.freeze({
     giveUpHorizonMs: 72 * 3_600_000,
     statusHorizonMs: 60_000,
     queueFloorCount: 64,
     queueFloorBytes: 1_048_576,
     maxQueueBytes: 16_777_216,
     duplicateWindowMs: 30 * 86_400_000,
-};
+});
 export class WireError extends Error {
     kind;
     constructor(kind, message) {
@@ -59,6 +79,16 @@ export function deliveryReportOf(digest, st) {
             : { digest, status: 'failed', reason: st.reason };
     }
 }
+/** Whether a receive outcome is terminal and its item may be concluded
+ *  (Delivery 5a.8): every disposition but `failed(rate-limited)`, the one
+ *  failure that is transient (RLTP-DEL-5820). An InfraError of the
+ *  holder's store is transient as well (RLTP-DEL-5810): an item whose
+ *  receive threw is kept, too. */
+export function concludable(r) {
+    return !(r.disposition === 'failed' && r.reason === 'rate-limited');
+}
+/** The adapter's own copy of a wire's token set: the wire keeps no handle on it. */
+const tokenCopy = (t) => ({ accessToken: t.accessToken, accessExpiresAt: t.accessExpiresAt, refreshToken: t.refreshToken, refreshExpiresAt: t.refreshExpiresAt });
 const hex = (b) => Array.from(b, (x) => x.toString(16).padStart(2, '0')).join('');
 // construction capability: only create() holds it
 const KEY = Symbol('MediatorCarrierAdapter.create');
@@ -77,6 +107,8 @@ export class MediatorCarrierAdapter {
     #tokens = null;
     #clock = Number.NEGATIVE_INFINITY;
     #closed = false;
+    /** the opening this adapter serves, bound at its first reconcile */
+    #gate = null;
     #subs = new Map();
     #inflight = new Set();
     #nextId = 1;
@@ -161,7 +193,8 @@ export class MediatorCarrierAdapter {
         this.#wire.onDeliver(async (raw) => {
             if (this.#closed)
                 return;
-            const bytes = raw.slice();
+            // a plain copy of its own: a Node Buffer's slice() would share memory
+            const bytes = new Uint8Array(raw);
             const queueId = hex(await sha(bytes));
             if (this.#closed)
                 return;
@@ -229,7 +262,7 @@ export class MediatorCarrierAdapter {
                     const refreshed = await this.#wire.refresh(this.#tokens.refreshToken);
                     if (this.#closed)
                         throw new Error('retired'); // as on the handshake path (R6-B1)
-                    this.#tokens = refreshed;
+                    this.#tokens = tokenCopy(refreshed);
                     return this.#tokens.accessToken;
                 }
                 catch (e) {
@@ -247,7 +280,7 @@ export class MediatorCarrierAdapter {
             const { challenge, sessionId } = await this.#wire.authChallenge(this.#connectionDid);
             if (this.#closed)
                 throw new Error('retired'); // nothing new starts, not even the answer (R6-B1)
-            this.#tokens = await this.#wire.authenticate({ did: this.#connectionDid, challenge, sessionId });
+            this.#tokens = tokenCopy(await this.#wire.authenticate({ did: this.#connectionDid, challenge, sessionId }));
             return this.#tokens.accessToken;
         })();
         this.#authing = run.finally(() => { this.#authing = null; });
@@ -278,7 +311,7 @@ export class MediatorCarrierAdapter {
                 const token = await this.#ensureAuth(now);
                 if (this.#closed)
                     return;
-                await this.#wire.keylistUpdate(token, wanted);
+                await this.#wire.keylistUpdate(token, [...wanted]); // the wire's own list: `wanted` is compared below
                 // land only if the desire has not moved meanwhile
                 if (!this.#closed && this.#desiredRkids !== null &&
                     wanted.join(' ') === this.#desiredRkids.join(' ')) {
@@ -303,7 +336,9 @@ export class MediatorCarrierAdapter {
         const id = 's' + this.#nextId++;
         const knownOffline = this.#wire.offline?.() === true;
         const sub = {
-            bytes: envelopeBytes.slice(),
+            id,
+            // a plain copy of its own (a Node Buffer's slice() shares memory)
+            bytes: new Uint8Array(envelopeBytes),
             submittedAt: now,
             attemptStartedAt: null,
             lastKind: null,
@@ -314,16 +349,79 @@ export class MediatorCarrierAdapter {
             this.#startAttempt(sub, now);
         return id;
     }
-    /** Files an Outbound (its envelope as JCS bytes) and returns the
-     *  SubmissionRef the holder's reports are keyed by: submission id ↔
-     *  document digest (note §4.3). */
-    submitOutbound(outbound, rawNow) {
+    /** Takes the holder's custody set (holder.pendingTransport, after a
+     *  resume of this opening) and the holder as the gate: files every entry
+     *  not yet filed under its digest (its envelope as JCS bytes; the give-up
+     *  horizon from entry.since) and returns their SubmissionRefs; withdraws
+     *  every filed submission still before the trias (no report, or
+     *  awaiting-transport) whose digest the view does not name. Accepted and
+     *  terminal submissions stay for their reports. */
+    reconcile(view, gate, rawNow) {
         this.#open();
-        if (typeof outbound?.digest !== 'string' || outbound.digest === '')
-            throw new Error('an outbound needs its document digest');
-        const submissionId = this.submit(new TextEncoder().encode(jcs(outbound.envelope)), rawNow);
-        this.#subs.get(submissionId).digest = outbound.digest;
-        return { submissionId, digest: outbound.digest };
+        if (view?.ok !== true || !Array.isArray(view.entries))
+            throw new Error('reconcile needs a view of holder.pendingTransport');
+        if (typeof gate?.handOver !== 'function')
+            throw new Error('reconcile needs the holder as its gate');
+        // one adapter per opening: its copies and the holder's grants belong to
+        // that opening, and the next opening gets an adapter of its own
+        if (this.#gate === null)
+            this.#gate = gate;
+        else if (this.#gate !== gate)
+            throw new Error('one adapter per opening: this adapter reconciles with another holder (create a new adapter for the next opening)');
+        const now = this.#now(rawNow);
+        // a submission's key: the digest, and for a duplicate's answer its
+        // grant too — the retries and each answer are hand-overs of their own
+        const keyOf = (digest, resend) => resend === undefined ? digest : `${digest}#${resend}`;
+        const named = new Set(view.entries.map((e) => keyOf(e.digest, e.resend)));
+        const filed = new Map();
+        for (const [id, sub] of this.#subs) {
+            if (sub.digest === undefined)
+                continue;
+            const key = keyOf(sub.digest, sub.entry?.resend);
+            const before = sub.st === null || sub.st.state === 'awaiting-transport';
+            if (before && !named.has(key)) {
+                this.#subs.delete(id);
+                continue;
+            }
+            filed.set(key, sub);
+        }
+        const refs = [];
+        for (const entry of view.entries) {
+            const had = filed.get(keyOf(entry.digest, entry.resend));
+            if (had !== undefined) {
+                // the newest entry of a live submission is the one its gate checks
+                if (had.st === null || had.st.state === 'awaiting-transport') {
+                    had.entry = entry;
+                    had.gate = gate;
+                    continue;
+                }
+                // an answer the holder still offers is still owed — its hand-over
+                // never began, or the holder could not record that it did: a
+                // terminal submission of it is filed again (the holder ends it)
+                if (entry.resend === undefined)
+                    continue;
+                this.#subs.delete(had.id);
+            }
+            const id = 's' + this.#nextId++;
+            const sub = {
+                id, digest: entry.digest, entry, gate,
+                bytes: new TextEncoder().encode(jcs(entry.envelope)),
+                // a duplicate's ack is a hand-over of its own, from now
+                submittedAt: entry.resend !== undefined ? now : Math.min(entry.since, now),
+                attemptStartedAt: null, lastKind: null, st: null,
+            };
+            this.#subs.set(id, sub);
+            refs.push({ submissionId: id, digest: entry.digest });
+            // taken over past its horizon (counted from the first submission,
+            // RLTP-DEL-6130): given up at once, never attempted
+            if (now - sub.submittedAt >= DECLARED.giveUpHorizonMs) {
+                sub.st = { state: 'failed', reason: 'expired-by-adapter-policy' };
+                continue;
+            }
+            if (this.#wire.offline?.() !== true)
+                this.#startAttempt(sub, now);
+        }
+        return refs;
     }
     /** The current state as the ports' DeliveryReport for holder.report(),
      *  or null while no honest report exists (and for an unknown id). A
@@ -334,7 +432,7 @@ export class MediatorCarrierAdapter {
             return null;
         const digest = this.#subs.get(id).digest;
         if (digest === undefined)
-            throw new Error('submitted without a document digest: use submitOutbound');
+            throw new Error('submitted without a document digest: file holder documents through reconcile');
         return deliveryReportOf(digest, st);
     }
     has(id) {
@@ -355,7 +453,56 @@ export class MediatorCarrierAdapter {
             const token = await this.#ensureAuth(now);
             if (this.#closed)
                 return; // retirement between auth and deposit: nothing new starts (R5-B2)
-            await this.#wire.deposit(token, sub.bytes, this.#egressDid);
+            // each attempt hands the wire a copy: what it does with it never reaches the next
+            const deposit = () => {
+                try {
+                    return this.#wire.deposit(token, new Uint8Array(sub.bytes), this.#egressDid);
+                }
+                catch (e) {
+                    return Promise.reject(e);
+                }
+            };
+            if (sub.gate !== undefined) {
+                // the holder decides, and the deposit starts in the same step of its
+                // queue (Delivery RLTP-DEL-6125 to 6135); the adapter re-checks its
+                // own state there: retired, withdrawn, past the trias, past the
+                // entry's deadline or its own horizon → no deposit
+                // the deposit's outcome, caught at once: the holder's step may still
+                // be committing when the wire answers
+                let started = null;
+                let declined = false;
+                const entry = sub.entry;
+                const start = () => {
+                    if (this.#closed || this.#subs.get(sub.id) !== sub || sub.gate.closed === true ||
+                        (sub.st !== null && sub.st.state !== 'awaiting-transport') || this.#clock >= entry.notAfter ||
+                        this.#clock - sub.submittedAt >= DECLARED.giveUpHorizonMs) {
+                        declined = true;
+                        return false;
+                    }
+                    started = deposit().then(() => null, (e) => ({ failed: e }));
+                    return true;
+                };
+                let ok;
+                try {
+                    ok = await sub.gate.handOver(entry, this.#clock, start);
+                }
+                catch {
+                    ok = null;
+                }
+                if (started === null) {
+                    // the holder said no: withdrawn; the adapter declined or the
+                    // holder was unreachable: not this attempt
+                    if (ok === false && !declined && this.#subs.get(sub.id) === sub)
+                        this.#subs.delete(sub.id);
+                    return;
+                }
+                const outcome = await started;
+                if (outcome !== null)
+                    throw outcome.failed;
+            }
+            else {
+                await deposit();
+            }
             sub.lastKind = null;
             next = { state: 'accepted' };
         }
@@ -406,7 +553,7 @@ export class MediatorCarrierAdapter {
         if (!sub)
             return null;
         if (sub.st !== null && sub.st.state !== 'awaiting-transport')
-            return sub.st;
+            return { ...sub.st };
         if (this.#wire.offline?.() === true) {
             return { state: 'awaiting-transport', reason: 'offline' };
         }
@@ -414,7 +561,7 @@ export class MediatorCarrierAdapter {
             this.#clock - sub.attemptStartedAt >= DECLARED.statusHorizonMs) {
             return { state: 'awaiting-transport', reason: 'transport-unreachable' };
         }
-        return sub.st;
+        return sub.st === null ? null : { ...sub.st };
     }
     acknowledged(id) {
         if (this.#closed)
@@ -469,17 +616,33 @@ export class MediatorCarrierAdapter {
         this.#inboxDigests.clear();
         const id = 'c' + this.#nextColId++;
         this.#outstanding.set(id, new Map(items.map((i) => [i.queueId, i])));
-        return { id, items: items.map((i) => ({ ...i })) };
+        // the caller gets its own copies: the outstanding entries stay intact,
+        // whatever it does with the bytes, for a conclusion that keeps them
+        return { id, items: items.map((i) => ({ ...i, bytes: new Uint8Array(i.bytes) })) };
     }
-    conclude(collection, rawNow) {
+    /** Concludes a collection (profile §4, Delivery 5a.8): its items'
+     *  digests become ack intent. `keep` names the items whose disposition
+     *  is transient (Delivery RLTP-DEL-5810, 5820: `failed(rate-limited)`,
+     *  or a transaction that could not commit, see `concludable`): they are
+     *  not concluded and not acknowledged, they go back to the buffer and the
+     *  next collect offers them again, and the mediator keeps its copy. */
+    conclude(collection, rawNow, opts = {}) {
         this.#open();
         const now = this.#now(rawNow);
         const col = this.#outstanding.get(collection.id);
         if (!col)
             return;
         this.#outstanding.delete(collection.id);
+        const keep = new Set(opts.keep ?? []);
         for (const item of col.values()) {
             this.#outstandingBytes -= item.bytes.length;
+            if (keep.has(item.queueId)) {
+                // transient: back to the buffer, offered again, never acknowledged
+                this.#inbox.push(item);
+                this.#inboxBytes += item.bytes.length;
+                this.#inboxDigests.add(item.queueId);
+                continue;
+            }
             this.#concluded.set(item.queueId, now);
             this.#pendingAcks.add(item.queueId);
         }
@@ -531,7 +694,8 @@ export class MediatorCarrierAdapter {
             for (const id of live)
                 this.#flightAcks.add(id);
             try {
-                await this.#wire.ackReceived(token, live);
+                // the wire gets its own list: what it does with it never reaches the bookkeeping below
+                await this.#wire.ackReceived(token, [...live]);
                 if (!this.#closed)
                     for (const id of live)
                         this.#pendingAcks.delete(id);