suaveplan/openspec/changes/api-host-pipeline-events/specs/api-host/spec.md

Capability Spec Delta: api-host — Pipeline per-stage observability

Package: @suaveplan/api-host Status: PROPOSED

ADDED Requirements

Requirement: Host emits a structured event at every §6 pipeline stage boundary

@suaveplan/api-host's RequestPipeline SHALL accept a pipelineEvents: PipelineEventsBus adapter slot on HostAdapters (from @suaveplan/api-types/pipeline-events). For every request processed, the pipeline MUST emit PipelineStageEvent { stage, outcome: "entered", requestId, at } on entry to each of the 11 stages defined in §6 of the foundation design doc, and MUST emit a matching completed / rejected / skipped event on exit.

Scenario: a successful request emits 22 events (entered + completed for each of 11 stages)

• WHEN a request that satisfies every stage's gates is processed
• THEN pipelineEvents.subscribe observes exactly 22 events: entered followed by completed for each of the 11 stages in §6 order

Scenario: a stage rejection halts subsequent stages

• WHEN the auth stage rejects a request (outcome: "rejected")
• THEN no subsequent stage emits entered for that request id

Scenario: conditionally-skipped stages emit skipped, not silent omission

• WHEN an anonymous request bypasses idempotency-by-principal (no principal to key by)
• THEN the idempotency stage emits { stage: "idempotency", outcome: "skipped", requestId } (NOT silent omission)

Verified by: src/request-pipeline/request-pipeline.test.ts::"successful request emits entered+completed for all 11 stages in order" AND src/request-pipeline/request-pipeline.test.ts::"rejected stage halts subsequent stage emission" AND src/request-pipeline/request-pipeline.test.ts::"skipped stage emits skipped outcome explicitly"

---

Requirement: Default pipelineEvents is a zero-cost noop bus

When no pipelineEvents adapter is configured, the host MUST install a NoopPipelineEventsBus whose emit and subscribe methods are zero-cost (no allocation per call, no listener-list iteration). Production deployments that don't need per-stage observability incur no overhead.

Scenario: NoopBus emit allocates no objects

• WHEN a request flows through a host configured with NoopBus
• THEN emit returns immediately AND a microbench (bench:emit-noop) confirms zero allocation per call

Scenario: NoopBus subscribe is a no-op returning an unsubscribe noop

• WHEN a consumer calls noopBus.subscribe(listener)
• THEN the listener is never invoked AND the returned unsubscribe function is callable without effect

Verified by: src/pipeline-events-bus/noop-bus.test.ts::"emit on noop bus is a no-op" AND src/pipeline-events-bus/noop-bus.test.ts::"subscribe on noop bus returns a no-op unsubscribe" AND src/pipeline-events-bus/noop-bus.bench.ts::"emit-noop zero-allocation"

---

Requirement: createTestHost wires an InMemoryPipelineEventsBus by default

@suaveplan/api-host/testing.createTestHost() MUST default pipelineEvents to an InMemoryPipelineEventsBus (the canonical fixture). The bus is exposed on host.adapters.pipelineEvents for direct assertion in smoke tests.

Scenario: createTestHost exposes the bus for direct assertion

• WHEN a test calls await createTestHost({ ... })
• THEN host.adapters.pipelineEvents is an InMemoryPipelineEventsBus instance whose events array can be inspected

Scenario: explicit override is honoured

• WHEN a test calls createTestHost({ adapters: { pipelineEvents: customBus } })
• THEN host.adapters.pipelineEvents === customBus

Verified by: src/testing/create-test-host/create-test-host.test.ts::"defaults pipelineEvents to InMemoryPipelineEventsBus" AND src/testing/create-test-host/create-test-host.test.ts::"explicit pipelineEvents override is honoured"

---

Requirement: Conformance harness runPipelineEventsConformance

The host SHALL ship runPipelineEventsConformance(host) from @suaveplan/api-host/testing/pipeline-events-conformance. The harness MUST assert four invariants:

1. Per-stage emit — every of the 11 stages emits entered AND (completed OR rejected OR skipped).
2. Order — stages emit in §6 order.
3. Skip — conditionally-skipped stages emit skipped (not silent omission).
4. Rejection — when a stage rejects, no subsequent stage emits entered.

Scenario: harness rejects a host whose pipeline omits a stage

• WHEN runPipelineEventsConformance runs against a stub host whose pipeline skips audit emission silently
• THEN the harness reports the "Per-stage emit" invariant failure pointing to the audit stage

Verified by: src/testing/pipeline-events-conformance/pipeline-events-conformance.test.ts::"harness rejects host with missing stage emission"