Skip to content

Unify the handler option across the three runtimes; parameterise TemporalOptions on its contract #22

Description

@btravers

From the 2026-08-13 repo audit.

The option a developer hands their work to has three names and three shapes across the three runtime packages:

  • start-http: handler: HttpHandler<Needs> — a direct function (request, response, ctx, signal) => PromiseLike<unknown> (packages/start-http/src/http-runtime.ts:28-41)
  • start-temporal: activities: (host) => Record<string, (...args: never[]) => unknown> — a builder whose return type is erased (packages/start-temporal/src/temporal-runtime.ts:47)
  • start-amqp: handlers: (host) => WorkerInferHandlers<TContract, ...> — a builder checked against the contract (packages/start-amqp/src/amqp-runtime.ts:38-40)

Only AmqpOptions is parameterised on its contract; TemporalOptions is not, with no stated reason — and packages/start-amqp/CLAUDE.md describes the two as equivalent guarantees, when temporal's declareActivitiesHandler check is a runtime throw, not a compile error.

Acceptance

  • One documented convention for the handler option (name, builder-vs-direct, contract-checked where a contract exists). The amqp shape is the strongest candidate.
  • TemporalOptions parameterised on its contract so the activities record is compile-checked, or a written reason why it cannot be.
  • The convention recorded in the root CLAUDE.md so the next runtime package inherits it.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions