fix: Reject observers without a callback

Ruby raises ArgumentError when observe or on has no block. JavaScript
accepted a missing onEvent, then logged a TypeError for each event.
Reject the call with TypeError before authorization, as Ruby does.

Port the Ruby tests for the 1,000-observer limit and for observer
removal on close. Each test failed when its guard was removed.

Document both observer errors, the setup sample for each runtime, and
the new activation event order. Remove the delivered observability
section from the roadmap.

Author: cardmagic

CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+- `solid_objects.activation.started` now fires before the actor's `activate()`
+  hook. Before, it fired after a successful hook. The new
+  `solid_objects.activation.completed` event takes that meaning, and
+  `solid_objects.activation.failed` reports a failed hook. Ruby changes the same
+  events. Move a subscriber that reads `activation.started` as a finished
+  activation to `activation.completed`.
+- Reference `observe()` and `on()` reject a missing `onEvent` callback with
+  `TypeError` before authorization, as Ruby raises `ArgumentError` without a
+  block. Tests pin the 1,000-observer limit and observer removal on `close()`.
+  The roadmap no longer lists portable observability as future work.
+
 - Add the shared telemetry contract `compatibility/telemetry-events.json`. Tests
   compare the attribute allowlist and the attribute keys of each core SQL event
   with Ruby. Activation events carry `ownerId`, commit action events carry

docs/api.md

@@ -1073,6 +1073,9 @@ Mounting, authorization actions, CSRF behavior, pages, and extensions are in
 values. `EventObserver` is a provider-free event callback. An actor reference offers
 `observe({ onEvent, authorizationContext })`, `on(name, { onEvent, authorizationContext })`,
 and `diagnostics(options)`. Both observer methods resolve to an unsubscribe function.
+They reject a missing `onEvent` with `TypeError` before authorization. A runtime
+accepts at most 1,000 local observers; the next one rejects with `RangeError`.
+`close()` removes every local observer.
 `DiagnosticOptions` accepts `authorizationContext` and a `limit` from 1 to 100.
 `ActorDiagnostics` holds five bounded `DiagnosticSummary` values, with `sampled`,
 `truncated`, and `oldestAgeMilliseconds`. See [observability](observability.md).

docs/observability.md

@@ -6,6 +6,20 @@ and the Durable Objects host. Existing JavaScript `name`, `occurredAt`, and
 `attributes` fields remain available. Ruby's Active Support notifications remain
 available with their existing snake_case payloads.
 
+```ts
+import { configure } from "solid-objects"
+
+const runtime = configure({
+  ...applicationConfiguration,
+  instrumentation: (event) => {
+    console.info(JSON.stringify(event))
+  },
+})
+```
+
+JavaScript passes `instrumentation` to `configure()`. Ruby sets
+`configuration.instrumentation` inside `SolidObjects.configure`.
+
 ## Schema version 1
 
 Every event has `schemaVersion`, `name` (prefixed with `solid_objects.`),
@@ -121,10 +135,16 @@ calling the returned proc. `on` filters one event name, such as `message.retry`.
 Observers receive only this actor's events in the current runtime/process; they
 are not subscriptions to workers on other hosts. Dispose them when the caller's
 session ends or authorization is revoked. Each runtime or process accepts at most
-1,000 local observers. An observer needs a callback or a block.
-For remote Durable Objects, configure `instrumentation` on the actor host and
-filter by actor identity there; process-local reference observers raise
-`UnsupportedCapability`. Remote `reference.diagnostics` is supported.
+1,000 local observers. More observers raise `RangeError` in JavaScript and
+`ArgumentError` in Ruby. An observer needs a callback or a block. JavaScript
+rejects a missing `onEvent` with `TypeError`, and Ruby raises `ArgumentError`
+without a block. Both checks run before authorization.
+
+The JavaScript Durable Objects host does not support process-local reference
+observers. On that host, `observe` and `on` raise `UnsupportedCapability`, and
+remote `reference.diagnostics` works. To observe a remote actor, configure
+`instrumentation` on the actor host and filter the events by actor identity.
+Ruby has no Durable Objects host.
 
 Both APIs default to denied. Set `authorizeAdministration` / `authorize_administration`
 to allow action `observe` or `inspect`, resource `actor_diagnostics`, and resource ID

docs/parity.md

@@ -89,7 +89,7 @@ Ruby publishes RBS contracts with native Ruby field names; this does not change
 | CLI                                                                           | Native | The packaged executable loads an application runtime and exposes start, diagnostics, processes, dead letters, reminders, and explicit retention pruning as JSON.                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | Operator dashboard                                                            | Native | Fetch and Node/Connect mounting, authorized views and actions, CSRF, filtering, paging, charts, and extensions match the Rack dashboard. Both dashboards expose individual retries and pause/resume; bulk redrive is available through the administration APIs. Pause does not interrupt an in-flight turn.                                                                                                                                                                                                                                                                                                                    |
 | Bulk redrive and administration audit                                         | Native | Message, effect, and broadcast scopes support idempotent retry and durable, bounded, cancellable redrive. Retry and task transitions persist administration identity in audit rows.                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| Structured instrumentation                                                    | Native | Versioned portable events, metric samples, isolated observers, and bounded authorized actor diagnostics match Ruby. Both suites check SQL event attributes against `compatibility/telemetry-events.json`; only JS activation events add the message fields of their turn. Both runtimes log exporter and observer failures and accept at most 1,000 local observers. Timeout events share wait reasons, activation owner IDs, and string generations; see [observability](observability.md). Durable Objects uses host instrumentation and remote diagnostics, sends fewer event attributes, and does not send `sync.timeout`. |
+| Structured instrumentation                                                    | Native | Versioned events, metric samples, isolated observers, and bounded authorized diagnostics match Ruby. Both test suites check SQL event attributes against `compatibility/telemetry-events.json`; only JS activation events add their turn's message fields. Both runtimes log exporter and observer failures, require observer callbacks, and cap local observers at 1,000. Timeout events share wait reasons, activation owner IDs, and string generations; see [observability](observability.md). Durable Objects uses host instrumentation and remote diagnostics, sends fewer attributes, and does not send `sync.timeout`. |
 | Large committed state warning                                                 | Native | `warnStateBytes` reports one `solid_objects.state.large` event, holding the actor type, actor ID, byte count, and threshold, when a committed image passes a 128 KB soft threshold. The event holds no application state, and it reports after the commit. The Ruby gem carries the same event and the same 5 MB hard default from `0.14.3`, as `warn_state_bytes`. Its threshold defaults to 64 KB rather than 128 KB, because its measured curve falls sooner: it keeps 55% of its empty-state throughput at 13 KB, where this package keeps 98% at 16 KB.                                                                   |
 | Public test helper                                                            | Native | `runtime.testing` provides role-selective deterministic draining, explicit-time due-reminder execution, and dependency-ordered reset without relying on cascades.                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 

roadmap.md

@@ -44,11 +44,3 @@ letters, reminders, outboxes, incarnation, and revision. Fleet-wide operations
 remain optional where a backend cannot provide them.
 
 [Issue #41: portable actor administration](https://github.com/cardmagic/solid-objects-js/issues/41)
-
-## Portable observability and diagnostics
-
-Define common structured events, metrics, and diagnostic views for activation
-duration, mailbox depth, retries, dead letters, reminder lateness, outbox age,
-recovery failures, and realtime subscriptions without leaking provider APIs.
-
-[Issue #42: portable observability and diagnostics](https://github.com/cardmagic/solid-objects-js/issues/42)

src/reference.ts

@@ -242,20 +242,22 @@ export class ActorReferenceCore<ActorType extends Actor> {
     return this.runtime.diagnostics(this, options)
   }
 
-  observe(options: {
+  async observe(options: {
     onEvent: EventObserver
     authorizationContext?: SnapshotOptions["authorizationContext"]
   }): Promise<() => void> {
+    assertObserver(options.onEvent)
     return this.runtime.observe(this, options)
   }
 
-  on(
+  async on(
     name: string,
     options: {
       onEvent: EventObserver
       authorizationContext?: SnapshotOptions["authorizationContext"]
     },
   ): Promise<() => void> {
+    assertObserver(options.onEvent)
     return this.observe({
       ...options,
       onEvent: (event) => {
@@ -391,6 +393,12 @@ function createMessageSender<ActorType extends Actor>(
   }) as ActorMessageSender<ActorType>
 }
 
+function assertObserver(onEvent: unknown): void {
+  if (typeof onEvent !== "function") {
+    throw new TypeError("an actor observer requires an onEvent callback")
+  }
+}
+
 function assertOperation(operations: ReadonlySet<string>, operation: string): void {
   if (!operations.has(operation)) {
     throw new UnknownOperation(`unknown operation ${JSON.stringify(operation)}`)

test/instrumentation.test.ts

@@ -338,6 +338,52 @@ describe("structured instrumentation", () => {
     expect(JSON.stringify(events)).not.toContain("reminder-private")
   })
 
+  it("rejects observers without an onEvent callback", async () => {
+    runtime = configuredRuntime()
+    await runtime.install()
+    const reference = InstrumentedActor.ref("callbackless")
+
+    await expect(reference.observe({} as never)).rejects.toThrow(TypeError)
+    await expect(reference.on("message.completed", {} as never)).rejects.toThrow(TypeError)
+  })
+
+  it("accepts at most 1000 local observers", async () => {
+    runtime = configuredRuntime()
+    await runtime.install()
+    const reference = InstrumentedActor.ref("observer-limit")
+    const stops = await Promise.all(
+      Array.from({ length: 1000 }, () => reference.observe({ onEvent: () => {} })),
+    )
+
+    const error = await reference.observe({ onEvent: () => {} }).catch((caught: unknown) => caught)
+
+    expect(error).toBeInstanceOf(RangeError)
+    expect(error).toHaveProperty("message", "at most 1000 local observers may be registered")
+    stops.pop()?.()
+    stops.push(await reference.observe({ onEvent: () => {} }))
+    for (const stop of stops) stop()
+  })
+
+  it("removes local observers when the runtime closes", async () => {
+    runtime = configuredRuntime()
+    await runtime.install()
+    const closed = runtime
+    const identity = { actorType: InstrumentedActor.actorType, actorId: "closed-observer" }
+    const events: InstrumentationEvent[] = []
+    await InstrumentedActor.ref(identity.actorId).observe({
+      onEvent: (event) => {
+        events.push(event)
+      },
+    })
+    closed.emitInstrumentation("custom", identity)
+
+    await closed.close()
+    runtime = undefined
+    closed.emitInstrumentation("custom", identity)
+
+    expect(events).toHaveLength(1)
+  })
+
   it("isolates asynchronous sinks and rejects unknown metadata", async () => {
     const events: InstrumentationEvent[] = []
     runtime = configuredRuntime({