@pulse-compute/runtime 0.0.0 → 1.0.0-beta.1

package/src/host.d.ts

@@ -0,0 +1,376 @@
+import type {
+  Handler,
+  PulseEffect,
+  PulseFetchResponse,
+  PulseParallelEffect,
+  PulseParallelResult,
+  Router
+} from './index';
+
+/** Provider-owned execution metadata supplied to every JavaScript effect. */
+export interface PulseJavascriptEffectHostExecution {
+  readonly kind: 'request' | 'event';
+  readonly request?: Request;
+  readonly event?: PulseEventFrame;
+  readonly application?: unknown;
+  readonly signal?: AbortSignal;
+  /** Adds execution-owned sensitive text to runtime redaction before provider work continues. */
+  registerRedactionValue(value: string | Uint8Array): void;
+  /** Applies one project-owned schema codec directly to an in-memory semantic value. */
+  validateSchemaValue(
+    schemaId: string,
+    value: unknown,
+    context?: Readonly<{ source?: string; operationId?: string }>
+  ): unknown;
+}
+
+/** Canonical execution-owned effect descriptor delivered to a trusted provider adapter. */
+export interface PulseJavascriptEffectDescriptor {
+  readonly version: 'pulse.javascript-effect.v1';
+  readonly id: string;
+  readonly kind: string;
+  readonly providerKind: string;
+  readonly operation: string;
+  readonly capability: string;
+  readonly [field: string]: unknown;
+}
+
+export interface PulseJavascriptEffectAdapterInput {
+  readonly id?: string;
+  dispatch(
+    effect: PulseJavascriptEffectDescriptor,
+    execution: PulseJavascriptEffectHostExecution
+  ): Promise<unknown> | unknown;
+  dispose?(execution: PulseJavascriptEffectHostExecution): Promise<void> | void;
+}
+
+export interface PulseJavascriptEffectAdapter {
+  readonly version: 'pulse.javascript-effect-adapter.v1';
+  readonly id: string;
+  dispatch(
+    effect: PulseJavascriptEffectDescriptor,
+    execution: PulseJavascriptEffectHostExecution
+  ): Promise<unknown> | unknown;
+  dispose?(execution: PulseJavascriptEffectHostExecution): Promise<void> | void;
+}
+
+export interface PulseEventAdapterSemantics {
+  readonly acceptance: 'host-accepted';
+  readonly deliveryGuarantee: 'none';
+  readonly autoLoopback: false;
+  readonly sameStackReentry: false;
+  readonly queueDiscipline: 'fifo-per-declared-adapter';
+  readonly executionIsolation: 'one-event-frame-per-execution';
+}
+
+export interface PulseEventRecordingAdapterOptions {
+  readonly id?: string;
+  readonly maxQueueDepth?: number;
+}
+
+/** Bounded deterministic event acceptance adapter. It never invokes a local application handler. */
+export interface PulseEventRecordingAdapter extends PulseJavascriptEffectAdapter {
+  readonly eventAdapter: {
+    readonly version: 'pulse.event-adapter.v1';
+    readonly id: string;
+    readonly maxQueueDepth: number;
+    readonly semantics: PulseEventAdapterSemantics;
+  };
+  acceptedFrames(): readonly PulseEventFrame[];
+}
+
+export interface PulseRuntimeHostKvNamespace<T = unknown> {
+  get(key: string): Promise<T | undefined> | T | undefined;
+  put(key: string, value: T): Promise<boolean> | boolean;
+}
+
+/** Compatibility injection shape retained while providers move to one effect adapter. */
+export interface PulseRuntimeHostCapabilities {
+  fetch?(
+    url: string,
+    init?: unknown,
+    execution?: PulseJavascriptEffectHostExecution
+  ): Promise<Response | PulseFetchResponse> | Response | PulseFetchResponse;
+  config?(
+    name: string,
+    execution?: PulseJavascriptEffectHostExecution
+  ): Promise<string | undefined> | string | undefined;
+  secret?(
+    name: string,
+    execution?: PulseJavascriptEffectHostExecution
+  ): Promise<string | undefined> | string | undefined;
+  kv?<T = unknown>(
+    name: string,
+    execution?: PulseJavascriptEffectHostExecution
+  ): PulseRuntimeHostKvNamespace<T> | undefined;
+  emit?(
+    frame: PulseEventFrame,
+    execution?: PulseJavascriptEffectHostExecution
+  ): Promise<void> | void;
+  effect?(
+    effect: PulseJavascriptEffectDescriptor,
+    execution: PulseJavascriptEffectHostExecution
+  ): Promise<unknown> | unknown;
+}
+
+export interface PulseJavascriptEffectObservation {
+  readonly version: 'pulse.javascript-effect-observation.v1';
+  readonly type: 'effect-dispatched' | 'effect-settled' | 'parallel-dispatched' | 'parallel-settled';
+  readonly [field: string]: unknown;
+}
+
+export interface PulseJavascriptEffectGroupSummary {
+  readonly id: string;
+  readonly keys: readonly string[];
+  readonly effectIds: readonly string[];
+}
+
+export interface PulseJavascriptEffectSummary {
+  readonly version: 'pulse.javascript-effect-observation.v1';
+  readonly adapter: {
+    readonly version: 'pulse.javascript-effect-adapter.v1';
+    readonly id: string;
+  };
+  readonly effectCount: number;
+  readonly localEffectCount: number;
+  readonly ownedEffectCount: number;
+  readonly parallelCount: number;
+  readonly resolutionOrder: readonly string[];
+  readonly groups: readonly PulseJavascriptEffectGroupSummary[];
+  readonly observations: readonly PulseJavascriptEffectObservation[];
+  readonly redactedSecretCount: number;
+  readonly aborted: boolean;
+  readonly abortCode?: string;
+  readonly closed: boolean;
+}
+
+/** Maintainer bridge used by the managed Router lifecycle and focused adapter tests. */
+export interface PulseJavascriptEffectExecution {
+  /** Execution-owned local projection. It participates in lifecycle containment but is not parallel-eligible. */
+  local<T = unknown>(
+    kind: string,
+    producer: (execution: PulseJavascriptEffectHostExecution) => T | PromiseLike<T>
+  ): PulseEffect<T>;
+  dispatch<T = unknown>(
+    effect: Omit<PulseJavascriptEffectDescriptor, 'version' | 'id'> & { readonly id?: string },
+    projector?: (value: unknown) => T
+  ): PulseParallelEffect<T>;
+  project<T, U>(
+    effect: PulseParallelEffect<T>,
+    projection: string,
+    projector: (value: T) => U | PromiseLike<U>
+  ): PulseParallelEffect<U>;
+  parallel<T extends Readonly<Record<string, PulseParallelEffect<unknown>>>>(
+    effects: T
+  ): PulseEffect<PulseParallelResult<T>>;
+  /** Applies execution-owned secret redaction to an error before it crosses a managed boundary. */
+  redactError(error: unknown): unknown;
+  /** Applies execution-owned secret and sensitive-field redaction to structured evidence. */
+  redactValue<T = unknown>(value: T): unknown;
+  assertIdle(): Promise<void>;
+  summary(): PulseJavascriptEffectSummary;
+  close(): Promise<void>;
+}
+
+export interface PulseRuntimeExecutionOptions {
+  /** Compatibility bridge. New providers should inject one shared effectAdapter instead. */
+  readonly capabilities?: PulseRuntimeHostCapabilities;
+  readonly effectAdapter?: PulseJavascriptEffectAdapter | PulseJavascriptEffectAdapterInput;
+  readonly application?: unknown;
+  /** Managed execution plane. Direct effect executions default to request. */
+  readonly executionKind?: 'request' | 'event';
+  /** Normalized event input supplied only for event-owned adapter work. */
+  readonly event?: PulseEventFrame;
+  readonly requestHeaders?: readonly (readonly [string, string])[];
+  readonly signal?: AbortSignal;
+  readonly maxEffects?: number;
+  /** Optional stricter limits for direct event ingress normalization. */
+  readonly eventLimits?: PulseEventLimits;
+  /** Maximum bytes materialized by ctx.req.text()/json(). */
+  readonly maxRequestBodyBytes?: number;
+  /** Maximum bytes materialized by fetched response text()/json() projections. */
+  readonly maxFetchBodyBytes?: number;
+  /** Shared fallback for request and fetched structured bodies. */
+  readonly maxStructuredBodyBytes?: number;
+  /** Maximum UTF-8 bytes in config and secret names. */
+  readonly maxBindingNameBytes?: number;
+  /** Maximum UTF-8 bytes returned by config and secret providers. */
+  readonly maxBindingValueBytes?: number;
+  /** Maximum UTF-8 bytes in a KV namespace name. */
+  readonly maxKvNamespaceBytes?: number;
+  /** Maximum UTF-8 bytes in a KV key. */
+  readonly maxKvKeyBytes?: number;
+  /** Maximum serialized bytes in a detached KV value. */
+  readonly maxKvValueBytes?: number;
+  /** Maximum nesting depth in a detached KV value. */
+  readonly maxKvValueDepth?: number;
+  /** Maximum entries in a detached KV value. */
+  readonly maxKvValueEntries?: number;
+  /** Compiler-generated project schema codec table. This is a host integration surface, not an authoring API. */
+  readonly schemaCodecs?: {
+    readonly registry?: unknown;
+    has(schemaId: string): boolean;
+    decode(schemaId: string, value: unknown, source?: string): unknown;
+    decodeJsonText(schemaId: string, text: string, source?: string): unknown;
+    encodeJsonText(schemaId: string, value: unknown, source?: string): string;
+    responseCase?(responseCaseId: string): { readonly id: string; readonly status: number; readonly schemaId: string } | undefined;
+    createTraceEvent?(event: unknown, options?: unknown): unknown;
+  };
+  /** Enforces registered schema IDs at every semantic JSON boundary. */
+  readonly strict?: boolean;
+  /** Provider-known sensitive values available before the first secret read. */
+  readonly redactionValues?: readonly string[];
+  /** Resolved synchronous logging threshold. */
+  readonly reporting?: 'off' | 'error' | 'warn' | 'info' | 'debug' | 0 | 1 | 2 | 3 | 4;
+  /** Provider-owned best-effort logging sink. */
+  readonly log?: (level: 1 | 2 | 3 | 4, message: string, event: Readonly<Record<string, unknown>>) => void;
+  readonly onLogObservation?: (event: Readonly<Record<string, unknown>>) => void;
+  readonly onJsonTrace?: (event: unknown) => void;
+  readonly onEffectObservation?: (observation: PulseJavascriptEffectObservation) => void;
+  readonly onEffectSummary?: (summary: PulseJavascriptEffectSummary) => void;
+}
+
+export declare class PulseRuntimeContractError extends Error {
+  readonly code: string;
+  readonly detail?: unknown;
+}
+
+export declare class PulseUnhandledError extends Error {
+  readonly code: 'PULSE_RUNTIME_UNHANDLED_ERROR';
+}
+
+export declare function createJavascriptEffectAdapter(
+  input: PulseJavascriptEffectAdapterInput
+): PulseJavascriptEffectAdapter;
+export declare function createCapabilityEffectAdapter(
+  capabilities?: PulseRuntimeHostCapabilities
+): PulseJavascriptEffectAdapter;
+export declare function createEventRecordingAdapter(
+  options?: PulseEventRecordingAdapterOptions
+): PulseEventRecordingAdapter;
+export declare function createJavascriptEffectExecution(
+  options?: PulseRuntimeExecutionOptions & { readonly request?: Request }
+): PulseJavascriptEffectExecution;
+export interface PulseBindingValueLimits {
+  readonly maxBindingNameBytes?: number;
+  readonly maxBindingValueBytes?: number;
+  readonly maxKvNamespaceBytes?: number;
+  readonly maxKvKeyBytes?: number;
+  readonly maxKvValueBytes?: number;
+  readonly maxKvValueDepth?: number;
+  readonly maxKvValueEntries?: number;
+}
+export declare function normalizeBindingName(kind: string, value: unknown, options?: PulseBindingValueLimits): string;
+export declare function normalizeBindingValue(
+  capability: string,
+  name: string,
+  value: unknown,
+  options?: PulseBindingValueLimits
+): string | undefined;
+export declare function normalizeKvNamespace(value: unknown, options?: PulseBindingValueLimits): string;
+export declare function normalizeKvKey(value: unknown, options?: PulseBindingValueLimits): string;
+export declare function cloneKvValue<T>(
+  value: T,
+  options?: {
+    readonly operation?: string;
+    readonly allowUndefined?: boolean;
+    readonly maxDepth?: number;
+    readonly maxEntries?: number;
+    readonly maxBytes?: number;
+    readonly maxKvValueBytes?: number;
+    readonly maxKvValueDepth?: number;
+    readonly maxKvValueEntries?: number;
+  }
+): T;
+export declare function normalizeKvPutResult(value: unknown): boolean;
+export interface PulseRedactionState {
+  add(value: unknown): unknown;
+  count(): number;
+  redactString(value: unknown): string;
+  redactValue(value: unknown): unknown;
+  redactError(error: unknown): unknown;
+  values(): readonly '<redacted>'[];
+  summary(): { readonly registeredSecretCount: number };
+}
+export declare function createRedactionState(initialValues?: Iterable<unknown> | string): PulseRedactionState;
+export declare function isPulseJavascriptEffect(value: unknown): boolean;
+
+export declare function isRouterApplication(value: unknown): value is Router;
+export declare function assertRouterApplication(value: unknown): Router;
+export declare function normalizeApplication(value: unknown): Router;
+export declare function executeRouter(
+  application: Router,
+  request: Request,
+  options?: PulseRuntimeExecutionOptions
+): Promise<Response>;
+export declare function executeApplication(
+  application: Router | Handler,
+  request: Request,
+  options?: PulseRuntimeExecutionOptions
+): Promise<Response>;
+export interface PulseEventLimits {
+  readonly maxTypeBytes?: number;
+  readonly maxSchemaIdBytes?: number;
+  readonly maxPayloadBytes?: number;
+  readonly maxPayloadDepth?: number;
+  readonly maxPayloadEntries?: number;
+  readonly maxEvents?: number;
+}
+export type PulseEventFrame<Payload = unknown> =
+  | Readonly<{
+      version: 'pulse.event-frame.v1';
+      type: string;
+      schemaId: string;
+      payload: Payload;
+    }>
+  | Readonly<{
+      version: 'pulse.event-frame.v1';
+      type: string;
+      schemaId: null;
+      payload?: never;
+    }>;
+export type PulseEventExecutionResult =
+  | Readonly<{
+      version: 'pulse.event-execution-result.v1';
+      status: 'completed';
+    }>
+  | Readonly<{
+      version: 'pulse.event-execution-result.v1';
+      status: 'failed';
+      error: unknown;
+    }>;
+/** Direct, transport-free JavaScript execution of one canonical Pulse event frame. */
+export declare function executeEvent(
+  application: Router,
+  frame: PulseEventFrame,
+  options?: PulseRuntimeExecutionOptions
+): Promise<PulseEventExecutionResult>;
+export declare function responseBodyClass(response: Response): 'structured' | 'opaque';
+export declare function responseHeaderPairs(response: Response): readonly (readonly [string, string])[];
+export declare function isPulseFetchResponse(value: unknown): value is PulseFetchResponse;
+/** Marks a provider-owned Web Response as an opaque pass-through without copying its body. */
+export declare function markOpaqueResponse(
+  response: Response,
+  headers?: Headers | Readonly<Record<string, string>> | readonly (readonly [string, string])[]
+): Response;
+export declare function wrapStructuredResponse(response: Response): PulseFetchResponse;
+export declare function createOpaqueFetchResponse(input?: {
+  readonly status?: number;
+  readonly headers?: Headers | Readonly<Record<string, string>> | readonly (readonly [string, string])[];
+  readonly bodyHandle?: unknown;
+  readonly response?: Response;
+}): PulseFetchResponse;
+
+export declare const RUNTIME_HOST_API_VERSION: 'pulse.runtime-host.v3';
+export declare const JAVASCRIPT_EFFECT_PROTOCOL_VERSION: 'pulse.javascript-effect.v1';
+export declare const JAVASCRIPT_EFFECT_ADAPTER_VERSION: 'pulse.javascript-effect-adapter.v1';
+export declare const JAVASCRIPT_EFFECT_OBSERVATION_VERSION: 'pulse.javascript-effect-observation.v1';
+export declare const EVENT_ADAPTER_VERSION: 'pulse.event-adapter.v1';
+export declare const EVENT_ADAPTER_SEMANTICS: PulseEventAdapterSemantics;
+export declare const EVENT_EMIT_CODES: Readonly<{
+  INPUT_INVALID: 'PULSE_RUNTIME_EVENT_EMIT_INPUT_INVALID';
+  SCHEMA_INVALID: 'PULSE_RUNTIME_EVENT_EMIT_SCHEMA_INVALID';
+  ACCEPTANCE_INVALID: 'PULSE_RUNTIME_EVENT_EMIT_ACCEPTANCE_INVALID';
+  QUEUE_FULL: 'PULSE_RUNTIME_EVENT_EMIT_QUEUE_FULL';
+  ADAPTER_INVALID: 'PULSE_RUNTIME_EVENT_ADAPTER_INVALID';
+}>;

package/src/host.js

@@ -0,0 +1,114 @@
+'use strict';
+
+const {
+  PulseRuntimeContractError,
+  PulseUnhandledError,
+  createOpaqueFetchResponse,
+  isPulseFetchResponse,
+  markOpaqueResponse,
+  responseBodyClass,
+  executeRouter,
+  routerEntries,
+  wrapStructuredResponse
+} = require('./internal/index.js');
+const {
+  JAVASCRIPT_EFFECT_PROTOCOL_VERSION,
+  JAVASCRIPT_EFFECT_ADAPTER_VERSION,
+  JAVASCRIPT_EFFECT_OBSERVATION_VERSION,
+  createJavascriptEffectAdapter,
+  createCapabilityEffectAdapter,
+  createJavascriptEffectExecution,
+  isPulseJavascriptEffect
+} = require('./internal/effect-adapter.js');
+const {
+  cloneKvValue,
+  normalizeBindingName,
+  normalizeBindingValue,
+  normalizeKvKey,
+  normalizeKvNamespace,
+  normalizeKvPutResult
+} = require('./internal/bindings.js');
+const { createRedactionState } = require('./internal/redaction.js');
+const { executeEvent } = require('./internal/event-execution.js');
+const {
+  EVENT_ADAPTER_VERSION,
+  EVENT_ADAPTER_SEMANTICS,
+  EVENT_EMIT_CODES,
+  createEventRecordingAdapter
+} = require('./internal/event-emission.js');
+const { responseHeaderPairs } = require('./internal/response.js');
+const { Router } = require('./index.js');
+
+const RUNTIME_HOST_API_VERSION = 'pulse.runtime-host.v3';
+
+function isRouterApplication(value) {
+  try {
+    routerEntries(value);
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+function normalizeApplication(value) {
+  if (isRouterApplication(value)) return value;
+  if (typeof value === 'function') {
+    const router = new Router();
+    router.use(async (ctx) => value(ctx));
+    return router;
+  }
+  throw new PulseRuntimeContractError(
+    'PULSE_RUNTIME_APPLICATION_EXPORT_INVALID',
+    'Pulse JavaScript application modules must default-export a Router, Pulse application, or managed handler.'
+  );
+}
+
+function assertRouterApplication(value) {
+  if (!isRouterApplication(value)) {
+    throw new PulseRuntimeContractError(
+      'PULSE_RUNTIME_APPLICATION_EXPORT_INVALID',
+      'Expected a Router or Pulse application.'
+    );
+  }
+  return value;
+}
+
+async function executeApplication(application, request, options = {}) {
+  return executeRouter(normalizeApplication(application), request, options);
+}
+
+module.exports = Object.freeze({
+  RUNTIME_HOST_API_VERSION,
+  JAVASCRIPT_EFFECT_PROTOCOL_VERSION,
+  JAVASCRIPT_EFFECT_ADAPTER_VERSION,
+  JAVASCRIPT_EFFECT_OBSERVATION_VERSION,
+  EVENT_ADAPTER_VERSION,
+  EVENT_ADAPTER_SEMANTICS,
+  EVENT_EMIT_CODES,
+  PulseRuntimeContractError,
+  PulseUnhandledError,
+  assertRouterApplication,
+  cloneKvValue,
+  createCapabilityEffectAdapter,
+  createEventRecordingAdapter,
+  createJavascriptEffectAdapter,
+  createJavascriptEffectExecution,
+  createRedactionState,
+  createOpaqueFetchResponse,
+  executeApplication,
+  executeEvent,
+  executeRouter,
+  isPulseFetchResponse,
+  isPulseJavascriptEffect,
+  isRouterApplication,
+  markOpaqueResponse,
+  normalizeBindingName,
+  normalizeBindingValue,
+  normalizeKvKey,
+  normalizeKvNamespace,
+  normalizeKvPutResult,
+  normalizeApplication,
+  responseBodyClass,
+  responseHeaderPairs,
+  wrapStructuredResponse
+});

package/src/index.d.ts

@@ -0,0 +1,189 @@
+export type HeaderPair = readonly [name: string, value: string];
+
+declare const pulseEffectBrand: unique symbol;
+declare const pulseParallelEffectBrand: unique symbol;
+
+export interface PulseEffect<T> extends Promise<T> {
+  readonly [pulseEffectBrand]: T;
+}
+
+/** An externally dispatched Pulse effect that may be a member of ctx.parallel(). */
+export interface PulseParallelEffect<T> extends PulseEffect<T> {
+  readonly [pulseParallelEffectBrand]: true;
+}
+
+export type PulseEffectResult<T> = T extends PulseEffect<infer Result> ? Result : never;
+export type PulseParallelResult<T extends Readonly<Record<string, PulseParallelEffect<unknown>>>> = {
+  readonly [Key in keyof T]: PulseEffectResult<T[Key]>;
+};
+
+export interface PulseRequest {
+  readonly method: string;
+  readonly url: string;
+  readonly path: string;
+  readonly headers: readonly HeaderPair[];
+  header(name: string): string | undefined;
+  text(): PulseEffect<string>;
+  json<T = unknown>(schemaId?: string): PulseEffect<T>;
+}
+
+export interface PulseFetchInitBase {
+  readonly method?: 'GET' | 'HEAD' | 'POST';
+  readonly headers?: Readonly<Record<string, string>> | readonly HeaderPair[];
+  readonly timeoutMs?: number;
+}
+
+export type PulseFetchInit = PulseFetchInitBase & (
+  | { readonly body?: never; readonly json?: never; readonly schema?: never }
+  | { readonly body: string; readonly json?: never; readonly schema?: never }
+  | { readonly body?: never; readonly json: unknown; readonly schema?: string }
+);
+
+export interface PulseStructuredResponse {
+  readonly status: number;
+  readonly ok: boolean;
+  readonly kind: string;
+  readonly bodyClass: 'structured';
+  readonly headers: readonly HeaderPair[];
+  header(name: string): string | undefined;
+  text(): PulseEffect<string>;
+  json<T = unknown>(schemaId?: string): PulseEffect<T>;
+}
+
+export interface PulseOpaqueResponse {
+  readonly status: number;
+  readonly ok: boolean;
+  readonly kind: 'stream';
+  readonly bodyClass: 'opaque';
+  readonly headers: readonly HeaderPair[];
+  header(name: string): string | undefined;
+  /** Opaque host-owned handle. It is returnable but not inspectable or iterable. */
+  readonly bodyHandle: unknown;
+  /** Opaque pass-through bodies cannot be inspected. */
+  text(): never;
+  /** Opaque pass-through bodies cannot be inspected. */
+  json<T = unknown>(schemaId?: string): never;
+}
+
+export type PulseFetchResponse = PulseStructuredResponse | PulseOpaqueResponse;
+
+export interface PulseFetchOperation extends PulseParallelEffect<PulseOpaqueResponse> {
+  text(): PulseParallelEffect<string>;
+  json<T = unknown>(schemaId?: string): PulseParallelEffect<T>;
+}
+
+export interface PulseResult {
+  readonly status: number;
+  readonly kind: string;
+  readonly bodyClass: 'structured' | 'opaque';
+  readonly headers: readonly HeaderPair[];
+}
+
+export interface PulseResponseOptions {
+  readonly status?: number;
+  readonly headers?: Readonly<Record<string, string>> | readonly HeaderPair[];
+}
+
+export interface PulseJsonResponseOptions extends PulseResponseOptions {
+  /** Exact schema ID declared by the project. */
+  readonly schema?: string;
+}
+
+export interface PulseState {
+  get(key: string): string | undefined;
+  set(key: string, value: string): void;
+}
+
+export interface PulseLogger {
+  error(message: string): void;
+  warn(message: string): void;
+  info(message: string): void;
+  debug(message: string): void;
+}
+
+export interface PulseKvNamespace<T = unknown> {
+  get(key: string): PulseParallelEffect<T | undefined>;
+  put(key: string, value: T): PulseParallelEffect<boolean>;
+}
+
+export type PulseEmitEvent<Payload = unknown> =
+  | Readonly<{ schema: string; payload: Payload }>
+  | Readonly<{ schema: null; payload?: never }>;
+
+/** Plane-neutral authority shared by one isolated HTTP request or event invocation. */
+export interface PulseExecutionContext {
+  readonly state: PulseState;
+  readonly log: PulseLogger;
+  fetch(url: string, init?: PulseFetchInit): PulseFetchOperation;
+  /** Dispatches a statically keyed group of independent Pulse effects and rejoins in property order. */
+  parallel<const T extends Readonly<Record<string, PulseParallelEffect<unknown>>>>(effects: T): PulseEffect<PulseParallelResult<T>>;
+  readonly config: { get(name: string): PulseParallelEffect<string | undefined> };
+  readonly secret: { get(name: string): PulseParallelEffect<string | undefined> };
+  kv<T = unknown>(name: string): PulseKvNamespace<T>;
+  emit<Payload = unknown>(
+    type: string,
+    event: Readonly<{ schema: string; payload: Payload }>
+  ): PulseParallelEffect<void>;
+  emit(
+    type: string,
+    event: Readonly<{ schema: null; payload?: never }>
+  ): PulseParallelEffect<void>;
+}
+
+/** HTTP request execution context. */
+export interface PulseContext extends PulseExecutionContext {
+  readonly req: PulseRequest;
+  json(value: unknown, descriptor?: PulseJsonResponseOptions | string): PulseResult;
+  text(value: string, options?: PulseResponseOptions): PulseResult;
+  response(input?: PulseResponseOptions & { readonly body?: string }): PulseResult;
+}
+
+export interface PulseRouteContext extends PulseContext {
+  /** Returns the named static route parameter for the matched Router path. */
+  param(name: string): string | undefined;
+}
+
+export interface PulseEvent<Payload = unknown> {
+  readonly type: string;
+  readonly payload: Payload;
+}
+
+/** Non-HTTP event execution context. Event handlers cannot access request or response fields. */
+export interface PulseEventContext<Payload = unknown> extends PulseExecutionContext {
+  readonly event: PulseEvent<Payload>;
+}
+
+export type PulseEventHandler<Payload = unknown> = (ctx: PulseEventContext<Payload>) => Promise<void>;
+
+export type HandlerResult = PulseResult | PulseFetchResponse;
+export type Handler = (ctx: PulseContext) => Promise<HandlerResult>;
+/** Terminal Router control transfer. The current handler never resumes after this value is returned. */
+export type RouterNext = (error?: unknown) => never;
+export type RouteHandler = (ctx: PulseRouteContext, next: RouterNext) => Promise<HandlerResult>;
+export type RouterMiddleware = (ctx: PulseContext, next: RouterNext) => Promise<HandlerResult>;
+export type RouterErrorHandler = (error: unknown, ctx: PulseContext, next: RouterNext) => Promise<HandlerResult>;
+
+/** Canonical Pulse-prefixed aliases. They do not create a second handler or Router algebra. */
+export type PulseHandlerResult = HandlerResult;
+export type PulseHandler = Handler;
+export type PulseRouteHandler = RouteHandler;
+export type PulseMiddleware = RouterMiddleware;
+export type PulseErrorHandler = RouterErrorHandler;
+
+/**
+ * Static authoring marker compiled by Pulse. Router instances are not runtime dispatchers.
+ * Canonical v2 supports terminal middleware/error transfer, get/head/post routes,
+ * fallthrough, and acyclic static mounts.
+ */
+export declare class Router {
+  use(handler: RouterMiddleware): this;
+  use(path: string, handler: RouterMiddleware): this;
+  get(path: string, handler: RouteHandler): this;
+  head(path: string, handler: RouteHandler): this;
+  post(path: string, handler: RouteHandler): this;
+  mount(path: string, router: Router): this;
+  error(handler: RouterErrorHandler): this;
+}
+
+export declare const RUNTIME_API_VERSION: 'pulse.runtime-authoring.v4';
+export declare const ROUTER_API_VERSION: 'pulse.router-authoring.v2';

package/src/index.js

@@ -0,0 +1,11 @@
+'use strict';
+
+const { Router: LiveRouter } = require('./internal/router.js');
+
+const RUNTIME_API_VERSION = 'pulse.runtime-authoring.v4';
+const ROUTER_API_VERSION = 'pulse.router-authoring.v2';
+
+/** Public authoring value backed by the package-internal live Router realization. */
+class Router extends LiveRouter {}
+
+module.exports = Object.freeze({ RUNTIME_API_VERSION, ROUTER_API_VERSION, Router });