@toa.io/core 1.0.0-alpha.270 → 1.0.0-alpha.273

package/CHANGELOG.md

@@ -3,6 +3,70 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [1.0.0-alpha.273](https://github.com/toa-io/toa/compare/v1.0.0-alpha.272...v1.0.0-alpha.273) (2026-09-02)
+
+**Note:** Version bump only for package @toa.io/core
+
+
+
+
+
+# [1.0.0-alpha.272](https://github.com/toa-io/toa/compare/v1.0.0-alpha.271...v1.0.0-alpha.272) (2026-09-01)
+
+
+### Bug Fixes
+
+* **core:** stop the reply contract from relaxing the declaration ([6222893](https://github.com/toa-io/toa/commit/622289326630b94deff93499d6a851bfaa57c69a))
+
+
+* feat(atomicity)!: take a quorum of independent servers ([862562f](https://github.com/toa-io/toa/commit/862562f24d77ec00127dbbd88d43802b208c643b))
+* refactor(atomicity)!: take the lock manager from the stash ([4fd91eb](https://github.com/toa-io/toa/commit/4fd91eb2fdb68f7b87aaf16d182794bbc567ba57))
+* refactor(core)!: pump the outbox in one cycle ([bf590fe](https://github.com/toa-io/toa/commit/bf590fe8ed59c701b5fd1a91ba4874685b79242f))
+* refactor(atomicity)!: make the connector a family, not a partitioner ([06fd63a](https://github.com/toa-io/toa/commit/06fd63ad6296b724ef83afccf4e4e25d0bcaf080))
+* refactor(atomicity)!: rename the connector and free it of the outbox ([21f1a41](https://github.com/toa-io/toa/commit/21f1a41aceafcfd35c7620014062fe46b54afa95))
+* feat(core)!: commit events with the state that produced them ([1eb68cc](https://github.com/toa-io/toa/commit/1eb68cc435dbfa03faa16009fceb866693d22e1a)), closes [#20](https://github.com/toa-io/toa/issues/20)
+
+
+### Features
+
+* **atomicity:** meter what the group has spent ([bb1118a](https://github.com/toa-io/toa/commit/bb1118aa60bfeb43d3212f2495b7797445f003c3))
+* **core:** give every component an atom aspect ([b501b9c](https://github.com/toa-io/toa/commit/b501b9cd3d5f5408d9faa71213e953fe2792cf9f))
+
+
+### BREAKING CHANGES
+
+* `atomicity.redis` accepts a list again, of independent servers rather
+than cluster nodes, and refuses an even number of them.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+* `context.stash.lock` is gone; lock through `context.atom` instead.
+A stash pointer resolving to several addresses now uses the first.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+* `Storage.outbox.pending` takes a fourth argument, the id to
+continue from.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+* `Factory.partition(group)` is `Factory.atom(group)`, and the
+`Partition` it returned is an `Atom`. `slots(total)` is unchanged.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+* `@toa.io/partitions.redis` is now `@toa.io/atomicity`, and its
+`lanes(total)` is `slots(total)`. Redis is declared as `atomicity` in the context
+rather than `outbox.redis`, and read from `TOA_ATOMICITY_REDIS`.
+`TOA_OUTBOX_PARTITION_INTERVAL` is `TOA_ATOMICITY_INTERVAL`.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+* `event.changeset` is removed; use `origin` and `state`. `State`
+takes an `Outbox` in place of an `Emission`. `difference` is dropped from
+`@toa.io/generic` along with its last caller.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+
+
+
+
+
 # [1.0.0-alpha.270](https://github.com/toa-io/toa/compare/v1.0.0-alpha.269...v1.0.0-alpha.270) (2026-08-31)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/core",
-  "version": "1.0.0-alpha.270",
+  "version": "1.0.0-alpha.273",
   "description": "Toa Core",
   "author": "temich <tema.gurtovoy@gmail.com>",
   "homepage": "https://github.com/toa-io/toa#readme",
@@ -21,11 +21,10 @@
   },
   "dependencies": {
     "@rsql/parser": "1.2.4",
-    "@toa.io/generic": "1.0.0-alpha.254",
-    "@toa.io/yaml": "1.0.0-alpha.254",
-    "error-value": "0.3.0",
-    "openspan": "1.0.0-alpha.270",
+    "@toa.io/generic": "1.0.0-alpha.273",
+    "js-yaml": "4.3.1",
+    "openspan": "1.0.0-alpha.272",
     "uuid": "11.1.1"
   },
-  "gitHead": "94400bdd411b4c25074ffcf58184580ddd060268"
+  "gitHead": "ad3284850ece95ffd5325fd0995707fc144c9c3d"
 }

package/src/assignment.js

@@ -12,14 +12,15 @@ class Assignment extends Operation {
     const {
       scope,
       state,
-      reply
+      reply,
+      request
     } = store
 
     if (reply.error !== undefined) return
 
     scope.set(state)
 
-    const output = await this.scope.apply(scope)
+    const output = await this.scope.apply(scope, request.input)
 
     // assignment returns new state by default
     if (store.reply.output === undefined) {

package/src/call.js

@@ -3,7 +3,6 @@
 const { Readable } = require('node:stream')
 const { current, encode } = require('openspan')
 const { Connector } = require('./connector')
-const { Err } = require('error-value')
 
 class Call extends Connector {
   #transmitter
@@ -48,7 +47,7 @@ class Call extends Connector {
         throw reply.exception
 
       if (reply.error !== undefined)
-        return Err(reply.error.code, reply.error)
+        return new RemoteError(reply.error)
       else
         return reply.output
     }
@@ -60,3 +59,12 @@ class Call extends Connector {
 }
 
 exports.Call = Call
+
+// the remote error as a value: every property it carries, and nothing else enumerable
+class RemoteError extends Error {
+  constructor (error) {
+    super()
+
+    Object.assign(this, error)
+  }
+}

package/src/contract/reply.js

@@ -11,6 +11,14 @@ class Reply extends Contract {
     const schema = { type: 'object', properties: {}, additionalProperties: false }
 
     if (output !== undefined) {
+      /*
+       * A reply carries more than the operation declares — `_version` and the rest of the
+       * record's own fields — so what it is validated against is the declaration relaxed.
+       * On a copy: the declaration itself is what a component publishes when asked to
+       * explain, and relaxing that would publish a contract nobody wrote.
+       */
+      output = structuredClone(output)
+
       if (output.type === 'object')
         output.additionalProperties = true
       else if (output.type === 'array' && output.items?.type === 'object')

package/src/contract/schemas/index.js

@@ -1,8 +1,13 @@
 'use strict'
 
 const { resolve } = require('path')
-const { load } = require('@toa.io/yaml')
+const { readFileSync } = require('node:fs')
+const { load: parseYAML } = require('js-yaml')
 
-exports.query = load.sync(resolve(__dirname, './query.yaml'))
-exports.error = load.sync(resolve(__dirname, './error.yaml'))
-exports.source = load.sync(resolve(__dirname, './source.yaml'))
+exports.query = read(resolve(__dirname, './query.yaml'))
+exports.error = read(resolve(__dirname, './error.yaml'))
+exports.source = read(resolve(__dirname, './source.yaml'))
+
+function read (path) {
+  return parseYAML(readFileSync(path, 'utf8'))
+}

package/src/entities/entity.js

@@ -1,6 +1,5 @@
 'use strict'
 
-const { difference } = require('@toa.io/generic')
 const { EntityContractException, EntityGuardException } = require('../exceptions')
 const { newid } = require('./newid')
 
@@ -62,7 +61,6 @@ class Entity {
     return {
       origin: this.#origin,
       state: this.#state,
-      changeset: this.#origin === null ? this.#state : difference(this.#origin, this.#state),
       trailers: this.#state._trailers,
       input
     }

package/src/index.js

@@ -11,6 +11,7 @@ const { Event } = require('./event')
 const { Exposition } = require('./exposition')
 const { Locator } = require('./locator')
 const { Observation } = require('./observation')
+const { Outbox } = require('./outbox')
 const { Operation } = require('./operation')
 const { Query } = require('./query')
 const { Receiver } = require('./receiver')
@@ -41,6 +42,7 @@ exports.Event = Event
 exports.Exposition = Exposition
 exports.Locator = Locator
 exports.Observation = Observation
+exports.Outbox = Outbox
 exports.Operation = Operation
 exports.Query = Query
 exports.Receiver = Receiver

package/src/outbox/index.js

@@ -0,0 +1,6 @@
+'use strict'
+
+const { Outbox, LANES } = require('./outbox')
+
+exports.Outbox = Outbox
+exports.LANES = LANES

package/src/outbox/outbox.js

@@ -0,0 +1,301 @@
+'use strict'
+
+const { console } = require('openspan')
+const { Connector } = require('../connector')
+const { newid } = require('../entities/newid')
+
+/**
+ * Owns the intent to publish. A row is built before the write so that the storage can commit
+ * it in the same transaction as the entity; publication then happens off the operation's path,
+ * and anything that fails to publish is recovered from the row.
+ *
+ * The mechanism is a safety net: in a healthy system the row is written, published within
+ * milliseconds by the same process, and marked published on that process's next tick.
+ *
+ * A storage that cannot commit a row atomically has no outbox, and this degrades to the
+ * inline emission it replaces.
+ */
+class Outbox extends Connector {
+  #emission
+  #storage
+  #atom
+
+  #gap
+  #interval
+  #batch
+  #defer
+
+  /** ids this process has published, held until a cycle marks them */
+  #published = new Set()
+
+  /** in-flight publications, awaited (with a bound) on close */
+  #inflight = new Set()
+
+  /** rows this replica is publishing right now, so a cycle does not pick them up again */
+  #publishing = new Set()
+
+  #timer
+  #pumping = false
+  #closing = false
+
+  constructor (emission, storage, atom, options = {}) {
+    super()
+
+    this.#emission = emission
+    this.#storage = storage
+    this.#atom = atom
+
+    this.#interval = number('TOA_OUTBOX_INTERVAL', options.interval, INTERVAL)
+    this.#batch = number('TOA_OUTBOX_BATCH', options.batch, BATCH)
+    this.#gap = options.gap ?? this.#interval * K
+    this.#defer = process.env.TOA_OUTBOX_DEFER === '1'
+
+    this.depends(emission)
+    this.depends(atom)
+
+    if (storage !== undefined) this.depends(storage)
+  }
+
+  /** whether the storage can commit a row atomically with the entity */
+  get durable () {
+    return this.#storage?.outbox !== undefined
+  }
+
+  /**
+   * @param event {toa.core.transition.Event}
+   * @returns {object}
+   */
+  row (event) {
+    return {
+      id: newid(),
+      lane: this.#lane(),
+      published: false,
+      pending: Date.now() + this.#gap,
+      event
+    }
+  }
+
+  /**
+   * Hands a committed row over. Awaited by the caller only on the legacy path — with an
+   * outbox this returns at once and the broker leaves the operation's path.
+   */
+  publish (row) {
+    if (!this.durable)
+      return this.#emission.emit(row.event)
+
+    /*
+     * A publication started while the pump is closing would outlive the emitters it needs,
+     * and `comq` waits on a connection that is going rather than failing. The row is already
+     * durable, so leaving it is exactly what it is for.
+     */
+    if (this.#closing || this.#defer ||
+      this.#inflight.size >= INFLIGHT || this.#published.size >= PUBLISHED)
+      return
+
+    void this.#publish(row)
+  }
+
+  async open () {
+    if (!this.durable) return
+
+    if (this.#defer)
+      console.warn('Outbox immediate publication is deferred; events are published by the pump only')
+
+    this.#timer = setInterval(() => this.#tick(), this.#interval)
+    this.#timer.unref()
+  }
+
+  async close () {
+    this.#closing = true
+
+    if (this.#timer !== undefined) clearInterval(this.#timer)
+
+    await this.#drain()
+    await this.#mark()
+  }
+
+  /**
+   * Publishes one row and swallows the failure: the row stays unpublished and comes back on a
+   * later cycle, which is the whole point of having written it.
+   *
+   * There is no timeout here on purpose. A publication is a confirmed write to a durable
+   * exchange, and `comq` waits for the broker to come back rather than failing — abandoning
+   * it would not stop it, it would only mean the row is published twice once it lands. What
+   * bounds this instead is the in-flight cap and the drain on close.
+   *
+   * @private
+   */
+  async #publish (row) {
+    this.#publishing.add(row.id)
+
+    const publishing = this.#emission.emit(row.event)
+
+    this.#inflight.add(publishing)
+
+    try {
+      await publishing
+
+      this.#published.add(row.id)
+    } catch (error) {
+      console.warn('Event publication failed', { row: row.id, error })
+    } finally {
+      this.#inflight.delete(publishing)
+      this.#publishing.delete(row.id)
+    }
+  }
+
+  /**
+   * `comq` retries a publish for as long as the broker is down rather than rejecting, so an
+   * unbounded drain outlives any grace period.
+   *
+   * @private
+   */
+  async #drain () {
+    if (this.#inflight.size === 0) return
+
+    await Promise.race([Promise.allSettled([...this.#inflight]), delay(DRAIN)])
+  }
+
+  /**
+   * Reads what is due, publishes it, and marks everything this process has sent — what it just
+   * published and what the immediate path published since the last cycle. One cycle at a time.
+   *
+   * @private
+   */
+  #tick () {
+    if (this.#pumping) return
+
+    this.#pumping = true
+
+    void this.#pump().finally(() => (this.#pumping = false))
+  }
+
+  /** @private */
+  async #pump () {
+    let page
+
+    do {
+      page = await this.#read(page?.[page.length - 1]?.id)
+
+      if (page.length === 0) break
+
+      /*
+       * A row is unpublished in the database until a cycle marks it, so a page includes what
+       * this replica is sending right now and what a failed marking left behind. Only this
+       * process knows either.
+       */
+      const rows = page.filter((row) =>
+        !this.#published.has(row.id) && !this.#publishing.has(row.id))
+
+      if (rows.length > 0) {
+        console.info('Outbox recovering unpublished events', { count: rows.length })
+
+        // every row is given its chance; what the broker refused stays unpublished and comes
+        // back on a later cycle
+        await Promise.allSettled(rows.map((row) => this.#publish(row)))
+      }
+
+      // a full page is a page that may have been cut short
+    } while (page.length === this.#batch)
+
+    await this.#mark()
+  }
+
+  /**
+   * One page of what is due. In a healthy system the first one is empty, every cycle — a row is
+   * due only if the process that wrote it failed to publish or died before marking it.
+   *
+   * Reading is suspended, not stopped, while this replica does not know which lanes are its
+   * own: the cycle keeps running and keeps marking, and reading resumes as soon as an
+   * assignment arrives. Reading without an assignment would be a different guarantee, where
+   * every replica publishes every stranded row.
+   *
+   * @private
+   * @param {string} [after] the last id of the page before, so a page is never read twice
+   */
+  async #read (after) {
+    const lanes = this.#atom.slots(LANES)
+
+    if (lanes === null || lanes.length === 0) return []
+
+    return this.#storage.outbox.pending(lanes, Date.now(), this.#batch, after)
+      .catch((error) => {
+        console.warn('Outbox read failed', { error })
+
+        return []
+      })
+  }
+
+  /**
+   * One batched write for many events, which is why the ids are held in memory rather than
+   * marked one by one. Ids that fail to be marked are kept and retried; a row that is never
+   * marked is simply published again, which is within the contract.
+   *
+   * @private
+   */
+  async #mark () {
+    if (this.#published.size === 0) return
+
+    const ids = [...this.#published]
+
+    try {
+      await this.#storage.outbox.settle(ids)
+
+      for (const id of ids) this.#published.delete(id)
+    } catch (error) {
+      console.warn('Outbox marking failed', { count: ids.length, error })
+    }
+  }
+
+   /**
+   * A lane this replica currently owns, so that in steady state it settles its own rows
+   * before it ever reads them. Any lane at all when it owns none: the row still has to be
+   * written, and whoever ends up owning that lane will pump it.
+   *
+   * @private
+   */
+  #lane () {
+    const owned = this.#atom.slots(LANES)
+
+    return owned === null || owned.length === 0
+      ? Math.floor(Math.random() * LANES)
+      : owned[Math.floor(Math.random() * owned.length)]
+  }
+}
+
+function number (variable, declared, fallback) {
+  if (declared !== undefined) return declared
+
+  const value = Number(process.env[variable])
+
+  return Number.isNaN(value) || value <= 0 ? fallback : value
+}
+
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms).unref())
+
+/**
+ * Constant, never configuration: rows carry their lane, so lowering this would leave rows in
+ * lanes nobody reads any more. It is also the ceiling on replicas of one component, and a
+ * power of two so that the common replica counts divide evenly.
+ */
+const LANES = 128
+
+/** one cycle reads, publishes and marks; in steady state it finds nothing to read */
+const INTERVAL = 5000
+
+/**
+ * `gap = interval * K`. Not a steady-state necessity — a replica writes into a lane it owns
+ * and marks what it published — but a guard for when a lane changes hands between the write
+ * and the settle. Two cycles of separation, plus one of margin.
+ */
+const K = 3
+
+/** how many rows one read brings back; the pump reads on while a page comes back full */
+const BATCH = 200
+
+const DRAIN = 10_000
+const INFLIGHT = 1000
+const PUBLISHED = 10_000
+
+exports.Outbox = Outbox
+exports.LANES = LANES

package/src/state.js

@@ -7,12 +7,12 @@ class State {
 
   #associated
   #entities
-  #emission
+  #outbox
 
-  constructor (storage, entity, emission, associated) {
+  constructor (storage, entity, outbox, associated) {
     this.storage = storage
     this.#entities = entity
-    this.#emission = emission
+    this.#outbox = outbox
     this.#associated = associated === true
   }
 
@@ -66,14 +66,14 @@ class State {
 
     object.set(blank)
 
-    const record = await this.storage.ensure(query, properties, object.get())
+    const row = this.#outbox?.row(object.event(input))
+    const record = await this.storage.ensure(query, properties, object.get(), row)
 
     if (record.id !== blank.id) // exists
       return this.#entities.object(record, NOT_MUTABLE)
 
-    const event = object.event(input)
-
-    await this.#emission.emit(event)
+    if (row !== undefined)
+      await this.#outbox.publish(row)
 
     return object
   }
@@ -83,36 +83,39 @@ class State {
       return this.massCommit(state, input)
 
     const data = state.get()
-    const ok = await this.storage.store(data)
 
-    // #20
-    if (ok === true) {
-      const event = state.event(input)
+    // the row is built before the write so that the storage can commit it in the same
+    // transaction, closing the window this used to have
+    const row = this.#outbox?.row(state.event(input))
+    const ok = await this.storage.store(data, row)
 
-      await this.#emission.emit(event)
-    }
+    if (ok === true && row !== undefined)
+      await this.#outbox.publish(row)
 
     return ok
   }
 
   async massCommit (state, input) {
     const data = state.get()
-    const ok = await this.storage.massStore(data)
+    const rows = this.#outbox === undefined
+      ? undefined
+      : state.events(input).map((event) => this.#outbox.row(event))
 
-    // #20
-    if (ok === true) {
-      const events = state.events(input)
+    const ok = await this.storage.massStore(data, rows)
 
-      await Promise.all(events.map((event) => this.#emission.emit(event)))
-    }
+    if (ok === true && rows !== undefined)
+      await Promise.all(rows.map((row) => this.#outbox.publish(row)))
 
     return ok
   }
 
-  async apply (state) {
+  async apply (state, input) {
     const changeset = state.export()
 
-    const result = await this.storage.upsert(state.query, changeset)
+    // an assignment's event is the write's own images, so the storage fills them in;
+    // see `apply` in the outbox design
+    const row = this.#outbox?.row({ input })
+    const result = await this.storage.upsert(state.query, changeset, row)
 
     if (result === null) {
       if (state.query.version !== undefined) {
@@ -120,12 +123,13 @@ class State {
       } else {
         throw new StateNotFoundException()
       }
-    } else {
-      // same as above
-      await this.#emission.emit({
-        changeset,
-        state: result
-      })
+    } else if (row !== undefined) {
+      // the storage fills `origin` and `state` from its own write; a storage that does not
+      // know how leaves the event with what it was given
+      row.event.state ??= result
+      row.event.origin ??= null
+
+      await this.#outbox.publish(row)
     }
 
     return result

package/test/contract/contract.fixtures.js

@@ -1,7 +1,8 @@
 'use strict'
 
 const { generate } = require('randomstring')
-const { load } = require('@toa.io/yaml')
+const { readFileSync } = require('node:fs')
+const { load: parseYAML } = require('js-yaml')
 const { resolve } = require('path')
 
 // noinspection JSCheckFunctionSignatures
@@ -20,7 +21,7 @@ const schemas = {
     type: 'object',
     properties: {
       input: { type: 'null' },
-      query: load.sync(resolve(__dirname, '../../src/contract/schemas/query.yaml')),
+      query: parseYAML(readFileSync(resolve(__dirname, '../../src/contract/schemas/query.yaml'), 'utf8')),
       authentic: { type: 'boolean' }
     },
     additionalProperties: true

package/test/emission.fixtures.js

@@ -9,8 +9,7 @@ const events = [0, 1, 2].map((index) => ({
 
 const event = {
   origin: { [generate()]: generate() },
-  state: { [generate()]: generate() },
-  changeset: { [generate()]: generate() }
+  state: { [generate()]: generate() }
 }
 
 exports.events = events

package/test/entities/entity.test.js

@@ -58,7 +58,7 @@ describe('tombstone', () => {
 
     expect(entity.get()._deleted).toBeNull()
     expect(entity.deleted).toBe(false)
-    expect(entity.event().changeset._deleted).toBeNull()
+    expect(entity.event().state._deleted).toBeNull()
   })
 
   it('should keep tombstone written by transition', () => {
@@ -85,12 +85,8 @@ it('should provide event', () => {
 
   const event = entity.event()
 
-  expect(event).toEqual(expect.objectContaining({
-    state,
-    origin,
-    changeset: expect.objectContaining({
-      foo: 'new value',
-      _version: 1
-    })
-  }))
+  expect(event).toEqual(expect.objectContaining({ state, origin }))
+  expect(event.state.foo).toBe('new value')
+  expect(event.state._version).toBe(1)
+  expect(event.origin.foo).not.toBe('new value')
 })

package/test/outbox.test.js

@@ -0,0 +1,114 @@
+'use strict'
+
+const { Outbox } = require('../src/outbox')
+
+let emission, storage, atom, outbox
+
+const BATCH = 4
+
+/** rows as the storage hands them back, ids ascending like the uuid v7 they are */
+const page = (from, count) =>
+  Array.from({ length: count }, (_, i) => ({
+    id: String(from + i).padStart(4, '0'),
+    event: { state: {} }
+  }))
+
+beforeEach(() => {
+  jest.clearAllMocks()
+  jest.useFakeTimers()
+
+  emission = { emit: jest.fn(async () => undefined), link: jest.fn() }
+
+  storage = {
+    link: jest.fn(),
+    outbox: {
+      pending: jest.fn(async () => []),
+      settle: jest.fn(async () => undefined)
+    }
+  }
+
+  atom = { slots: jest.fn(() => [0]), link: jest.fn() }
+  outbox = new Outbox(emission, storage, atom, { interval: 1000, batch: BATCH })
+})
+
+afterEach(() => {
+  jest.useRealTimers()
+})
+
+/** one cycle, and everything it awaited */
+const cycle = async () => {
+  jest.advanceTimersByTime(1000)
+
+  for (let i = 0; i < 20; i++) await Promise.resolve()
+}
+
+it('should read nothing more when the first page is short', async () => {
+  storage.outbox.pending.mockResolvedValueOnce(page(0, 3))
+
+  await outbox.open()
+  await cycle()
+
+  expect(storage.outbox.pending).toHaveBeenCalledTimes(1)
+  expect(emission.emit).toHaveBeenCalledTimes(3)
+})
+
+it('should keep reading while a page comes back full', async () => {
+  storage.outbox.pending
+    .mockResolvedValueOnce(page(0, BATCH))
+    .mockResolvedValueOnce(page(BATCH, BATCH))
+    .mockResolvedValueOnce(page(2 * BATCH, 5))
+
+  await outbox.open()
+  await cycle()
+
+  expect(storage.outbox.pending).toHaveBeenCalledTimes(3)
+  expect(emission.emit).toHaveBeenCalledTimes(2 * BATCH + 5)
+})
+
+it('should continue each page from the id the one before ended on', async () => {
+  storage.outbox.pending
+    .mockResolvedValueOnce(page(0, BATCH))
+    .mockResolvedValueOnce(page(BATCH, 1))
+
+  await outbox.open()
+  await cycle()
+
+  const [, second] = storage.outbox.pending.mock.calls
+
+  expect(storage.outbox.pending.mock.calls[0][3]).toBeUndefined()
+  expect(second[3]).toStrictEqual(String(BATCH - 1).padStart(4, '0'))
+})
+
+it('should mark what it published, once, after the last page', async () => {
+  storage.outbox.pending
+    .mockResolvedValueOnce(page(0, BATCH))
+    .mockResolvedValueOnce(page(BATCH, 2))
+
+  await outbox.open()
+  await cycle()
+
+  expect(storage.outbox.settle).toHaveBeenCalledTimes(1)
+  expect(storage.outbox.settle.mock.calls[0][0]).toHaveLength(BATCH + 2)
+})
+
+it('should not publish a row it has published and not yet marked', async () => {
+  storage.outbox.settle.mockRejectedValueOnce(new Error('mongo is out'))
+  storage.outbox.pending
+    .mockResolvedValueOnce(page(0, 2))
+    .mockResolvedValueOnce(page(0, 2))
+
+  await outbox.open()
+  await cycle()
+  await cycle()
+
+  expect(emission.emit).toHaveBeenCalledTimes(2)
+})
+
+it('should read nothing while it owns no slots', async () => {
+  atom.slots.mockReturnValue(null)
+
+  await outbox.open()
+  await cycle()
+
+  expect(storage.outbox.pending).not.toHaveBeenCalled()
+})

package/test/state.fixtures.js

@@ -8,7 +8,10 @@ const storage = {
   find: jest.fn(() => ([{ id: generate() }])),
   add: jest.fn(() => true),
   set: jest.fn(() => true),
-  store: jest.fn(() => true)
+  store: jest.fn(() => true),
+  massStore: jest.fn(() => true),
+  upsert: jest.fn(() => ({ id: generate() })),
+  ensure: jest.fn((query, properties, state) => state)
 }
 
 const factory = {
@@ -20,9 +23,7 @@ const query = generate()
 
 const entity = {
   get: jest.fn(() => ({ [generate()]: generate() })),
-  event: jest.fn(() => ({
-    state: { [generate()]: generate() }, changeset: { [generate()]: generate() }
-  }))
+  event: jest.fn(() => ({ state: { [generate()]: generate() } }))
 }
 
 const initial = {
@@ -31,16 +32,18 @@ const initial = {
 
 const unchanged = {
   ...entity,
-  event: jest.fn(() => ({ state: { [generate()]: generate() }, changeset: {} }))
+  event: jest.fn(() => ({ state: { [generate()]: generate() } }))
 }
 
-const emitter = {
-  emit: jest.fn()
+// a legacy outbox: no storage capability, so `publish` emits inline
+const outbox = {
+  row: jest.fn((event) => ({ id: generate(), lane: 0, published: false, pending: 0, event })),
+  publish: jest.fn()
 }
 
 exports.storage = storage
 exports.factory = factory
-exports.emitter = emitter
+exports.outbox = outbox
 exports.query = query
 exports.entity = entity
 exports.initial = initial

package/test/state.test.js

@@ -8,7 +8,7 @@ let state
 beforeEach(() => {
   jest.clearAllMocks()
 
-  state = new State(fixtures.storage, fixtures.factory, fixtures.emitter)
+  state = new State(fixtures.storage, fixtures.factory, fixtures.outbox)
 })
 
 it('should provide object', async () => {
@@ -37,11 +37,58 @@ it('should provide read-only objects', async () => {
 it('should store entity', async () => {
   await state.commit(fixtures.initial)
 
-  expect(fixtures.storage.store).toHaveBeenCalledWith(fixtures.initial.get.mock.results[0].value)
+  expect(fixtures.storage.store).toHaveBeenCalledWith(
+    fixtures.initial.get.mock.results[0].value,
+    fixtures.outbox.row.mock.results[0].value)
 })
 
-it('should emit', async () => {
+it('should publish the row', async () => {
   await state.commit(fixtures.entity)
 
-  expect(fixtures.emitter.emit).toHaveBeenCalledWith(fixtures.entity.event.mock.results[0].value)
+  expect(fixtures.outbox.row).toHaveBeenCalledWith(fixtures.entity.event.mock.results[0].value)
+  expect(fixtures.outbox.publish).toHaveBeenCalledWith(fixtures.outbox.row.mock.results[0].value)
+})
+
+it('should not publish if the write did not happen', async () => {
+  fixtures.storage.store.mockImplementationOnce(() => false)
+
+  await state.commit(fixtures.entity)
+
+  expect(fixtures.outbox.publish).not.toHaveBeenCalled()
+})
+
+it('should build the row before the write', async () => {
+  // the storage commits the row in the same transaction, so it must already exist
+  fixtures.storage.store.mockImplementationOnce((_, row) => {
+    expect(row).toBeDefined()
+
+    return true
+  })
+
+  expect.assertions(1)
+
+  await state.commit(fixtures.entity)
+})
+
+describe('assignment', () => {
+  const changeset = { query: 'q', export: () => ({ foo: 1 }) }
+
+  it('should pass the row to upsert and publish it', async () => {
+    const result = await state.apply(changeset, { foo: 1 })
+
+    expect(fixtures.storage.upsert).toHaveBeenCalledWith(
+      changeset.query, { foo: 1 }, fixtures.outbox.row.mock.results[0].value)
+
+    expect(fixtures.outbox.publish).toHaveBeenCalledWith(fixtures.outbox.row.mock.results[0].value)
+    expect(result).toStrictEqual(fixtures.storage.upsert.mock.results[0].value)
+  })
+
+  it('should fill the state a storage without the outbox left alone', async () => {
+    await state.apply(changeset, { foo: 1 })
+
+    const row = fixtures.outbox.row.mock.results[0].value
+
+    expect(row.event.state).toStrictEqual(fixtures.storage.upsert.mock.results[0].value)
+    expect(row.event.input).toStrictEqual({ foo: 1 })
+  })
 })

package/types/atomicity.d.ts

@@ -0,0 +1,58 @@
+// noinspection ES6UnusedImports
+
+import { Connector } from './connector'
+
+declare namespace toa.core {
+
+  namespace atomicity {
+
+    /**
+     * What one group of replicas decides together, in one place. The decisions here are the
+     * ones processes cannot arrange by talking to each other: they need a single arbiter and a
+     * step indivisible from its point of view.
+     */
+    interface Atom extends Connector {
+      /**
+       * An exclusive claim on slots of `0..total`: while this replica holds one, no other
+       * replica of the group does. Answered from memory, so it costs nothing to ask.
+       *
+       * `null` while this replica owns nothing — after a restart, during a rollout, or while
+       * coordination is unreachable. Whoever asks must be able to stand down: acting on a
+       * claim that cannot be supported is a different guarantee, not a degraded one.
+       */
+      slots (total: number): number[] | null
+
+      /**
+       * Debt the group has run up under each key, in milliseconds. Every call adds its own
+       * deltas and reads back where the group stands, so a replica reports what it alone has
+       * spent and still decides on what all of them have.
+       *
+       * Rejects where there is nothing to arbitrate through.
+       */
+      meter (keys: string[], deltas: number[]): Promise<number[]>
+
+      /**
+       * Runs `routine` holding `keys`, and while it holds them no other replica of the group
+       * does. Waits for as long as it takes to acquire them.
+       *
+       * The lease is extended for as long as the routine runs. An extension that fails aborts
+       * the signal the routine is given, which is the only way it learns it no longer holds
+       * what it is working under.
+       *
+       * Rejects where there is nothing to arbitrate through.
+       */
+      lock<T> (keys: string | string[],
+        routine: (signal: AbortSignal, context: unknown) => Promise<T>): Promise<T>
+    }
+
+    interface Factory {
+      /** @param group what the replicas deciding together have in common */
+      atom (group: string, options?: object): Atom
+    }
+
+  }
+
+}
+
+export type Atom = toa.core.atomicity.Atom
+export type Factory = toa.core.atomicity.Factory

package/types/index.ts

@@ -1,6 +1,8 @@
 export * as bindings from './bindings'
 export * as extensions from './extensions'
 export * as storages from './storages'
+export * as outbox from './outbox'
+export * as atomicity from './atomicity'
 export * as bridges from './bridges'
 export * as operations from './operations'
 

package/types/outbox.d.ts

@@ -0,0 +1,53 @@
+import * as _state from './state'
+import * as _atomicity from './atomicity'
+
+declare namespace toa.core {
+
+  namespace outbox {
+
+    /**
+     * The intent to publish, committed with the state change it belongs to. Everything about
+     * it is core's: the storage writes it and, where the images are the write's own, fills
+     * `event.origin` and `event.state` in.
+     */
+    interface Row {
+      id: string
+
+      /** which replica pumps this row; carries no other meaning, and no ordering */
+      lane: number
+
+      published: boolean
+
+      /** not before this */
+      pending: number
+
+      event: _state.Event
+    }
+
+    /** What a storage offers when it can commit a row atomically with the entity. */
+    interface Storage {
+      insert (row: Row, session?: unknown): Promise<void>
+
+      insertMany (rows: Row[], session?: unknown): Promise<void>
+
+      /**
+       * One page of what is due, still unpublished, and in one of the given lanes, in the
+       * order the rows were written. `after` continues from the last id of the page before.
+       */
+      pending (lanes: number[], now: number, limit: number, after?: string): Promise<Row[]>
+
+      settle (ids: string[]): Promise<void>
+    }
+
+  }
+
+}
+
+export type Row = toa.core.outbox.Row
+export type Storage = toa.core.outbox.Storage
+
+/**
+ * A lane is a slot of `atomicity`: which replica pumps a row, and nothing else. The outbox is
+ * the first thing to claim slots this way, not the last.
+ */
+export type Atom = _atomicity.Atom

package/types/state.d.ts

@@ -6,9 +6,12 @@ declare namespace toa.core {
   namespace transition {
 
     type Event = {
-      origin: Object
+      /** the pre-image; null when the entity did not exist before */
+      origin: Object | null
       state: Object
-      changeset: Object
+      /** out-of-band values an algorithm wrote into `state._trailers`; must be serializable */
+      trailers?: Object
+      input?: Object
     }
 
   }
@@ -24,9 +27,9 @@ declare namespace toa.core {
 
     none(): null
 
-    commit(entity: _entity.Entity): Promise<boolean>
+    commit(entity: _entity.Entity, input?: Object): Promise<boolean>
 
-    apply(changeset: _entity.Changeset): Promise<void>
+    apply(changeset: _entity.Changeset, input?: Object): Promise<_storages.Record>
   }
 
 }

package/types/storages.d.ts

@@ -2,6 +2,7 @@
 
 import { Locator } from './locator'
 import { Connector } from './connector'
+import * as outbox from './outbox'
 
 declare namespace toa.core {
 
@@ -43,8 +44,13 @@ declare namespace toa.core {
       table (database: string, locator: Locator, schema: Object, reset?: boolean): Promise<string>
     }
 
+    interface Options {
+      /** whether this component publishes anything, and so needs an outbox */
+      outbox?: boolean
+    }
+
     interface Factory {
-      storage (locator: Locator, properties?: object): Storage
+      storage (locator: Locator, properties?: object, options?: Options): Storage
 
       migration? (driver?: string): Migration
     }
@@ -58,10 +64,27 @@ declare namespace toa.core {
     find? (query: storages.Query): Promise<storages.Record[]>
 
     // commit
-    store? (record: storages.Record): Promise<boolean>
+    store? (record: storages.Record, row?: outbox.Row): Promise<boolean>
+
+    // mass commit
+    massStore? (records: storages.Record[], rows?: outbox.Row[]): Promise<boolean>
 
     // assignment
-    upsert? (query: storages.Query, changeset: Object, insert: storages.Record): Promise<storages.Record>
+    upsert? (query: storages.Query, changeset: Object, row?: outbox.Row): Promise<storages.Record>
+
+    // atomic get-or-create
+    ensure? (query: storages.Query, properties: Object, record: storages.Record, row?: outbox.Row): Promise<storages.Record>
+
+    /**
+     * Present only where a row can be committed atomically with the entity. Its absence is
+     * what makes the runtime fall back to publishing inline, so a storage that cannot do
+     * this must not offer it: a row written outside the transaction would be a second write
+     * with a crash window in front of it, which is the defect the outbox exists to close.
+     *
+     * The row schema is the connector's own — it also owns `pending` and `settle` — and
+     * never crosses this boundary.
+     */
+    outbox?: outbox.Storage
   }
 
 }