@toa.io/extensions.convergence 1.0.0-alpha.298 → 1.0.0-alpha.299

package/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2020-present Artem Gurtovoi
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/extensions.convergence",
-  "version": "1.0.0-alpha.298",
+  "version": "1.0.0-alpha.299",
   "type": "module",
   "description": "Toa Convergence extension",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -28,10 +28,11 @@
     "transpile": "tsc"
   },
   "dependencies": {
-    "@toa.io/core": "1.0.0-alpha.293",
-    "@toa.io/definitions": "1.0.0-alpha.298",
+    "@toa.io/core": "1.0.0-alpha.299",
+    "@toa.io/definitions": "1.0.0-alpha.299",
     "@toa.io/generic": "1.0.0-alpha.292",
-    "@toa.io/pointer": "1.0.0-alpha.293",
+    "@toa.io/pointer": "1.0.0-alpha.299",
     "openspan": "1.0.0-alpha.293"
-  }
+  },
+  "gitHead": "2ba95b16f2cf06f82d6ff8d436761e843e5e4b43"
 }

package/readme.md

@@ -5,39 +5,51 @@ entity state.
 
 ## Declaration
 
-A region is a deployment of the context, not a variant of it: one context declares every region
-there is, at its root.
+A region is a deployment of the context, and **the environment is which region it is** — the
+same thing that already decides which database and which broker it uses. So a context declares
+one of these per region, and they share nothing:
 
 ```yaml
 # context.toa.yaml
-convergence:
-  - region: eu
-    priority: 0 # a rank: 0 outranks 1
-    binding:
-      provider: amqp
-      pointer: [amqp://cnv-eu-0.example.com, amqp://cnv-eu-1.example.com]
-  - region: us
-    priority: 1
-    binding: { provider: amqp, pointer: amqp://cnv-us.example.com }
+mongodb@eu: mongodb://mongo.eu.example.com/store
+mongodb@us: mongodb://mongo.us.example.com/store
+
+convergence@eu:
+  priority: 0 # a rank: 0 outranks 1
+  binding:
+    provider: amqp
+    pointer: [amqp://cnv-eu-0.example.com, amqp://cnv-eu-1.example.com]
+
+convergence@us:
+  priority: 1
+  binding: { provider: amqp, pointer: amqp://cnv-us.example.com }
 ```
 
+```shell
+$ toa deploy eu
+```
+
+An environment that declares no `convergence` is not a region and converges nothing, so the
+same context still deploys to `staging` as one place.
+
 Nothing is declared in a manifest. A context that declares convergence converges **every
-component that stores anything**, as the outbox publishes every event something consumes.
+component that stores anything** — its own, and the ones its extensions ship: identity is what
+holds users, their roles and the keys their tokens are read with, and a region without them is
+one where nobody registered elsewhere exists.
+
+**A storage that does not converge stands the component down, and says so at boot.** Nothing
+else about the component changes and nothing else is held back; it is one line in the log,
+because a component quietly not converging is two regions differing with nothing to notice it.
 
 `pointer` is a [pointer](/libraries/pointer), so a URL carries no credentials — they are
 deployed as secrets — and shards syntax works. It is flat: a URL or a list of them. A region has
 one set of brokers, and they are that region's own, shared with nothing else.
 
-## Deploying
-
-Which region a deployment is, is chosen when it is deployed:
-
-```shell
-$ TOA_CONVERGENCE_REGION=eu toa deploy production
-```
-
-An operator can write it in `.env` instead of prefixing every command. Without it, a context
-that declares convergence is refused rather than deployed as a region it cannot name.
+**`priority` is the same table in every region, and nothing checks that.** A deployment reads
+only its own declaration, so two regions given one rank is a misconfiguration no deploy can see:
+ties between those two would resolve for neither. What notices is the runtime — a record can
+only carry the rank of the region that wrote it, so one arriving with this region's own rank is
+reported as an error.
 
 **The region an existing application is first deployed as is rank `0`.** Its records were
 written by whatever region it is now becoming, and that is what they are recorded as.
@@ -56,6 +68,11 @@ Each region's broker holds two exchanges, the same two names everywhere:
 | `convergence.in` | **federated** from every other region's `convergence.out`. |
 | `convergence.<namespace>.<name>` | a durable queue per component, bound to `convergence.in` under that component's key. |
 
+Nothing declares those queues for a region that is not running yet, which is what makes adding
+one an order that matters, and adding a converging component to a running pair the same:
+`toa export convergence <environment>` prints what a region's broker must carry, and
+[operations](./operations.md) says when to declare it.
+
 **Toa does not configure the federation.** On each region's broker, an upstream per other region
 and one policy over them:
 
@@ -96,14 +113,19 @@ where a change that failed to publish would be lost rather than recovered, and t
 differ with nothing to say so. Events degrade there; convergence refuses.
 
 **[Atomicity](/connectors/atomicity).** Without it the outbox pump recovers nothing, so a
-publication that fails is never retried and that change is lost for good. Nothing detects this,
-which is why it is written here rather than raised.
+publication that fails is never retried and that change is lost for good. Nothing can refuse at
+boot over it — a replica owns no lane for a moment anyway — so what happens instead is that the
+pump says so, every ten cycles it has owned none.
+
+**Which delayed calls a region makes is `cadence.regions`,** not something held back from
+convergence: every region holds every region's rows, and each makes the calls of the region it
+is. See [cadence](/extensions/cadence#regions).
 
 **The same components in every region.** A component deployed in one and not another has no
 queue there, so its records cannot be routed; publishing is `mandatory`, so what had nowhere to
 go is logged rather than dropped in silence.
 
-**Unique indexes other than `_id` are not safe.** Two regions can independently take the same
+**Uniqueness over anything but `id` is not safe.** Two regions can independently take the same
 value, and the record that arrives second cannot be stored at all. It is logged and dropped;
 redelivery would not help.
 
@@ -114,4 +136,8 @@ that region's rank. An incoming record wins where its version is greater, or whe
 is equal and the region that wrote it outranks the one that wrote what is stored. `priority` is
 read there and nowhere else.
 
+**`context.region` is that rank**, which is what a component reads to tell where it is running.
+It is zero where an application is deployed as one place, which is what such a deployment's
+records carry.
+
 An unmanaged operation reads the driver's own handle, and will see the field.

package/transpiled/Destination.d.ts

@@ -12,14 +12,22 @@ export declare class Destination extends Connector implements outbox.Destination
     private readonly resolve;
     private readonly span;
     private outbound;
+    /** whether the storage under this component turned out to be one that does not converge */
+    private disabled;
     constructor(locator: Locator, resolve: () => Promise<bindings.Outbound>);
-    emit(event: outbox.Row['event']): Promise<void>;
+    /**
+     * Stands down: the half that receives found a storage that does not converge, so neither
+     * does this component, and publishing what no region will consume would be returns and
+     * nothing else. The row settles at once rather than staying outstanding for good.
+     */
+    disable(): void;
+    emit(row: outbox.Row): Promise<void>;
     protected open(): Promise<void>;
 }
 /** What convergence puts on the wire. Owned by this extension at both ends. */
 export interface Message {
     /** the record as it stands — VERSION, timestamps, REGION and all */
     record: object;
-    /** W3C traceparent, so the merge continues the trace of the write that caused it */
+    /** W3C traceparent, so the far side continues the trace of the write that caused it */
     trace?: string;
 }

package/transpiled/Destination.js

@@ -12,6 +12,8 @@ export class Destination extends Connector {
     resolve;
     span;
     outbound;
+    /** whether the storage under this component turned out to be one that does not converge */
+    disabled = false;
     constructor(locator, resolve) {
         super();
         this.label = locator.id;
@@ -22,21 +24,37 @@ export class Destination extends Connector {
             attributes: { 'messaging.destination.name': CHANNEL }
         };
     }
-    async emit(event) {
+    /**
+     * Stands down: the half that receives found a storage that does not converge, so neither
+     * does this component, and publishing what no region will consume would be returns and
+     * nothing else. The row settles at once rather than staying outstanding for good.
+     */
+    disable() {
+        this.disabled = true;
+    }
+    async emit(row) {
+        if (this.disabled)
+            return;
         await console.span(this.span, async () => {
             const context = current();
             /*
              * The record says which region wrote it, so the message does not say it again. `trace`
              * is convergence's own field rather than anything a binding puts there: it owns both
-             * ends, and it wants the merge to continue the trace of the write that caused it.
+             * ends, and it wants the far side to continue the trace of the write that caused it.
+             *
+             * `row.trail` is deliberately not carried. The far side writes the record through the
+             * storage rather than through an operation, so it makes no call and publishes no event —
+             * there is no chain there to continue, and nothing to refuse.
              */
-            const message = { record: event.state };
+            const message = { record: row.event.state };
             if (context !== undefined)
                 message.trace = encode(context);
             await this.outbound.send(this.label, message);
         });
     }
     async open() {
+        if (this.disabled)
+            return;
         this.outbound = await this.resolve();
         await this.outbound.connect();
         this.depends(this.outbound);

package/transpiled/Destination.js.map

@@ -1 +1 @@
-{"version":3,"file":"Destination.js","sourceRoot":"","sources":["../source/Destination.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAoB,MAAM,UAAU,CAAA;AACrE,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AACxC,OAAO,EAAE,OAAO,EAAE,MAAM,4CAA4C,CAAA;AAIpE;;;;GAIG;AACH,MAAM,OAAO,WAAY,SAAQ,SAAS;IACxB,IAAI,GAAG,OAAO,CAAA;IAEb,KAAK,CAAQ;IACb,OAAO,CAAkC;IACzC,IAAI,CAAa;IAE1B,QAAQ,CAAoB;IAEpC,YAAmB,OAAgB,EAAE,OAAyC;QAC5E,KAAK,EAAE,CAAA;QAEP,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,EAAE,CAAA;QACvB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;QAEtB,IAAI,CAAC,IAAI,GAAG;YACV,IAAI,EAAE,GAAG,OAAO,OAAO;YACvB,IAAI,EAAE,UAAU;YAChB,UAAU,EAAE,EAAE,4BAA4B,EAAE,OAAO,EAAE;SACtD,CAAA;IACH,CAAC;IAEM,KAAK,CAAC,IAAI,CAAC,KAA0B;QAC1C,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,IAAI,EAAE;YACvC,MAAM,OAAO,GAAG,OAAO,EAAE,CAAA;YAEzB;;;;eAIG;YACH,MAAM,OAAO,GAAY,EAAE,MAAM,EAAE,KAAK,CAAC,KAAK,EAAE,CAAA;YAEhD,IAAI,OAAO,KAAK,SAAS;gBAAE,OAAO,CAAC,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,CAAA;YAE1D,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAA;QAC/C,CAAC,CAAC,CAAA;IACJ,CAAC;IAEkB,KAAK,CAAC,IAAI;QAC3B,IAAI,CAAC,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAA;QAEpC,MAAM,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAA;QAE7B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IAC7B,CAAC;CACF"}
+{"version":3,"file":"Destination.js","sourceRoot":"","sources":["../source/Destination.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAoB,MAAM,UAAU,CAAA;AACrE,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AACxC,OAAO,EAAE,OAAO,EAAE,MAAM,4CAA4C,CAAA;AAIpE;;;;GAIG;AACH,MAAM,OAAO,WAAY,SAAQ,SAAS;IACxB,IAAI,GAAG,OAAO,CAAA;IAEb,KAAK,CAAQ;IACb,OAAO,CAAkC;IACzC,IAAI,CAAa;IAE1B,QAAQ,CAAoB;IAEpC,2FAA2F;IACnF,QAAQ,GAAG,KAAK,CAAA;IAExB,YAAmB,OAAgB,EAAE,OAAyC;QAC5E,KAAK,EAAE,CAAA;QAEP,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,EAAE,CAAA;QACvB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;QAEtB,IAAI,CAAC,IAAI,GAAG;YACV,IAAI,EAAE,GAAG,OAAO,OAAO;YACvB,IAAI,EAAE,UAAU;YAChB,UAAU,EAAE,EAAE,4BAA4B,EAAE,OAAO,EAAE;SACtD,CAAA;IACH,CAAC;IAED;;;;OAIG;IACI,OAAO;QACZ,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAA;IACtB,CAAC;IAEM,KAAK,CAAC,IAAI,CAAC,GAAe;QAC/B,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAM;QAEzB,MAAM,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,IAAI,EAAE;YACvC,MAAM,OAAO,GAAG,OAAO,EAAE,CAAA;YAEzB;;;;;;;;eAQG;YACH,MAAM,OAAO,GAAY,EAAE,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,CAAA;YAEpD,IAAI,OAAO,KAAK,SAAS;gBAAE,OAAO,CAAC,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,CAAA;YAE1D,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAA;QAC/C,CAAC,CAAC,CAAA;IACJ,CAAC;IAEkB,KAAK,CAAC,IAAI;QAC3B,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAM;QAEzB,IAAI,CAAC,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE,CAAA;QAEpC,MAAM,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAA;QAE7B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IAC7B,CAAC;CACF"}

package/transpiled/Factory.d.ts

@@ -10,15 +10,17 @@ export declare class Factory implements extensions.Factory {
     private readonly host;
     /** one publisher for the process, however many components send through it */
     private outbound;
+    /**
+     * What this extension was given, by component, until the storage of that component is made.
+     * What decorates a storage is every extension loaded in the process rather than the ones a
+     * manifest named, so this is what tells a component this extension converges from one it was
+     * never asked about — one that stores nothing, or one of another composition entirely.
+     */
+    private readonly destinations;
     constructor(host: extensions.Host);
     /** out */
     destination(locator: Locator, _: null, manifest: Manifest): Destination | undefined;
-    /**
-     * In. Guarded, because what decorates a storage is every extension loaded in the process
-     * rather than the ones a manifest named: once anything here converges, this is asked about
-     * everything. Convergence is a property of a deployment, so what it is deployed with is what
-     * says whether there is any.
-     */
+    /** in, for the components this extension was given and no others */
     storage(storage: storages.Storage, locator: Locator): storages.Storage;
     private publisher;
     private binding;

package/transpiled/Factory.js

@@ -1,3 +1,4 @@
+import { console } from 'openspan';
 import { environment } from '@toa.io/generic';
 import { resolve } from '@toa.io/pointer';
 import { BINDING, BROKERS, CHANNEL, ID } from '@toa.io/definitions/extensions.convergence';
@@ -12,6 +13,13 @@ export class Factory {
     host;
     /** one publisher for the process, however many components send through it */
     outbound;
+    /**
+     * What this extension was given, by component, until the storage of that component is made.
+     * What decorates a storage is every extension loaded in the process rather than the ones a
+     * manifest named, so this is what tells a component this extension converges from one it was
+     * never asked about — one that stores nothing, or one of another composition entirely.
+     */
+    destinations = new Map();
     constructor(host) {
         this.host = host;
     }
@@ -19,17 +27,32 @@ export class Factory {
     destination(locator, _, manifest) {
         if (!converging() || manifest.entity === undefined)
             return undefined;
-        return new Destination(locator, async () => this.publisher());
+        const destination = new Destination(locator, async () => this.publisher());
+        this.destinations.set(locator.id, destination);
+        return destination;
     }
-    /**
-     * In. Guarded, because what decorates a storage is every extension loaded in the process
-     * rather than the ones a manifest named: once anything here converges, this is asked about
-     * everything. Convergence is a property of a deployment, so what it is deployed with is what
-     * says whether there is any.
-     */
+    /** in, for the components this extension was given and no others */
     storage(storage, locator) {
-        if (!converging())
+        const destination = this.destinations.get(locator.id);
+        // the pairing is for the component being built, and one is built once: an extension is
+        // loaded once for the life of a process, and holding a component's id past its build
+        // would decorate the next one to carry that id
+        this.destinations.delete(locator.id);
+        if (destination === undefined || !converging())
+            return storage;
+        /*
+         * A storage that does not converge has nowhere to put what another region wrote, so
+         * neither does this component — and the half that publishes stands down with it, because
+         * what it sent would reach a queue no region declares. Said out loud, because a component
+         * silently not converging is two regions differing with nothing to notice it.
+         */
+        if (storage.converges !== true) {
+            destination.disable();
+            console.warn('Component does not converge: its storage cannot', {
+                component: locator.id
+            });
             return storage;
+        }
         return new Converging(storage, locator, async (sink) => this.host.inbound(this.binding(), CHANNEL, this.uris(), locator.id, sink));
     }
     async publisher() {

package/transpiled/Factory.js.map

@@ -1 +1 @@
-{"version":3,"file":"Factory.js","sourceRoot":"","sources":["../source/Factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AACzC,OAAO,EACL,OAAO,EACP,OAAO,EACP,OAAO,EACP,EAAE,EACH,MAAM,4CAA4C,CAAA;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAIzC;;;;GAIG;AACH,MAAM,OAAO,OAAO;IACD,IAAI,CAAiB;IAEtC,6EAA6E;IACrE,QAAQ,CAAwC;IAExD,YAAmB,IAAqB;QACtC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;IAED,UAAU;IACH,WAAW,CAChB,OAAgB,EAChB,CAAO,EACP,QAAkB;QAElB,IAAI,CAAC,UAAU,EAAE,IAAI,QAAQ,CAAC,MAAM,KAAK,SAAS;YAAE,OAAO,SAAS,CAAA;QAEpE,OAAO,IAAI,WAAW,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAA;IAC/D,CAAC;IAED;;;;;OAKG;IACI,OAAO,CAAC,OAAyB,EAAE,OAAgB;QACxD,IAAI,CAAC,UAAU,EAAE;YAAE,OAAO,OAAO,CAAA;QAEjC,OAAO,IAAI,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,CACrD,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,IAAI,CAAC,CAC1E,CAAA;IACH,CAAC;IAEO,KAAK,CAAC,SAAS;QACrB,IAAI,CAAC,QAAQ,KAAK,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAA;QAE1E,OAAO,IAAI,CAAC,QAAQ,CAAA;IACtB,CAAC;IAEO,OAAO;QACb,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;QAE1C,IAAI,SAAS,KAAK,SAAS;YACzB,MAAM,IAAI,KAAK,CAAC,GAAG,OAAO,wDAAwD,CAAC,CAAA;QAErF,OAAO,SAAS,CAAA;IAClB,CAAC;IAEO,IAAI;QACV,OAAO,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,CAAA;IAC7B,CAAC;CACF;AAED,6FAA6F;AAC7F,SAAS,UAAU;IACjB,OAAO,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,SAAS,CAAA;AAC/C,CAAC"}
+{"version":3,"file":"Factory.js","sourceRoot":"","sources":["../source/Factory.ts"],"names":[],"mappings":"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"}

package/transpiled/Storage.d.ts

@@ -27,7 +27,7 @@ export declare class Converging extends Connector implements storages.Storage, b
     get raw(): unknown;
     get outbox(): storages.Storage['outbox'];
     get migrates(): boolean | undefined;
-    get merges(): boolean | undefined;
+    get converges(): boolean | undefined;
     get(query: storages.Query): Promise<storages.Record | null>;
     find(query: storages.Query): Promise<storages.Record[]>;
     stream(query?: storages.Query): Promise<Readable>;
@@ -35,5 +35,5 @@ export declare class Converging extends Connector implements storages.Storage, b
     massStore(records: storages.Record[], rows?: outbox.Row[]): Promise<boolean>;
     upsert(query: storages.Query, changeset: object, row?: outbox.Row): Promise<storages.Record | null>;
     ensure(query: storages.Query | undefined, properties: object, record: storages.Record, row?: outbox.Row): Promise<storages.Record>;
-    merge(record: storages.Record): Promise<boolean>;
+    converge(record: storages.Record): Promise<boolean>;
 }

package/transpiled/Storage.js

@@ -1,4 +1,5 @@
 import { console, decode, run } from 'openspan';
+import { environment } from '@toa.io/generic';
 import { Connector } from '@toa.io/core';
 import { CHANNEL } from '@toa.io/definitions/extensions.convergence';
 /**
@@ -31,7 +32,7 @@ export class Converging extends Connector {
             attributes: { 'messaging.destination.name': CHANNEL }
         };
         this.processing = {
-            name: `${CHANNEL} merge`,
+            name: `${CHANNEL} process`,
             kind: 'consumer',
             service: locator.id,
             attributes: { 'messaging.destination.name': CHANNEL }
@@ -43,12 +44,24 @@ export class Converging extends Connector {
      */
     async accept(message) {
         const { record, trace } = message;
+        /*
+         * A record carrying this region's own rank cannot have come from anywhere: a region is
+         * not bound to what it publishes, and it republishes nothing it converges, so the rank on a
+         * record that arrives is the rank of the region that wrote it. Two of them sharing one is
+         * a misconfiguration nothing else can see — no deployment knows what the others declared —
+         * and it means ties between those two resolve for neither.
+         */
+        if (record.REGION === REGION)
+            console.error('Convergence received a record of this region\'s own rank', {
+                component: this.locator.id,
+                region: REGION
+            });
         const remote = trace === undefined ? null : decode(trace);
         const task = async () => console.span(this.delivery, async () => console.span(this.processing, async () => {
-            const merged = await this.storage.merge(record);
-            console.debug('Convergence merge', {
+            const applied = await this.storage.converge(record);
+            console.trace('Convergence processed', {
                 component: this.locator.id,
-                outcome: merged ? 'applied' : 'stale'
+                outcome: applied ? 'applied' : 'stale'
             });
         }));
         if (remote === null)
@@ -57,18 +70,13 @@ export class Converging extends Connector {
             await run(remote, task);
     }
     async open() {
-        if (this.storage.merges !== true)
-            throw new Error(`Component '${this.locator.id}' converges, which its storage does not do. ` +
-                'A record written in another region has nowhere to land.');
         /*
          * Without a durable outbox a publication is lost where the process dies before it lands,
          * and a lost one here is two regions differing for good, with nothing that notices and
          * nothing that repairs it. That is why this refuses where events only degrade.
          */
         if (this.storage.outbox === undefined)
-            throw new Error(`Component '${this.locator.id}' converges, and its outbox is not durable. ` +
-                'MongoDB is not a replica set, so a change that fails to publish is lost rather ' +
-                'than recovered, and the regions would differ with nothing to say so.');
+            throw new Error(`Component '${this.locator.id}' converges, and its storage offers no outbox.`);
         const inbound = await this.subscribe(this);
         await inbound.connect();
         this.depends(inbound);
@@ -83,8 +91,8 @@ export class Converging extends Connector {
     get migrates() {
         return this.storage.migrates;
     }
-    get merges() {
-        return this.storage.merges;
+    get converges() {
+        return this.storage.converges;
     }
     async get(query) {
         return this.storage.get(query);
@@ -108,8 +116,10 @@ export class Converging extends Connector {
     async ensure(query, properties, record, row) {
         return this.storage.ensure(query, properties, record, row);
     }
-    async merge(record) {
-        return this.storage.merge(record);
+    async converge(record) {
+        return this.storage.converge(record);
     }
 }
+/** The rank of this region, which nothing that arrives should be carrying. */
+const REGION = Number(environment.get('TOA_REGION') ?? 0);
 //# sourceMappingURL=Storage.js.map

package/transpiled/Storage.js.map

@@ -1 +1 @@
-{"version":3,"file":"Storage.js","sourceRoot":"","sources":["../source/Storage.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Storage.js","sourceRoot":"","sources":["../source/Storage.ts"],"names":[],"mappings":"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"}