@toa.io/extensions.cadence 1.0.0-alpha.284 → 1.0.0-alpha.287

package/CHANGELOG.md

@@ -3,8 +3,8 @@
 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.284](https://github.com/toa-io/toa/compare/v1.0.0-alpha.283...v1.0.0-alpha.284) (2026-09-05)
+# [1.0.0-alpha.287](https://github.com/toa-io/toa/compare/v1.0.0-alpha.286...v1.0.0-alpha.287) (2026-09-06)
 
-### Features
+### Bug Fixes
 
-* **cadence:** calls a component makes to itself, and calls it puts off ([8bbde5f](https://github.com/toa-io/toa/commit/8bbde5fc89e8e5549d5aa2bfcddb1beec0871565))
+* **cadence:** the scan reads what is owed, and nothing that is done ([581610e](https://github.com/toa-io/toa/commit/581610e87ac54c42491c882d5749ff3307700d35))

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/components/cadence.metronome/manifest.toa.yaml

@@ -5,35 +5,29 @@ name: metronome
 cadence: ~
 
 entity:
-  schema:
-    type: object
-    properties:
-      lane:
-        description: Which dispatcher takes this row, as the outbox partitions its lanes
-        type: integer
-      due:
-        description: When the call is to be made, in milliseconds since the epoch
-        type: integer
-      expires:
-        description: >
-          After this the call is not made at all. A scan bounds on it, so a call nothing was
-          running to make in time is a row nobody reads, rather than an event anything sees.
-        type: integer
-      endpoint:
-        description: What to call, as `namespace.component.operation`
-        type: string
-      request:
-        description: The request to make, as it was handed over
-        type: object
-    required:
-      - lane
-      - due
-      - expires
-      - endpoint
-  index:
+  properties:
+    lane:
+      description: Which dispatcher takes this row, as the outbox partitions its lanes
+      type: integer
     due:
-      lane: asc
-      due: asc
+      description: When the call is to be made, in milliseconds since the epoch
+      type: integer
+    expires:
+      description: >
+        After this the call is not made at all. A scan bounds on it, so a call nothing was
+        running to make in time is a row nobody reads, rather than an event anything sees.
+      type: integer
+    endpoint:
+      description: What to call, as `namespace.component.operation`
+      type: string
+    request:
+      description: The request to make, as it was handed over
+      type: object
+  required:
+    - lane
+    - due
+    - expires
+    - endpoint
 
 # `enumerate` reads what is due and `terminate` cancels one; both come from the prototype.
 operations:

package/components/cadence.metronome/migrations/0001-system-properties.yaml

@@ -0,0 +1,14 @@
+# 1.0.0-alpha.286 renamed the four system properties of a record. A database written before it
+# holds them under the old names, where nothing reads them: such a record is never created,
+# never updated, never deleted, and at version zero.
+#
+# `$rename` leaves a record that has none of them alone, so this is a no-op for a component
+# that has only ever run this release.
+- update:
+    filter: {}
+    update:
+      $rename:
+        _version: VERSION
+        _created: CREATED
+        _updated: UPDATED
+        _deleted: DELETED

package/components/cadence.metronome/migrations/0002-indexes.yaml

@@ -0,0 +1,5 @@
+- index:
+    name: index_due
+    keys:
+      lane: asc
+      due: asc

package/components/cadence.metronome/migrations/0003-pending-index.yaml

@@ -0,0 +1,16 @@
+# The index holds what is still owed, and nothing else.
+#
+# Without the filter a scan walks every row the collection has ever held: the criteria bounds
+# `due` from above and not below, and `DELETED` is not in the index, so every tombstone is
+# fetched and discarded on the way to the few rows that are live. The cost of a pass grows with
+# the age of the deployment until it outlives its own interval.
+#
+# The name is the one 0002 gave it, deliberately: an index whose declaration changed is dropped
+# and made again.
+- index:
+    name: index_due
+    keys:
+      lane: asc
+      due: asc
+    partial:
+      DELETED: null

package/components/cadence.metronome/migrations/0004-retention.yaml

@@ -0,0 +1,15 @@
+# A settled row is kept, and not kept forever.
+#
+# `DELETED` is what `settle` writes and what the runtime holds as a date, so the row ages out
+# on the moment its call was disposed of. A row still owed has `DELETED: null`, and the TTL
+# monitor passes over a record whose field is not a date — so nothing waiting to be called can
+# be reaped by this, however long it has been waiting.
+#
+# Thirty days. The record answers what was asked for and when it was disposed of, which is a
+# question asked while an incident is recent; a year of it is a collection nobody reads and
+# everybody stores.
+- index:
+    name: index_deleted
+    keys:
+      DELETED: asc
+    ttl: 2592000

package/components/cadence.metronome/operations/delay.js

@@ -8,7 +8,7 @@ import { LANES } from '@toa.io/extensions.cadence'
  * row has no immediate path to settle, so nothing is gained, and an even spread is what the
  * dispatchers want.
  */
-export function transition (input, object) {
+export function transition(input, object) {
   const due = Date.now() + input.interval
 
   object.lane = Math.floor(Math.random() * LANES)

package/components/cadence.metronome/operations/settle.js

@@ -1,9 +1,13 @@
 /**
- * The rows whose calls have been made. They are tombstoned rather than removed: the record of
- * what was asked for outlives the call, and a query answers only what is still owed.
+ * The rows whose calls have been disposed of — made, or found past the bound their caller gave
+ * them. They are tombstoned rather than removed: the record of what was asked for outlives the
+ * call, and a query answers only what is still owed.
+ *
+ * `DELETED` is also what the retention index reaps by, so that the record outlives the call
+ * without outliving the deployment.
  */
-export function transition (_, objects) {
+export function transition(_, objects) {
   const now = Date.now()
 
-  for (const object of objects) object._deleted = now
+  for (const object of objects) object.DELETED = now
 }

package/components/cadence.metronome/types/toa.d.ts

@@ -1,7 +1,7 @@
 // Written by `toa types`. Every run rewrites it.
 // What a manifest does not state belongs in a file of your own.
 
-import type { Query } from '@toa.io/core'
+import type { Query } from '@toa.io/core/types'
 import type { Readable } from 'node:stream'
 
 export interface Entity {
@@ -16,10 +16,10 @@ export interface Entity {
   /** The request to make, as it was handed over */
   request?: Record<string, unknown>
   id: string
-  _version?: number
-  _created?: number
-  _updated?: number
-  _deleted?: number | null
+  VERSION?: number
+  CREATED?: number
+  UPDATED?: number
+  DELETED?: number | null
 }
 
 export type DelayInput = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/extensions.cadence",
-  "version": "1.0.0-alpha.284",
+  "version": "1.0.0-alpha.287",
   "type": "module",
   "description": "Toa Schedule",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -18,11 +18,12 @@
     "access": "public"
   },
   "dependencies": {
-    "@toa.io/core": "1.0.0-alpha.284",
-    "@toa.io/schemas": "1.0.0-alpha.283",
-    "openspan": "1.0.0-alpha.277"
+    "@toa.io/core": "1.0.0-alpha.287",
+    "@toa.io/schemas": "1.0.0-alpha.287",
+    "openspan": "1.0.0-alpha.286"
   },
   "scripts": {
     "transpile": "tsc"
-  }
+  },
+  "gitHead": "5c7944a70c16065ab6372072385cc1f02f5db77c"
 }

package/readme.md

@@ -14,9 +14,9 @@ at all.
 ```yaml
 # manifest.toa.yaml
 cadence:
-  sweep:                # an operation of this component
-    cycle: 86400        # seconds one whole cycle takes
-    intervals: 24       # what it is split into, so one call an hour
+  sweep: # an operation of this component
+    cycle: 86400 # seconds one whole cycle takes
+    intervals: 24 # what it is split into, so one call an hour
 ```
 
 The gap between calls is `cycle / intervals`, derived rather than declared, so the two cannot
@@ -26,13 +26,13 @@ declares:
 ```yaml
 # manifest.toa.yaml
 cadence:
-  sweep: 3600           # once an hour
+  sweep: 3600 # once an hour
 ```
 
 The operation is called with the cycle and the interval as its input:
 
 ```javascript
-async function sweep ({ n, i }, context) { }
+async function sweep({ n, i }, context) {}
 ```
 
 `n` is `intervals` and `i` is which of them this call is for, from `0` to `n - 1`. They are there
@@ -77,22 +77,25 @@ either answer put to everyone who wanted an operation called every hour is a wor
 picking one.
 
 `intervals` is not a replica count. With `intervals: 24` and three replicas each makes eight of
-the day's calls: the cycle is spread over *time*, not over the fleet. Replicas beyond `intervals`
+the day's calls: the cycle is spread over _time_, not over the fleet. Replicas beyond `intervals`
 make none.
 
 ## Delay
 
 ```javascript
-const id = await context.delay('mail.sender.remind', { input: { user } },
-  { interval: 7 * 24 * 3600 * 1000, overdue: null })
+const id = await context.delay(
+  'mail.sender.remind',
+  { input: { user } },
+  { interval: 7 * 24 * 3600 * 1000, overdue: null }
+)
 
 await context.delay.cancel(id)
 ```
 
-| | |
-|---|---|
-| `interval` | milliseconds from now |
-| `overdue` | milliseconds the call may be late and still be made, or `null` for no bound |
+|            |                                                                             |
+| ---------- | --------------------------------------------------------------------------- |
+| `interval` | milliseconds from now                                                       |
+| `overdue`  | milliseconds the call may be late and still be made, or `null` for no bound |
 
 The call is made once the delay has passed, and waits for the target where it is not there to
 take it. The id it answers cancels it, and `cancel` raises where the id was never issued.
@@ -111,11 +114,11 @@ cadence: ~
 ordinary path has: a call is made at the moment it is due. How much is left of that in practice
 depends on how coarsely the calls are looked over — see [Discreteness](#discreteness).
 
-| | |
-|---|---|
-| `null` | no bound: made whenever it can be, however late that is |
-| `0` | on time or never |
-| a number | made if no more than that many milliseconds late |
+|          |                                                         |
+| -------- | ------------------------------------------------------- |
+| `null`   | no bound: made whenever it can be, however late that is |
+| `0`      | on time or never                                        |
+| a number | made if no more than that many milliseconds late        |
 
 **There is no default, and it is stated on every call.** Only the caller knows whether a late
 call is still the right call — an unpaid order expires on time or not at all, a report is wanted
@@ -139,12 +142,23 @@ it already past its bound and leaves it. State an `overdue` several times `discr
 `null`.
 
 **A cancellation is reliable while the call is further out than `discreteness`**, and is a race
-closer than that, where the call may already be on its way.
+closer than that, where the call may already be on its way. What bounds it is the period between
+passes: a cancelled call stops being owed, the next pass stops reading it, and a call taken in
+hand is given up again when that happens.
+
+**A call is due by the clock of whichever replica took the `delay`**, and made by the clock of
+whichever one dispatches it. The overlap covers the disagreement between two machines kept in
+ordinary time; nothing here measures it.
 
 So `discreteness` and `overdue` are chosen together against what the application needs. A call
 that must be made within seconds of its time, or cancellable within seconds of it, needs a
 `discreteness` of seconds — at the cost of looking the calls over that much more often.
 
+**A pass takes a bounded number of calls**, 200 to a replica, oldest first. Where more than that
+come due to one replica in one period, the rest are taken on a later pass and are late by however
+long that took; where it is logged, the rate is past what one period can carry. Replicas divide
+the lanes between them, so the ceiling is per replica rather than for the application.
+
 ### What to expect
 
 **A call may be made more than once**, so where a second one would cost something, the target
@@ -179,10 +193,10 @@ may no longer be one it accepts. Either way the attempt is spent.
 ```yaml
 # context.toa.yaml
 cadence:
-  discreteness: 60    # seconds between passes over the calls waiting to be made
+  discreteness: 60 # seconds between passes over the calls waiting to be made
 ```
 
 `discreteness` is how often the calls waiting to be made are looked over. It defaults to 60,
-which is what an application that states nothing gets. It is the floor under how closely a
-delayed call can be cancelled and how small an `overdue` is worth stating — see
+which is what an application that states nothing gets. It sets how small an `overdue` is worth
+stating, and it is the floor under how closely a delayed call can be cancelled — see
 [Discreteness](#discreteness) — and lowering it costs a pass that runs more often.

package/schemas/declaration.cos.yaml

@@ -16,6 +16,5 @@ patternProperties:
           and the operation is told which interval it is running for.
         type: integer
         minimum: 1
-        default: 1
     required: [cycle]
     additionalProperties: false

package/source/Aspect.ts

@@ -17,14 +17,13 @@ interface Input {
  * handing over the call it should have scheduled loses the call, and there is no way for this
  * to know. Where the semantics allow it, hand the call over first.
  *
- * @implements {toa.core.extensions.Aspect}
  */
 export class Aspect extends Connector {
   public readonly name = 'delay'
 
   private readonly metronome: Local
 
-  public constructor (metronome: Local) {
+  public constructor(metronome: Local) {
     super()
 
     this.metronome = metronome
@@ -34,18 +33,28 @@ export class Aspect extends Connector {
 
   // named rather than forwarded, so that the connector's lifecycle is not reachable from an
   // algorithm — the same reason the atom aspect names its own
-  public async invoke (method: string, ...args: any[]): Promise<unknown> {
+  public async invoke(method: string, ...args: any[]): Promise<unknown> {
     switch (method) {
-      case 'delay': return await this.delay(args[0], args[1], args[2])
-      case 'cancel': return await this.cancel(args[0])
-      default: throw new Error(`Delay aspect has no '${method}' method`)
+      case 'delay':
+        return await this.delay(args[0], args[1], args[2])
+      case 'cancel':
+        return await this.cancel(args[0])
+      default:
+        throw new Error(`Delay aspect has no '${method}' method`)
     }
   }
 
   /** Answers the id the call was given, which is what cancels it. */
-  private async delay (endpoint: string, request: object | null,
-    options: Options): Promise<unknown> {
-    const input: Input = { endpoint, interval: options.interval, overdue: options.overdue }
+  private async delay(
+    endpoint: string,
+    request: object | null,
+    options: Options
+  ): Promise<unknown> {
+    const input: Input = {
+      endpoint,
+      interval: options.interval,
+      overdue: options.overdue
+    }
 
     // a call that takes no request carries none, rather than a null one
     if (request !== null && request !== undefined) input.request = request
@@ -58,7 +67,7 @@ export class Aspect extends Connector {
    * nothing to terminate and raises; one whose call has already been made has a row still, and
    * terminating it again is not an error.
    */
-  private async cancel (id: string): Promise<unknown> {
+  private async cancel(id: string): Promise<unknown> {
     return await this.metronome.invoke('terminate', { query: { id }, input: null })
   }
 }

package/source/Composition.ts

@@ -5,7 +5,7 @@ import type { Dirent } from 'node:fs'
 import type { Host } from './Factory.js'
 
 /** The components this extension ships, which run inside its own service. */
-export function components (): Components {
+export function components(): Components {
   const labels: string[] = []
   const paths: string[] = []
 
@@ -20,13 +20,13 @@ export function components (): Components {
 export class Composition extends Connector {
   private readonly host: Host
 
-  public constructor (host: Host) {
+  public constructor(host: Host) {
     super()
 
     this.host = host
   }
 
-  protected override async open (): Promise<void> {
+  protected override async open(): Promise<void> {
     const composition = await this.host.composition(components().paths)
 
     await composition.connect()
@@ -35,7 +35,7 @@ export class Composition extends Connector {
   }
 }
 
-function entries (): Dirent[] {
+function entries(): Dirent[] {
   return readdirSync(ROOT, { withFileTypes: true }).filter((entry) => entry.isDirectory())
 }