@eltjs/eca 0.0.0-stage → 0.3.2

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 ezzabuzaid
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,201 @@
-# Temporary Holding Version
+# @eltjs/eca
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A user wants to know when the data in a warehouse starts to match a condition. For example: "when my card purchases in the first 10 days of a month pass 200 JOD, tell me". An agent writes the condition as code with SQL in it. A condition reads the warehouse at two positions, before and after, and it gives what became true between them. The host keeps one cursor for each rule, gives it to each evaluation, and saves the cursor that it gets back with the matches. eca keeps nothing. The model is Event–Condition–Action (ECA), from active databases: a new position of the warehouse is the event, and the host does the action.
+
+The words in these documents have one meaning each. See the glossary in [CONTEXT.md](./CONTEXT.md).
+
+## Use it
+
+The host makes one `Eca` with its warehouse and a clock. It starts each new rule, and then evaluates its rules when it wants:
+
+```ts
+import { Eca } from '@eltjs/eca';
+
+const eca = new Eca<DatabaseSync, { month: string; spent: number }>({
+  warehouse,
+  clock: globalThis,
+});
+const spend = { condition: new EarlyMonthSpend() };
+cursors.set(spend, await eca.start());
+
+for await (const outcome of eca.evaluate(
+  [...cursors].map(([rule, cursor]) => ({ rule, cursor })),
+)) {
+  if ('expired' in outcome) continue; // the host decides; see below
+  await transaction(async (tx) => {
+    for (const { month, spent } of outcome.matches)
+      await outbox(
+        tx,
+        `You spent ${spent} JOD in the first 10 days of ${month}.`,
+      );
+    await saveCursor(tx, outcome.rule, outcome.cursor);
+  });
+}
+```
+
+- A rule is the host's own object with a `condition`. Each outcome carries it back as `outcome.rule`, with the host's own type, so a rule can hold what the host needs, such as the name its cursor is saved under.
+- `start()` gives the cursor of a new rule: the newest position of the warehouse, now. The rule matches only what becomes true after it.
+- `evaluate(rules)` gives one outcome for each rule, in order. The host saves its matches and its cursor in one transaction of its own, so a stop between them loses no match and repeats none.
+- The two type parameters are the handle of the warehouse and the data of a match. Give a union when the rules have different data.
+- The host decides when to evaluate: after each pass, on a timer, or when a user asks. See [ADR 0001](./docs/adr/0001-the-host-decides-when-a-rule-is-evaluated.md).
+
+## Give eca the warehouse
+
+eca does not open the warehouse, and it does not know what holds it. The host gives a `Warehouse` with two methods:
+
+- `stable(after)` gives the positions after a position, in ascending order, or `{ expired }`. A position names a commit where no pass is half done.
+- `read(position?)` gives a reading of the warehouse as of a position, or as of its newest one: `{ sql, position, at }`, which eca disposes, or `{ expired }`.
+
+elt's SQLite and Postgres destinations give both. The adapter is two lines:
+
+```ts
+import type { DatabaseSync } from 'node:sqlite';
+
+import type { Warehouse } from '@eltjs/eca';
+
+const warehouse: Warehouse<DatabaseSync> = {
+  stable: async (after) => destination.positions(after),
+  read: async (position) => destination.reading(position),
+};
+```
+
+A Postgres destination gives a `postgres.Sql` reading, whose reader views read the database as of the position. See [ADR 0005](./docs/adr/0005-eca-reads-the-warehouse-through-a-port.md).
+
+## Write a condition
+
+A condition has one method: `evaluate(before, after)`. Each argument is a reading: `sql`, the handle of the warehouse as of a position, and `at`, the time that the reading stands for. It resolves to what matches in `after` that did not match in `before`:
+
+```ts
+import type { DatabaseSync } from 'node:sqlite';
+
+import type { Condition, Reading } from '@eltjs/eca';
+
+// The months whose card purchases of Arab Bank in days 1 to 10 pass 200 JOD,
+// on the clock of the user, by the time of the SMS, in fils.
+function overLimit(sql: DatabaseSync): Map<string, number> {
+  const fils = new Map<string, number>();
+  for (const { text, date } of sql
+    .prepare(`SELECT text, date FROM messages WHERE handle = 'Arab Bank'`)
+    .all()) {
+    if (typeof text !== 'string' || typeof date !== 'string') continue;
+    const amount =
+      /تم قيد حركة شراء من حسابكم .* بمبلغ JOD (\d+)\.(\d{3}) /u.exec(text);
+    if (amount === null) continue;
+    const day = Temporal.Instant.from(date).toZonedDateTimeISO('Asia/Amman');
+    if (day.day > 10) continue;
+    const month = day.toPlainDate().toPlainYearMonth().toString();
+    fils.set(
+      month,
+      (fils.get(month) ?? 0) + Number(`${amount[1]}${amount[2]}`),
+    );
+  }
+  return new Map([...fils].filter(([, spent]) => spent > 200_000));
+}
+
+class EarlyMonthSpend implements Condition<
+  DatabaseSync,
+  { month: string; spent: number }
+> {
+  async evaluate(before: Reading<DatabaseSync>, after: Reading<DatabaseSync>) {
+    const was = overLimit(before.sql);
+    return [...overLimit(after.sql)]
+      .filter(([month]) => !was.has(month))
+      .map(([month, spent]) => ({ month, spent: spent / 1000 }));
+  }
+}
+```
+
+- The pattern is "true after, and not true before". What to compare is the condition's own choice: here a month, or an id, a day, or one text.
+- The condition parses its own data. SQL reads the rows, and the code reads the text. See [ADR 0004](./docs/adr/0004-each-condition-parses-its-own-data.md).
+- A condition on time reads `before.at` and `after.at`: a deadline that passes is one with `before.at < due <= after.at`. Each evaluation starts at the `at` where the last one ended, so it matches once.
+- Judge a window by the time in the data, not by the time of the evaluation. A commit can be late.
+
+## The walk
+
+`evaluate` walks each rule from its cursor over each position after it. In each step, one thing moves between `before` and `after`:
+
+1. Time moves up to the commit of the next position, with the data as it was.
+2. The data moves to the next position, at that time.
+3. After the last position, time moves up to now.
+
+Thus:
+
+- A key that stops matching and matches again between two evaluations matches again. A rule that the host evaluates once a day hears of each crossing of the day.
+- A deadline that passes while a task is open matches, also when a later position closed the task, because it is read with the data of that time.
+- A step in which nothing moves is skipped. With no new position, the walk is one step: time, from the cursor up to now.
+- At most two readings are open at once.
+
+See [ADR 0010](./docs/adr/0010-eca-is-a-stateless-reader-over-warehouse-positions.md).
+
+## Outcomes
+
+| Outcome                            | When                                                   | The cursor                  |
+| ---------------------------------- | ------------------------------------------------------ | --------------------------- |
+| `{ rule, matches, cursor }`        | The walk ended                                         | At the newest position, now |
+| `{ rule, matches, error, cursor }` | The condition threw at a step                          | After the last good step    |
+| `{ rule, expired }`                | The warehouse can no longer read the cursor's position | None                        |
+
+- A failure keeps the matches of the steps before it. The next evaluation goes on from the last good step, so a failure that passes, such as a lock, loses nothing. The other rules of the call still run. See [ADR 0008](./docs/adr/0008-a-failing-condition-is-yielded-with-the-matches-before-it.md).
+- A position expires when it is older than the retention of the warehouse, or when a fresh run made the warehouse again. The reason says which. The host decides what to do: start the rule again with `start()`, or tell the user. eca never skips it silently.
+- A cursor that eca did not make is a `TypeError`. A warehouse with no position yet makes `start()` throw: load it first.
+
+## Remove, pause and resume a rule
+
+eca keeps nothing, so these need no API:
+
+- **Remove** a rule: stop giving its cursor, and delete it.
+- **Pause** a rule: keep its cursor, and do not give it.
+- **Resume** a rule: give its cursor again. The walk covers each position that it missed, within the retention of the warehouse.
+
+## What eca does not do
+
+- No store. The host saves the cursor of each rule, with its matches.
+- No schedule. The host evaluates when it wants; a condition on time matches when the host evaluates after the time passed.
+- No news of a match whose data changed, or of a match that stopped, unless the condition asks for it. "True after and not before" is the condition's own choice.
+- No routing. Each evaluation evaluates the rules that the host gives. A condition can read the whole warehouse.
+
+## The same concepts in other systems
+
+| This package                          | Other systems                                                                                                      |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| Rule: event, condition, action        | ECA rules of active databases (HiPAC, 1988); Home Assistant automations: trigger, condition, action                |
+| Position, `stable(after)`             | SQL Server change tracking: `CHANGE_TRACKING_CURRENT_VERSION`, `CHANGETABLE(… @since)`; Kafka's last stable offset |
+| Reading as of a position              | SQL:2011 system-versioned tables, `FOR SYSTEM_TIME AS OF`                                                          |
+| Expired position                      | `CHANGE_TRACKING_MIN_VALID_VERSION`; a Kafka offset older than the log's retention                                 |
+| Cursor that the host saves            | A Kafka consumer's committed offset, saved with its output in one transaction                                      |
+| Matches and cursor in one transaction | The transactional outbox                                                                                           |
+| Warehouse port and the host's adapter | Ports and adapters; the `Dialect` of Kysely                                                                        |
+
+## Documentation
+
+- [ADR 0001: The host decides when a rule is evaluated](./docs/adr/0001-the-host-decides-when-a-rule-is-evaluated.md)
+- [ADR 0002: A new rule starts from a baseline](./docs/adr/0002-a-new-rule-starts-from-a-baseline.md) (superseded)
+- [ADR 0003: The host acts on each outcome](./docs/adr/0003-the-host-acts-on-each-outcome.md)
+- [ADR 0004: Each condition parses its own data](./docs/adr/0004-each-condition-parses-its-own-data.md)
+- [ADR 0005: eca reads the warehouse through a port](./docs/adr/0005-eca-reads-the-warehouse-through-a-port.md)
+- [ADR 0006: eca keeps no state across restarts](./docs/adr/0006-eca-keeps-no-state-across-restarts.md) (superseded)
+- [ADR 0007: eca yields only new matches](./docs/adr/0007-eca-yields-only-new-matches.md) (superseded)
+- [ADR 0008: A failing condition is yielded with the matches before it](./docs/adr/0008-a-failing-condition-is-yielded-with-the-matches-before-it.md)
+- [ADR 0009: A host gives a rule back its keys](./docs/adr/0009-a-host-gives-a-rule-back-its-keys.md) (superseded)
+- [ADR 0010: eca is a stateless reader over warehouse positions](./docs/adr/0010-eca-is-a-stateless-reader-over-warehouse-positions.md)
+
+## Development
+
+Run the commands from the workspace root.
+
+```sh
+npx nx run eca:test        # builds, then runs the tests
+npx nx run eca:typecheck   # formats, lints, then type checks
+npx nx run eca:build       # compiles src/ to dist/
+```
+
+The tests run a real elt `Pipeline` into a real SQLite destination, and read it through the destination's positions and readings.
+
+```
+src/
+  eca.ts         Eca: start, evaluate, and the walk
+  rule.ts        Rule, Condition, Outcome
+  warehouse.ts   the Warehouse port and Reading
+  index.ts       the public exports
+  eca.test.ts    the tests
+```

package/dist/eca.d.ts

@@ -0,0 +1,45 @@
+import type { Outcome, Rule } from './rule.ts';
+import type { Warehouse } from './warehouse.ts';
+/**
+ * The time of an evaluation. A host gives `globalThis`; a test can give a
+ * clock it moves.
+ */
+export type Clock = {
+    readonly Temporal: {
+        readonly Now: {
+            instant(): Temporal.Instant;
+        };
+    };
+};
+/**
+ * Evaluates rules over the warehouse. It keeps nothing: each rule's cursor is
+ * the host's, which gives it to each evaluation and saves the one it gets
+ * back. A rule the host does not give is not evaluated, so a host removes,
+ * pauses and resumes a rule by what it keeps.
+ */
+export declare class Eca<Sql, Data> {
+    #private;
+    constructor({ warehouse, clock, }: {
+        readonly warehouse: Warehouse<Sql>;
+        readonly clock: Clock;
+    });
+    /**
+     * The cursor of a new rule: the newest position, now. The rule matches only
+     * what becomes true after it. A warehouse with no position yet throws: load
+     * it first.
+     */
+    start(): Promise<string>;
+    /**
+     * One outcome for each rule, in order. Each rule walks from its cursor over
+     * each position after it, and in each step its condition evaluates two
+     * readings in which one thing moved: time, with the data as it was, up to
+     * the commit of the next position; then the data, at that time; and last,
+     * time up to now. So a key that stops matching and matches again between
+     * two evaluations matches again, and a time that passes is read with the
+     * data current then. Every rule of one call ends at the same time.
+     */
+    evaluate<R extends Rule<Sql, Data>>(rules: Iterable<{
+        readonly rule: R;
+        readonly cursor: string;
+    }>): AsyncGenerator<Outcome<Sql, Data, R>>;
+}

package/dist/eca.js

@@ -0,0 +1,127 @@
+/**
+ * Evaluates rules over the warehouse. It keeps nothing: each rule's cursor is
+ * the host's, which gives it to each evaluation and saves the one it gets
+ * back. A rule the host does not give is not evaluated, so a host removes,
+ * pauses and resumes a rule by what it keeps.
+ */
+export class Eca {
+    #warehouse;
+    #clock;
+    constructor({ warehouse, clock, }) {
+        this.#warehouse = warehouse;
+        this.#clock = clock;
+    }
+    /**
+     * The cursor of a new rule: the newest position, now. The rule matches only
+     * what becomes true after it. A warehouse with no position yet throws: load
+     * it first.
+     */
+    async start() {
+        const reading = await this.#warehouse.read();
+        if ('expired' in reading)
+            throw new Error(reading.expired);
+        await using _reading = reading;
+        return encode({
+            position: reading.position,
+            at: this.#clock.Temporal.Now.instant(),
+        });
+    }
+    /**
+     * One outcome for each rule, in order. Each rule walks from its cursor over
+     * each position after it, and in each step its condition evaluates two
+     * readings in which one thing moved: time, with the data as it was, up to
+     * the commit of the next position; then the data, at that time; and last,
+     * time up to now. So a key that stops matching and matches again between
+     * two evaluations matches again, and a time that passes is read with the
+     * data current then. Every rule of one call ends at the same time.
+     */
+    async *evaluate(rules) {
+        const now = this.#clock.Temporal.Now.instant();
+        for (const { rule, cursor } of rules)
+            yield await this.#walk(rule, decode(cursor), now);
+    }
+    // At most two readings are open: a step's before and its after. The before
+    // closes once its step has evaluated, so a long pause holds no more.
+    async #walk(rule, from, now) {
+        const positions = await this.#warehouse.stable(from.position);
+        if ('expired' in positions)
+            return { rule, expired: positions.expired };
+        const opened = await this.#warehouse.read(from.position);
+        if ('expired' in opened)
+            return { rule, expired: opened.expired };
+        let held = opened;
+        let before = { sql: opened.sql, ...from };
+        const matches = [];
+        // Evaluates one step, or gives the outcome of its failure: the cursor
+        // stays after the last step that evaluated.
+        const step = async (after) => {
+            try {
+                matches.push(...(await rule.condition.evaluate(before, after)));
+            }
+            catch (error) {
+                return { rule, matches, error, cursor: encode(before) };
+            }
+            before = after;
+            return undefined;
+        };
+        // A step in which time does not move changes nothing.
+        const until = (at) => Temporal.Instant.compare(at, before.at) > 0
+            ? step({ ...before, at })
+            : undefined;
+        try {
+            for (const position of positions) {
+                const reading = await this.#warehouse.read(position);
+                if ('expired' in reading)
+                    return { rule, expired: reading.expired };
+                try {
+                    const at = latest(reading.at, before.at, now);
+                    const failed = (await until(at)) ??
+                        (await step({ sql: reading.sql, position, at }));
+                    if (failed !== undefined)
+                        return failed;
+                }
+                finally {
+                    await dispose(held);
+                    held = reading;
+                }
+            }
+            return (await until(now)) ?? { rule, matches, cursor: encode(before) };
+        }
+        finally {
+            await dispose(held);
+        }
+    }
+}
+async function dispose(resource) {
+    if (Symbol.asyncDispose in resource)
+        await resource[Symbol.asyncDispose]();
+    else
+        resource[Symbol.dispose]();
+}
+// The commit time of a position, kept within the walk: never before the step
+// it follows, as a position can become stable after an evaluation that came
+// later than its commit, and never past the evaluation's time.
+function latest(at, floor, ceiling) {
+    if (Temporal.Instant.compare(at, floor) < 0)
+        return floor;
+    if (Temporal.Instant.compare(at, ceiling) > 0)
+        return ceiling;
+    return at;
+}
+function encode({ position, at }) {
+    return JSON.stringify({ position, at: at.toString() });
+}
+function decode(cursor) {
+    let parsed;
+    try {
+        parsed = JSON.parse(cursor);
+    }
+    catch {
+        parsed = undefined;
+    }
+    const position = Reflect.get(Object(parsed), 'position');
+    const at = Reflect.get(Object(parsed), 'at');
+    if (typeof position !== 'string' || typeof at !== 'string')
+        throw new TypeError(`${cursor} is not a cursor that eca made`);
+    return { position, at: Temporal.Instant.from(at) };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { type Clock, Eca } from './eca.ts';
+export type { Condition, Outcome, Rule } from './rule.ts';
+export type { Reading, Warehouse } from './warehouse.ts';

package/dist/index.js

@@ -0,0 +1 @@
+export { Eca } from './eca.js';

package/dist/rule.d.ts

@@ -0,0 +1,41 @@
+import type { Reading } from './warehouse.ts';
+/**
+ * What became true between two readings of the warehouse: the agent writes it
+ * as code, with SQL in it, and it gives what matches in `after` that did not
+ * in `before`. `before.at` and `after.at` bound the time it covers, so a
+ * condition on time, such as a deadline that passes, matches once.
+ */
+export interface Condition<Sql, Data> {
+    evaluate(before: Reading<Sql>, after: Reading<Sql>): Promise<readonly Data[]>;
+}
+/**
+ * The host's own object: an outcome carries it back, with the host's own type,
+ * so the host knows which rule it is about.
+ */
+export type Rule<Sql, Data> = {
+    readonly condition: Condition<Sql, Data>;
+};
+/**
+ * What one evaluation of a rule gives. The host saves the matches and the new
+ * cursor together, in one transaction of its own, and gives that cursor back
+ * at the next evaluation.
+ * - The walk ended: each match of each step, and the cursor at the newest
+ *   position.
+ * - The condition threw at a step: the matches of the steps before it, the
+ *   error, and the cursor after the last good step.
+ * - The cursor names a position that the warehouse can no longer read, such
+ *   as one older than its retention or of a warehouse made again.
+ */
+export type Outcome<Sql, Data, R extends Rule<Sql, Data> = Rule<Sql, Data>> = {
+    readonly rule: R;
+    readonly matches: readonly Data[];
+    readonly cursor: string;
+} | {
+    readonly rule: R;
+    readonly matches: readonly Data[];
+    readonly error: unknown;
+    readonly cursor: string;
+} | {
+    readonly rule: R;
+    readonly expired: string;
+};

package/dist/rule.js

@@ -0,0 +1 @@
+export {};

package/dist/warehouse.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The warehouse as of one position: `sql` reads it as it was there, and
+ * `at` is the time that the reading stands for.
+ */
+export type Reading<Sql> = {
+    readonly sql: Sql;
+    readonly position: string;
+    readonly at: Temporal.Instant;
+};
+/**
+ * What eca needs of the warehouse that its rules read, such as elt's SQLite
+ * or Postgres destination. The host gives it, so eca never learns where the
+ * data lives. A position names a commit where no pass is half done; one that
+ * the warehouse can no longer read gives `{ expired }`.
+ */
+export interface Warehouse<Sql> {
+    stable(after: string): Promise<readonly string[] | {
+        readonly expired: string;
+    }>;
+    read(position?: string): Promise<(Reading<Sql> & (AsyncDisposable | Disposable)) | {
+        readonly expired: string;
+    }>;
+}

package/dist/warehouse.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@eltjs/eca",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.2",
+  "description": "Event-condition-action rules over a warehouse that elt loads: a condition reads the warehouse at two positions, and the host saves each rule's cursor with what became true between them.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ezzabuzaid/elt",
+    "directory": "packages/eca"
+  },
+  "bugs": {
+    "url": "https://github.com/ezzabuzaid/elt/issues"
+  },
+  "homepage": "https://github.com/ezzabuzaid/elt/tree/main/packages/eca#readme",
+  "keywords": [
+    "elt",
+    "eca",
+    "event-condition-action",
+    "rules",
+    "alerts",
+    "warehouse"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/spec/**",
+    "!**/*.tsbuildinfo",
+    "!**/*.test.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=26"
+  },
+  "devDependencies": {
+    "@eltjs/elt": "^0.3.2",
+    "@eltjs/elt-sqlite": "^0.3.2",
+    "@zukhruf/sqlite-open": "^0.8.10",
+    "@zukhruf/testing": "^0.8.10"
+  }
+}