@hasna/events 0.1.13 → 0.1.15

package/LICENSE

@@ -1,17 +1,202 @@
-Apache License
-Version 2.0, January 2004
-http://www.apache.org/licenses/
 
-Copyright 2026 Hasna
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
 
-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
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 
-http://www.apache.org/licenses/LICENSE-2.0
+   1. Definitions.
 
-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.
+      "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 Hasna
+
+   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

@@ -8,7 +8,49 @@ This package is local-first. By default it stores JSON files under `~/.hasna/eve
 - `events.json`
 - `deliveries.json`
 
-Override the data directory with `HASNA_EVENTS_DIR`, `HASNA_EVENTS_HOME`, or the CLI `--dir` flag.
+The CLI `--dir` flag has highest precedence, followed by `HASNA_EVENTS_DIR`,
+then the legacy `HASNA_EVENTS_HOME` fallback.
+
+## Storage Runtime Contract
+
+The default compatibility runtime is local JSON files. It does not use local
+SQLite, remote Postgres, S3, AWS infrastructure, or live cloud mutation. Apps
+that require cross-process idempotency and restart-safe webhook delivery should
+use the opt-in durable spool and SQLite broker described below.
+
+```ts
+import { getEventsStatus } from "@hasna/events";
+
+const status = await getEventsStatus();
+
+console.log(status.storage);
+// {
+//   mode: "local-files",
+//   localFiles: true,
+//   localSqlite: false,
+//   remote: false,
+//   postgres: false,
+//   s3: false,
+//   aws: false,
+//   idempotency: "best-effort-local",
+//   replayCursors: true
+// }
+```
+
+Cloud-backed stores should implement the same `EventsStore` interface and, for
+durable event-bus use, the optional `appendEventOnce` and `listEventsPage`
+methods. `appendEventOnce` is the storage-layer hook for atomic idempotency by
+`id` or `dedupeKey`, such as a Postgres unique constraint or equivalent
+provider guarantee. `listEventsPage` returns an opaque cursor page for bounded
+replay. The local JSON store implements these hooks for deterministic local
+tests, but its idempotency is best-effort local file behavior, not a
+cross-process database lock.
+
+Remote Postgres/S3/AWS adapters should keep credentials and infrastructure
+provisioning outside this package configuration, report their storage mode in
+`status.storage`, and avoid emitting live external deliveries during store
+tests. Creating buckets, databases, secrets, migrations, or production data
+changes is an explicit deployment/approval step, not part of this local runtime.
 
 ## Install
 
@@ -16,7 +58,8 @@ Override the data directory with `HASNA_EVENTS_DIR`, `HASNA_EVENTS_HOME`, or the
 bun add @hasna/events
 ```
 
-This package is not published by this repository setup step. Apps can also depend on the local workspace path while the rollout is in progress.
+The core CLI and durable SQLite broker require Bun 1.0 or newer. The isolated
+`@hasna/events/durable-spool` producer export supports Node 20 or newer.
 
 ## Event Envelope
 
@@ -42,21 +85,74 @@ await events.emit({
 });
 ```
 
-Envelope fields are:
+Only `source` and `type` are required inputs. `id` defaults to a UUID, `time`
+to the current ISO timestamp, `severity` to `info`, `data` and `metadata` to
+empty objects, and `schemaVersion` to `1.0`. `subject`, `message`, and
+`dedupeKey` are optional.
+
+`source` should be the emitting app or bounded context. `type` should use dot
+notation such as `ticket.created`, `repo.synced`, or `check.failed`. Emission
+deduplicates by either an explicit `id` or `dedupeKey` by default; a duplicate
+is neither stored nor delivered again. Library callers can pass
+`{ dedupe: false }` to store a duplicate intentionally.
+
+## Package Entry Points
+
+The root export includes the client, types, storage, filtering, signing,
+transports, and catalog APIs. Focused entry points are also available:
+
+- `@hasna/events/storage`
+- `@hasna/events/signing`
+- `@hasna/events/filter`
+- `@hasna/events/transports`
+- `@hasna/events/catalog`
+- `@hasna/events/commander`
+- `@hasna/events/cli`
+
+## Typed Event Catalog (Distribution Events)
+
+`@hasna/events/catalog` binds well-known envelope `type` strings to the
+`@hasna/contracts` schema ids their `data` payloads mirror, and provides an
+OPT-IN emit-time validator hook.
+
+Distribution event types (`DISTRIBUTION_EVENT_TYPES`):
+
+| Event type | Contracts schema (`data` mirror) |
+| --- | --- |
+| `release.published` | `hasna.release.v1` |
+| `release.rollout.started` | `hasna.rollout_record.v1` |
+| `release.rollout.completed` | `hasna.rollout_record.v1` |
+| `release.rollout.failed` | `hasna.rollout_record.v1` |
+| `app.installed` | `hasna.rollout_record.v1` |
+| `announcement.sent` | `hasna.announcement.v1` |
+| `feedback.created` | `hasna.feedback.v1` |
+| `feedback.triaged` | `hasna.feedback.v1` |
+
+```ts
+import { EventsClient, EventTypeCatalog, registerDistributionEventTypes } from "@hasna/events";
+
+const catalog = registerDistributionEventTypes(new EventTypeCatalog());
+const client = new EventsClient({ catalog, validateCatalogTypes: true });
+
+// Registered type with an invalid payload throws EventValidationError
+// BEFORE the event is stored or delivered.
+await client.emit({
+  source: "open-publish",
+  type: "release.published",
+  data: { appId: "open-todos" },
+});
+```
+
+Validation is fully backward compatible:
 
-- `id`
-- `source`
-- `type`
-- `time`
-- `subject`
-- `severity`
-- `data`
-- `message`
-- `dedupeKey`
-- `schemaVersion`
-- `metadata`
+- It is OFF by default (`validateCatalogTypes` defaults to `false`).
+- Unregistered/free-form event types ALWAYS pass, even when validation is on.
+- A per-emit `validate` option overrides the client setting in both directions.
 
-`source` should be the emitting app or bounded context. `type` should use dot notation such as `ticket.created`, `repo.synced`, or `check.failed`.
+Payload types (`ReleasePublishedData`, `RolloutData`, `AppInstalledData`,
+`AnnouncementSentData`, `FeedbackCreatedData`, `FeedbackTriagedData`) are
+dependency-free structural mirrors of the contracts schemas; this package does
+not depend on `@hasna/contracts` at runtime.
 
 ## OpenAutomations Trigger Ingress
 
@@ -123,7 +219,11 @@ await events.addChannel({
 });
 ```
 
-Filters support `*` wildcards and nested `data` or `metadata` paths.
+All matchers inside one filter are ANDed. Multiple filters on a channel are
+ORed. A channel with no filters accepts every event, while a disabled channel
+accepts none. String matchers support `*` and `**`; `data` and `metadata`
+matchers also support nested or literal dotted keys, primitive array-member
+matching, typed values, and negative matchers.
 
 ## Webhook Transport
 
@@ -131,10 +231,19 @@ Webhook delivery sends a `POST` with the event envelope as JSON.
 
 Headers:
 
+- `Content-Type: application/json`
+- `User-Agent: @hasna/events`
 - `X-Hasna-Event-Id`
 - `X-Hasna-Event-Type`
 - `X-Hasna-Timestamp`
-- `X-Hasna-Signature` when `webhook.secret` is configured
+- `X-Hasna-Signature` when `webhook.secret` or `webhook.secretRef` resolves
+
+`X-Hasna-Timestamp` is the current delivery-attempt time and is what the HMAC
+signs. The envelope `time` in the JSON body remains the original event time, so
+delayed imports and retries receive fresh replay-window signatures without
+rewriting domain history.
+Custom webhook headers whose names begin with `X-Hasna-` are rejected so channel
+configuration cannot replace signed delivery metadata.
 
 Signatures use HMAC-SHA256 over:
 
@@ -160,6 +269,113 @@ const ok = verifyWebhookSignature(secret, timestamp, body, signature);
 Pass an explicit `toleranceMs` when a consumer needs a tighter or wider replay
 window.
 
+## Durable Node Producer And Bun Delivery Worker
+
+`@hasna/events/durable-spool` is the producer boundary for Node 20+ apps. It
+has no Bun runtime import and performs no network access. Each enqueue writes a
+mode-0600 temporary file, fsyncs it, hard-links it without replacement to an
+identity-keyed final name, removes the temporary file, and fsyncs the inbox
+directory. Concurrent producers with the same `dedupeKey` converge on one
+immutable record.
+
+```ts
+import { DurableEventSpool } from "@hasna/events/durable-spool";
+
+const spool = new DurableEventSpool({ dataDir: process.env.HASNA_EVENTS_DIR! });
+await spool.enqueue({
+  id: "notes:note:123:created",
+  source: "notes",
+  type: "note.created",
+  time: "2026-08-06T12:00:00.000Z",
+  subject: "note:123",
+  dedupeKey: "notes:note:123:created",
+  schemaVersion: "notes.v1",
+  data: {
+    noteId: "123",
+    createdAt: "2026-08-06T12:00:00.000Z",
+    originMachine: "station03",
+  },
+  metadata: {},
+});
+```
+
+`@hasna/events/durable` is Bun-only because it uses `bun:sqlite`. The broker
+imports committed spool records into an event and matching-channel outbox in a
+SQLite `BEGIN IMMEDIATE` transaction, then removes the spool record. SQLite WAL,
+unique event/dedupe identities, unique event/channel jobs, bounded leases, and
+persisted retry timestamps make separate workers and process restarts safe.
+Producer spool records and broker event rows apply the default sensitive-key
+redaction. Each outbox row additionally applies its channel's `redact.paths`
+before the payload is persisted or delivered.
+The broker initializes schema v1 only from an empty version-0 application
+schema. Existing v1 databases must match the complete columns, constraints,
+foreign keys, and indexes; malformed or newer schemas are rejected unchanged.
+
+```ts
+import { DurableEventsBroker } from "@hasna/events/durable";
+
+const broker = new DurableEventsBroker({ dataDir: process.env.HASNA_EVENTS_DIR! });
+broker.addChannel({
+  id: "notes-created",
+  enabled: false,
+  transport: "webhook",
+  filters: [{ source: "notes", type: "note.created" }],
+  webhook: {
+    url: "https://example.com/events/notes",
+    secretRef: "env:HASNA_NOTES_WEBHOOK_SECRET",
+  },
+  retry: { maxAttempts: 5, backoffMs: 1_000, multiplier: 2 },
+});
+
+broker.importSpool();
+await broker.drain();
+broker.close();
+```
+
+Durable SQLite channels reject inline `webhook.secret` values. The default
+resolver supports `env:VARIABLE_NAME`; callers can inject a vault-backed
+resolver. Resolved credential values are used only to sign the in-memory HTTP
+request and are never stored in channel configuration, the outbox, delivery
+history, or status output.
+
+Any HTTP 2xx response acknowledges delivery. The receiver therefore must return
+2xx only after durably enqueueing the event and must deduplicate by `dedupeKey`
+or `id`. Non-2xx responses, timeouts, and unresolved runtime secrets follow the
+persisted retry schedule. Exhausted jobs remain `dead`; an operator can call
+`retryDead({ eventId, channelId, limit })` or use `events durable retry-dead`
+without creating a second event/channel outbox identity.
+
+The Bun CLI exposes the same operator boundary:
+
+```bash
+events --dir "$HASNA_EVENTS_DIR" durable channel https://example.com/events/notes \
+  --id notes-created --source notes --type note.created \
+  --secret-ref env:HASNA_NOTES_WEBHOOK_SECRET --disabled
+
+events --dir "$HASNA_EVENTS_DIR" durable drain --limit 100
+events --dir "$HASNA_EVENTS_DIR" durable work --limit 100
+events --dir "$HASNA_EVENTS_DIR" durable retry-dead --limit 100
+events --dir "$HASNA_EVENTS_DIR" durable status
+```
+
+`durable drain` imports and processes one bounded batch, then exits. Enqueueing
+alone never performs network delivery. `durable work` is the long-running Bun
+worker: it watches only the durable spool inbox, debounces file events, imports
+and drains immediately, wakes at the next persisted retry timestamp, and runs a
+low-frequency bounded reconciliation in case a filesystem notification was
+missed. It never watches Apple Notes or note files. SIGTERM and SIGINT stop it
+cleanly. Each worker claims only the job it is about to dispatch, and only the
+current lease owner can settle it. Delivery is still at-least-once: if a request
+outlives its lease, another worker may retry it, so receivers must deduplicate by
+`dedupeKey` or `id`. This package change does not install, start, or enable a
+runner; a canary deployment must supervise one `durable work` process explicitly.
+
+Webhook requests time out after 15 seconds unless `webhook.timeoutMs` is set.
+Non-2xx responses and network failures are recorded as failed attempts. The
+compatibility JSON delivery path stores response bodies truncated after 4,096
+characters; durable delivery intentionally omits response bodies, stdout, and
+stderr from its outbox and delivery history.
+
 ## Command Transport
 
 Command channels run a local process and pass the event on stdin and environment variables.
@@ -194,19 +410,28 @@ Environment variables:
 - `HASNA_EVENT_SCHEMA_VERSION`
 - `HASNA_EVENT_JSON`
 
-The transport type union already reserves `email`, `sse`, and `mcp-relay` for later implementations.
+Command processes time out after 15 seconds unless `command.timeoutMs` is set.
+Their stdout and stderr are stored on the delivery attempt and truncated after
+4,096 characters. A zero exit code succeeds; other exits or signals fail.
+
+Both implemented transports use one attempt by default. Channel retry policy
+can increase `maxAttempts`; failed attempts back off from 250 ms by a default
+multiplier of 2 unless overridden. The transport type union reserves `email`,
+`sse`, and `mcp-relay`, but the CLI refuses to configure them and direct
+dispatch currently records them as skipped.
 
 ## Redaction
 
 Events scrub obvious sensitive keys such as `secret`, `token`, `password`,
-`apiKey`, and `authorization` before local storage and delivery by default.
+`apiKey`, `api_key`, `api-key`, and `authorization` recursively before local
+storage and delivery by default.
 Callers that intentionally need raw local payloads can pass:
 
 ```ts
 await events.emit(input, { redactSensitiveData: false });
 ```
 
-Use channel-level paths for config-only redaction:
+Use channel-level paths for per-channel delivery redaction:
 
 ```ts
 await events.addChannel({
@@ -235,6 +460,12 @@ const events = new EventsClient({
 
 The package exposes `events` and `hasna-events`.
 
+Global options must come before the command group:
+
+```bash
+events --dir /tmp/events --json status
+```
+
 ```bash
 events channels add https://example.com/channels/hasna \
   --id ops \
@@ -245,13 +476,16 @@ events channels add https://example.com/channels/hasna \
 
 events channels list
 events channels test ops
+events channels match ops
 events channels remove ops
 ```
 
 Field filters can match nested `data` or `metadata` values. Plain
 `--data`/`--metadata` values are strings, which keeps ids and slugs such as
 `001` intact. Use `--data-json` or `--metadata-json` for typed JSON predicates.
-Dot paths access nested object keys; dots inside key names are not escaped yet.
+Dot paths check both nested object keys and literal dotted keys; there is no
+syntax to distinguish between those two forms yet. A negative predicate also
+matches when its field is absent.
 When the actual event value is an array, string filters match any primitive
 array member, which is useful for tag routing such as `data.tags=auto:route`.
 Use `path!=value` or `path!=json` for negative predicates such as
@@ -305,21 +539,35 @@ events events emit ticket.created \
   --data '{"ticketId":123}'
 
 events events list --limit 20
+events events list --source tickets --type ticket.created
 events events replay --type ticket.created
+events events replay --type ticket.created --dry-run --limit 100
+events events replay --type ticket.created --cursor "$NEXT_CURSOR" --limit 100
 events events replay --dry-run
 ```
 
-Machine-readable status:
+Replay cursors are opaque and tied to the same filter set (`--id`, `--source`,
+and `--type`) used to produce them. Use the `nextCursor` returned by the
+previous JSON replay response rather than constructing cursor strings in
+callers. A replay without `--limit` or `--cursor` processes all matching events;
+use those flags when callers need bounded page-by-page replay.
+
+Machine-readable status (global flags precede `status`):
 
 ```bash
-events status --json
+events --json status
 ```
 
-The status contract reports event, channel, delivery, file, and transport counts
-only. It does not include event payloads, webhook signing secrets, command
-environment values, or channel targets.
+The status contract reports storage runtime, event, channel, delivery, file, and
+transport metadata only. It does not include event payloads, webhook signing
+secrets, command environment values, or channel targets.
 
 Use `--json` for script-friendly output and `--dir <path>` for isolated data.
+The standalone `events events list` command has no implicit row cap. Commands
+registered into another Commander program with `registerEventsCommands` default
+to the 100 most recent rows, accept a host override, and use `--limit 0` to list
+all rows. The embedded emitter also supports `--no-dedupe`; the standalone CLI
+does not currently expose that library option.
 
 ## App Integration Pattern