relay-dsh-plugin-events 0.2.1 → 0.2.2

package/README.md

@@ -1,10 +1,12 @@
 # Relay Events for DeepSeek Harness
 
-> **Now supports the latest DSH `0.1.2-alpha.3`.** Plugin `0.2.1` is verified on DSH `0.1.2-alpha.3`, `0.1.2-alpha.2`, and `0.1.1-rc.2`. [Install it and try the latest DSH](https://www.npmjs.com/package/relay-dsh-plugin-events) · [Compatibility details](docs/dsh-0.1.2-alpha.3.md).
+> **Now supports DSH `0.1.2-rc.1` while retaining `0.1.2-alpha.3` compatibility.** Plugin `0.2.2` is verified on both releases. [Install it from npm](https://www.npmjs.com/package/relay-dsh-plugin-events) · [Compatibility evidence](https://github.com/yangbobo2021/Relay/tree/codex/relay-foundation/dsh-lab/dsh-0.1.2-rc.1-20260903).
+
+> **Release channels:** `latest` → `0.2.2`; `next` → `0.2.1-rc.1`.
 
 ```bash
-npx @deepseek-ai/dsh@0.1.2-alpha.3 plugin --profile web add relay-dsh-plugin-events@0.2.1
-npx @deepseek-ai/dsh@0.1.2-alpha.3 web
+npx @deepseek-ai/dsh@0.1.2-rc.1 plugin --profile web add relay-dsh-plugin-events@0.2.2
+npx @deepseek-ai/dsh@0.1.2-rc.1 web
 ```
 
 [![DSH compatibility](https://img.shields.io/badge/DSH-0.1.1--rc.2%20%7C%200.1.2--alpha.2%20%7C%200.1.2--alpha.3-2f7d68)](https://github.com/deepseek-ai/deepseek-harness)

package/README.zh.md

@@ -1,10 +1,12 @@
 # 面向 DeepSeek Harness 的 Relay Events
 
-> **现已支持最新 DSH `0.1.2-alpha.3`。** 插件 `0.2.1` 已在 DSH `0.1.2-alpha.3`、`0.1.2-alpha.2` 与 `0.1.1-rc.2` 上完成兼容验证。[安装插件，立即体验最新版 DSH](https://www.npmjs.com/package/relay-dsh-plugin-events) · [兼容性详情](docs/dsh-0.1.2-alpha.3.md)。
+> **现已支持 DSH `0.1.2-rc.1`，并保留对 `0.1.2-alpha.3` 的兼容。** 插件 `0.2.2` 已在两个版本上完成验证。[从 npm 安装](https://www.npmjs.com/package/relay-dsh-plugin-events) · [兼容性证据](https://github.com/yangbobo2021/Relay/tree/codex/relay-foundation/dsh-lab/dsh-0.1.2-rc.1-20260903)。
+
+> **发布通道：** `latest` → `0.2.2`；`next` → `0.2.1-rc.1`。
 
 ```bash
-npx @deepseek-ai/dsh@0.1.2-alpha.3 plugin --profile web add relay-dsh-plugin-events@0.2.1
-npx @deepseek-ai/dsh@0.1.2-alpha.3 web
+npx @deepseek-ai/dsh@0.1.2-rc.1 plugin --profile web add relay-dsh-plugin-events@0.2.2
+npx @deepseek-ai/dsh@0.1.2-rc.1 web
 ```
 
 [![DSH 兼容版本](https://img.shields.io/badge/DSH-0.1.1--rc.2%20%7C%200.1.2--alpha.2%20%7C%200.1.2--alpha.3-2f7d68)](https://github.com/deepseek-ai/deepseek-harness)

package/SPEC.md

@@ -1,6 +1,6 @@
 # Relay DSH Events Plugin Specification
 
-Status: Accepted for `0.1.0`
+Status: Accepted; `0.2.1` baseline plus Event Productization contracts
 
 ## Purpose
 
@@ -16,6 +16,9 @@ The plugin owns:
 - Wait, Event, routing-attempt, routing-decision, Delivery, Activation, and Monitor
   persistence in one local SQLite database;
 - the `relayEvents` Cordis service and its versioned Router/Monitor provider slots;
+- Agent-authored versioned Wait continuation and immutable matched-Wait Delivery
+  snapshots;
+- capability-scoped trusted bound-Event source registration;
 - exact event-type fallback routing when no Router provider is registered;
 - delivery to the existing DSH Session, stable Activation identity, and background
   recovery of queued Deliveries;
@@ -29,50 +32,91 @@ The plugin does not own:
 - Monitor observation, detection, scheduling, or generated code;
 - email, CI, or provider-specific Webhook normalization;
 - conversation creation or an execution backend;
-- notification delivery for escalated Events.
+- provider-specific notification transport implementation. Events owns provider
+  registration, bounded escalation calls, durable outcomes, receipt IDs, attempt
+  counts, and explicit safe retry.
 
 ## Public Service Contract
 
 `ctx.relayEvents.apiVersion` is `1`. The public service exposes high-level event
-operations and two replaceable provider registrations:
+operations, two replaceable providers, and capability-scoped bound sources:
 
 - `registerRouter(provider)` accepts exactly one active Router with stable `id` and
   `route({ event, eventRecord, sessions })`;
 - `registerMonitorProvider(provider)` accepts exactly one active Monitor provider
   with `prepare`, `checkMonitor`, and lifecycle-safe disposal;
+- `registerBundleCatalogProvider(provider)` accepts one live, secret-safe Monitor
+  Bundle catalog projection; management snapshots keyset-page it independently from
+  Event history and never infer creation capabilities from persisted instances;
+- `registerBoundEventSource(provider)` accepts non-overlapping declared Event source
+  names and returns an unforgeable capability whose `handleEvent({ event, binding })`
+  path can select one active Wait without semantic routing;
 - Wait/Event operations: `registerWaits`, `cancelWaits`, `listWaits`,
   `handleEvent`, and `dispatchSession`;
 - Monitor persistence operations: `beginMonitorCheck`, `completeMonitorCheck`,
   `failMonitorCheck`, `abandonMonitorCheck`, and `listDueMonitors`. No SQLite
   handle, mutable map, or DSH Agent object crosses the service boundary.
+- `registerNotificationProvider(provider)` accepts at most one capability-scoped
+  escalation notifier. Missing and failed notification attempts remain durable,
+  inspectable outcomes and never fabricate a Session.
+- Monitor lifecycle operations inspect, pause, resume, update cadence, run now, and
+  stop with optimistic versions and durable terminal actor/reason evidence.
+  Rebaseline creates an immutable version or reactivates an identical retained
+  version for rollback, always recording a fresh baseline before switching it active.
 
 Provider registration is owned by the registering Cordis fiber. Duplicate active
 providers fail closed. Unloading a provider restores the exact fallback Router or
 the Monitor-unavailable state without unloading Events.
 
+Wait continuation is normalized to version 1 and persisted inside the immutable Wait
+card. A Delivery stores the exact matched Wait snapshot and routing evidence at commit
+time. Public Event payload fields cannot assert a trusted binding, and a stale or
+cross-Session binding escalates without claiming a Wait.
+
 ## Reliability
 
-- Event ingestion is idempotent by source identity and fingerprint.
+- Event ingestion is idempotent by source identity and fingerprint. Reusing one
+  provider identity with conflicting content fails closed.
+- Capability-scoped sources and bound Monitors may provide a bounded canonical
+  correlation key for cross-source convergence. Generic public Event content cannot
+  set that key.
 - Routing decisions are validated against the current Wait snapshot and committed
   once.
 - Delivery creation and Wait claim are atomic.
+- Exact routing escalates conflicting cross-Session exclusive matches instead of
+  selecting an owner by iteration order. Non-exclusive matches may fan out.
+- Delivery retries reproduce the committed matched Wait snapshots even after the
+  Session registers replacement Waits.
 - Failed admission keeps the same Event, Delivery, and Activation IDs queued.
 - Admission succeeds when the stable inbox message has been flushed to DSH
   persistence, not when the model turn finishes. A retry recognizes the persisted
   Activation message and does not enqueue another follow-up.
 - Reappearing Monitor trigger keys do not create another Delivery or pause a
   rearmed Monitor; its replacement Wait stays active.
+- Router failures are durably counted. Exhausting the configured failure budget
+  commits one inspectable `escalate` decision without exposing provider errors or
+  secrets and without creating a Delivery.
+- A background recovery scan advances both incomplete `received`/`routing` Events
+  and queued Deliveries, including after Host restart.
 - A background recovery scan retries queued Deliveries after failure or Host restart.
 - Events never create DSH Sessions and never switch the selected Web Session.
 - Shutdown stops new operations, waits for in-flight work, disposes routes/listeners,
   and closes SQLite last.
+- The management snapshot includes live and historical registrations plus recent
+  Events; management mutations use authoritative versions and never silently apply
+  to stale rows.
 
 ## Security
 
 - Loopback ingress may omit a token. Non-loopback ingress requires an exact Bearer
   token and fails closed when no token is configured.
 - Event fields remain untrusted content in the injected DSH envelope.
+- Agent-authored continuation is structurally bounded and remains separate from
+  external Event content.
 - Payload size is bounded before JSON parsing.
+- Admission is globally bounded by a sliding rate window and an in-flight
+  concurrency ceiling; overload returns fixed public errors and never exposes
+  internal exception text.
 - Provider-specific signatures are outside this generic ingress boundary.
 
 ## Delivery Acceptance

package/contracts/index.mjs

@@ -21,3 +21,22 @@ export function validateMonitorProvider(provider) {
   }
   return provider;
 }
+
+export function validateBoundEventSourceProvider(provider) {
+  if (!provider || typeof provider !== "object") throw new TypeError("bound Event source provider is required");
+  if (!/^[a-z][a-z0-9._-]{0,63}$/u.test(provider.id ?? "")) {
+    throw new TypeError("bound Event source provider requires a lowercase stable id");
+  }
+  if (!Array.isArray(provider.sources) || provider.sources.length === 0) {
+    throw new TypeError("bound Event source provider requires at least one source");
+  }
+  for (const source of provider.sources) {
+    if (typeof source !== "string" || source.length === 0 || source.length > 128) {
+      throw new TypeError("bound Event source provider has an invalid source");
+    }
+  }
+  if (new Set(provider.sources).size !== provider.sources.length) {
+    throw new TypeError("bound Event source provider sources must be unique");
+  }
+  return provider;
+}

package/docs/acceptance-scenarios.md

@@ -1,6 +1,8 @@
 # Events Delivery Acceptance Scenarios
 
-Official DSH reference: `b150a551b8d465e31e418e1b2eaf5e79bbb7d28e`
+Official DSH references: `b150a551b8d465e31e418e1b2eaf5e79bbb7d28e`,
+`0a53fb55bea101816fa226bb964ae2bed71c343b`, and
+`dd6322d604e00eec1ba5e0c8541159906a21094a`.
 
 | ID | Scenario | Required result | Evidence |
 | --- | --- | --- | --- |
@@ -21,4 +23,24 @@ Official DSH reference: `b150a551b8d465e31e418e1b2eaf5e79bbb7d28e`
 | EVT-015 | Clean unload | New operations fail during shutdown; in-flight work settles; listeners, Remote, service, timers, and SQLite are released. | lifecycle integration |
 | EVT-016 | Backend neutrality | Events-only, Events+Codex, and Events+Claude compositions contain no backend import or backend-name branch in Events. | static + official DSH |
 | EVT-017 | Package boundary | Tarball contains built/public artifacts only and imports in a clean directory. | `npm pack` acceptance |
-
+| EVT-018 | Wait continuation | Complete and legacy Waits normalize versioned continuation; invalid/oversized nested values fail before replacing prior Waits. | unit + SQLite |
+| EVT-019 | Matched Wait envelope | Delivery contains only immutable matched Wait snapshots, continuation and routing evidence from the committed routing snapshot. | SQLite + inbox contract |
+| EVT-020 | Exclusive conflict | Cross-Session exact matches involving exclusive Waits escalate independent of insertion order and claim nothing. | randomized-order integration |
+| EVT-021 | Non-exclusive fan-out | Exact non-exclusive matches create one atomic Delivery per Session with complete matched cards. | SQLite integration |
+| EVT-022 | Trusted bound source | Only a registered source capability can submit a binding; public payload ownership fields have no authority. | service + protocol security |
+| EVT-023 | Stale/cross-Session binding | Invalid owner, Wait, version, or Session/Wait pair escalates with no claim or Delivery. | SQLite integration |
+| EVT-024 | Schema upgrade | Existing schema v4/v5/v9 storage upgrades through schema v10, preserving Delivery snapshots and adding notification receipt/attempt evidence. | real file migration |
+| EVT-025 | Router failure terminal state | Repeated Router failure reaches the configured budget, commits one inspectable escalation, creates no Delivery, and omits raw provider errors/secrets. | unit + SQLite |
+| EVT-026 | Incomplete Event recovery | The background scan resumes `received`/`routing` Events and reaches a single terminal decision without redelivery or duplicate attempts. | fake-clock integration + restart |
+| EVT-027 | Conflicting provider identity | Reuse of one source delivery identity with different content fails closed, preserves the original terminal Event, and creates no second record. | SQLite security integration |
+| EVT-028 | Monitor lifecycle | Inspect, cadence update, pause, resume, run-now guard, and stop use optimistic versions, preserve baseline, and persist terminal actor/reason/time. | SQLite + Host/client contract |
+| EVT-029 | Historical management snapshot | Live and terminal Waits/Monitors plus recent Events and decisions remain inspectable without reactivating or mutating them. | management Remote + browser |
+| EVT-030 | Escalation notification outcome | One configured provider receives bounded escalation content once; absent and failed providers record visible `unavailable`/`failed` outcomes without leaking raw errors. | service + SQLite |
+| EVT-031 | Trusted cross-source convergence | A trusted webhook and Monitor transition sharing one canonical correlation key create one Event/Delivery regardless of source order; public payload correlation fields have no authority. | connector-monitor composition |
+| EVT-032 | Notification safe retry | Duplicate ingestion never retries a terminal notification; an explicit retry is allowed only for unavailable/failed outcomes, increments attempts, and stores a bounded provider receipt. | service + SQLite + browser |
+| EVT-033 | Global admission budgets | Exact rate and concurrency limits reject only excess Event admission with stable 429/503 responses while management remains usable. | HTTP + concurrency integration |
+| EVT-034 | Management pagination and focus | Stable keyset pages, state/source filters, background refresh, dialog focus trap/return, Escape isolation, and draft preservation work in English and Chinese. | official DSH browser |
+| EVT-035 | Live Bundle catalog | Packed Monitor extensions appear in a distinct creation catalog with live status, type/version/origin, Events, capabilities, lifecycle, permissions, and remediation; no credential/handle fields render. | official DSH browser |
+| EVT-036 | Bundle catalog pagination/localization | A 24-type packed catalog has stable non-overlapping keyset pages; locale change reloads localized provider data; wide/narrow and light/dark layouts remain accessible. | service + official DSH browser |
+| EVT-037 | Immutable rollback | A successful target update adds one version; failed baseline changes nothing; rollback reuses retained content, records a new baseline, and preserves Monitor/Wait identity. | SQLite service |
+| EVT-038 | Empty and fault presentation | Events-only UI renders loading/empty/history states, transitions from zero to one background Event, and exposes retryable failures without fabricating success. | official DSH browser + client contract |

package/docs/test-review.md

@@ -66,3 +66,93 @@ delivery harness.
 - A rearmed recurring Monitor now ignores already committed trigger keys without
   pausing again. The regression checks disappearance/reappearance and the still-active
   replacement Wait. Shutdown lease release is tested against real SQLite.
+
+## Review 8 — continuation, snapshots, and trusted binding
+
+- Added EP-01 continuation normalization with legacy defaults, nested shape and size
+  bounds, atomic failure behavior, and authenticated Agent-tool ownership.
+- Persisted the exact matched Wait snapshot and routing evidence on each Delivery so a
+  later Wait replacement cannot change the admitted continuation context.
+- Replaced insertion-order exclusive selection with deterministic escalation and kept
+  non-exclusive multi-Session fan-out.
+- Added capability-scoped bound Event source registration. Public payload fields cannot
+  assert ownership; stale and cross-Session bindings escalate without claims.
+- Exercised a real schema v4 file migration, not an in-memory reconstructed v5 store.
+- The first test command intentionally failed before discovery because `DSH_ROOT` was
+  absent; it was not counted as a pass. Verification then used official DSH
+  `dd6322d604e00eec1ba5e0c8541159906a21094a` and discovered every expected test with
+  zero skip/todo.
+- Mutation review disabled the new exclusive-conflict guard. EP03-006/008 failed in
+  the routing validator before any Delivery, proving the acceptance test exercises the
+  protection rather than a fixture-only assertion. The guard was restored before the
+  final run.
+
+## Review 9 — Router failure terminalization and recovery
+
+- Added a configurable Router failure budget whose final attempt commits an
+  inspectable escalation instead of leaving an Event permanently in `routing`.
+- The committed decision contains stable public wording and attempt metadata but not
+  the Router's raw error text; the regression injects a sentinel secret and proves it
+  is absent.
+- Extended background recovery to resume both incomplete Events and queued
+  Deliveries. The recovery regression begins with a real rejected ingress call,
+  waits for the scheduler's second attempt, then independently reads SQLite-backed
+  Event state and asserts exactly two attempts and no Delivery.
+
+## Review 10 — productization and browser delivery
+
+- Schema v10 persists notification attempt counts and provider receipts. Tests prove
+  duplicate ingress cannot silently retry and only an explicit failed/unavailable
+  action can retry; the official browser verifies the second unavailable attempt is
+  still visible when no provider exists.
+- Exact rate/concurrency boundaries, fixed public overload/internal errors, stable
+  keyset pagination, retention rollback, and Monitor proposal budgets are asserted
+  against production paths. Events verification discovered 52/52 tests with zero
+  skip/todo, then typecheck, build, and dry-run pack passed.
+- Official DSH `dd6322d604e00eec1ba5e0c8541159906a21094a` accepted the packed management
+  suite: English/Chinese, 1280×720 and 1440×900, destructive keyboard dialogs,
+  focus return, hostile text, Router and credential lifecycles, pagination, Monitor
+  cadence validation/update, terminal/check/trigger evidence, light/dark computed
+  WCAG AA contrast, the full user-facing fault matrix, and console/network cleanliness.
+  A separate Events-only run proved real empty state and background transition to the
+  first durable HTTP Event. Packed Codex and Claude compositions proved the same Event
+  stack boots with both backend adapters and opens an existing backend-bound Session.
+- The browser run initially caught Escape propagation, disconnected focus targets,
+  an unlabeled Relay filter, and onboarding-mask timing. Each failure remained red
+  until the production UI or the test's host-state synchronization was corrected;
+  no force-click, skipped case, or weakened Relay assertion was accepted.
+- The extended browser gate also caught tertiary/status colors below AA, a React
+  `currentTarget` lifetime crash, and a rapid cadence submit that left the visible
+  input at 7200 while persisting 3600. The final assertion waits for the independently
+  reloaded Monitor summary, so the old UI-only false positive cannot pass.
+
+## Review 12 — Monitor Bundle catalog and rollback
+
+- Service tests page a changing Bundle catalog with opaque keyset cursors, reject
+  malformed cursors and one-over limits, and prove provider unload produces a real
+  empty catalog rather than cached UI state.
+- SQLite rebaseline tests now update to a second immutable version, force a baseline
+  failure and compare the unchanged active version/count, then reactivate the first
+  version while recording a third baseline observation.
+- The packed official DSH run registers 22 synthetic types from a separate fixture
+  extension plus Time and GitHub. It verifies two non-overlapping catalog pages,
+  available/configuration-required states, provider identity, Event/capability data,
+  permission/remediation text, and no browser console or resource errors.
+- That browser gate first failed on 3.68:1 dark-theme remediation contrast, then on
+  ambiguous controls after two pagers existed, then on English provider content after
+  switching to Chinese. Fixes were accepted only after the complete browser matrix
+  passed again; static tests pin the locale reload and `zh` to `zh-CN` mapping.
+
+## Review 13 — extraction migration and final package gate
+
+- Two real-file migration tests persist the pre-extraction `clock` / `deadline_reached`
+  and `github` / `snapshot_changed` shapes, close Events and Monitors, reopen the same
+  SQLite file with extension-owned compatibility providers, and assert the original
+  IDs, active version, baseline, continuation, Session, and stable Event identity.
+- The root package verifier initially failed before import because it ignored the
+  explicit official-DSH checkout and assumed a missing worktree-local directory. It
+  now honors `DSH_ROOT`; the restored run builds, packs, clean-installs, and imports
+  every selected public entry.
+- Final Events verification discovered 58/58 tests with zero skip/todo, and the root
+  integration process discovered 467/467. The external root acceptance report records
+  the final artifact SHA-256 so this package does not self-reference its own tarball.