@pulse-compute/pulse 0.0.0 → 1.0.0-beta.2

package/README.md

@@ -1,3 +1,193 @@
 # @pulse-compute/pulse
 
-This is an inert namespace-bootstrap package. It contains no executable code.
+<!-- pulse-package-status:start -->
+> **Support tier:** Canonical application surface<br>
+> **Audience:** Pulse application authors using the conventional project root, configuration factory, and schema declarations.<br>
+> **Install directly:** Yes. Install it in every conventional Pulse project.<br>
+> **Supported entry points:** `@pulse-compute/pulse`, `@pulse-compute/pulse/schema`<br>
+> **Stability:** Supported conventional application, project-configuration, and schema-authoring contract.<br>
+> **npm:** [`@pulse-compute/pulse`](https://www.npmjs.com/package/@pulse-compute/pulse)<br>
+> **Canonical documentation:** [Package guide](https://pulsecompute.io/v1.0.0-beta.2/packages/pulse/)
+>
+> This release-status block is generated from the synchronized `Pulse 1.0.0-beta.2` package policy.
+<!-- pulse-package-status:end -->
+
+This package owns the project-aware authoring layer above the low-level
+`@pulse-compute/runtime` contract. It currently exports:
+
+- `defineConfig((scope) => ({ ... }))`;
+- symbolic `scope.config()` and `scope.secret()` references;
+- the conventional `Pulse` application root;
+- the project-level TypeScript contract used by `.pulse/config.ts`.
+
+`Pulse` extends the TypeScript `Router` surface for authoring convenience, but it
+does not create a second routing system. Compiler analysis normalizes a direct
+`new Pulse(...)` root to the existing Router IR and attaches project/profile
+metadata beside that IR. Router registration order, matching, terminal `next()`,
+error lanes, 404/500 ownership, effects, continuations, and provider realization
+remain unchanged.
+
+
+## Generated project contract
+
+`pulse init` generates the conventional application package directly:
+
+```text
+.pulse/config.ts
+.pulse/.gitignore
+src/index.ts
+tests/pulse.harness.ts
+```
+
+The generated application uses `new Pulse({ auto: true })`, async managed
+handlers, the default `local` native profile, and strict schema policy. The
+generated project depends on this package explicitly; it does not rely on an
+undocumented transitive application root.
+
+## Application root
+
+```ts
+import { Pulse } from '@pulse-compute/pulse'
+
+const app = new Pulse({ auto: true })
+
+app.get('/health', async (ctx) => {
+  return ctx.json({ ok: true })
+})
+
+export default app
+```
+
+The compiler accepts only direct, statically legible construction forms:
+
+```ts
+new Pulse({ auto: true })
+new Pulse(configFactory)
+```
+
+Aliases, subclasses, factories returning `Pulse`, mounted `Pulse` instances, and
+re-exported application roots remain outside the single-entry grammar.
+Mounted and child applications continue to use `Router`.
+
+`auto: true` does not perform filesystem or environment discovery inside deployed
+application code. Project tooling supplies the normalized workspace/profile plan.
+The explicit config-factory constructor is the deterministic semantic reference.
+
+
+## Profile composition token
+
+`app.profile()` returns an opaque token intended only for direct passage to a
+composition helper. Package metadata gives each profile fragment one unique
+owner and an explicit helper/re-export ownership vocabulary. Assets and GRIP do
+not yet claim a realized helper, so passing the token to those packages remains
+unsupported until their composition contracts are implemented. The token cannot
+be inspected, stored, destructured, branched on, or returned.
+
+## Async-shaped handlers
+
+Conventional `.pulse` projects require managed handlers to be async-shaped. A
+synchronous handler is rejected with `PULSE_HANDLER_ASYNC_REQUIRED`. The only
+remaining synchronous-compatibility mode is an explicit migration surface for
+legacy root-config projects and sealed internal compiler evidence.
+
+Managed handlers are async-shaped for TypeScript and future explicit JavaScript
+execution:
+
+```ts
+app.get('/users/:id', async (ctx) => {
+  const user = await ctx
+    .fetch(`/origin/users/${ctx.param('id')}`)
+    .json<User>('app.User')
+
+  return ctx.json({ user })
+})
+```
+
+For native targets, `async` and trusted `await` are authoring notation only:
+
+- the async wrapper is erased;
+- awaited Pulse effects lower to the existing effect and continuation state machine;
+- awaiting a synchronous `ctx` surface is erased with a warning;
+- `await next()` remains invalid because `next()` is terminal Router transfer;
+- arbitrary library awaits remain native-ineligible;
+- no Promise runtime, Asyncify, or automatic target fallback is added.
+
+## Request state
+
+`ctx.state` is a small request-scoped string map:
+
+```ts
+app.use(async (ctx, next) => {
+  ctx.state.set('request-id', 'r1')
+  return next()
+})
+
+app.get('/health', async (ctx) => {
+  return ctx.json({ requestId: ctx.state.get('request-id') })
+})
+```
+
+State is shared across the forward Router cursor, mounted Routers, error recovery,
+and native effect suspension/resumption. It is reset for the next request. The
+contract does not expose object-valued state, enumeration, deletion, or persistence.
+
+## Configuration
+
+Canonical configuration is one synchronous deferred factory:
+
+```ts
+import { defineConfig } from '@pulse-compute/pulse'
+
+export default defineConfig((scope) => ({
+  pulse: {
+    entry: 'src/index.ts',
+    tests: 'tests/pulse.harness.ts',
+    defaultProfile: 'dev',
+    strict: true,
+  },
+  dev: {
+    host: 'node',
+    target: 'native',
+    apiBase: scope.config('API_BASE'),
+    token: scope.secret('API_TOKEN'),
+  },
+}))
+```
+
+The scope is symbolic only. It never exposes resolved values, selected-profile
+state, commands, or ambient environment access.
+
+With `pulse.strict: true` (the default), schema-less request JSON is rejected.
+With `pulse.strict: false`, `await ctx.req.json<T>()` selects the byte-bounded
+`host-generic-json` Pulse capability and records its ownership, inclusion reason,
+limit, and dynamic-host cost class in compiler/build metadata. The parser is not
+embedded in the guest Wasm. Declared schema calls remain specialized and validated
+in either mode.
+
+## Current boundaries
+
+`@pulse-compute/pulse` is the public conventional application surface. It does not expose
+mixed targets or a public compiler/plugin API, and it does not own Handler IR,
+effects, continuations, native lowering, or provider lifecycle.
+
+## Shared runtime type contract
+
+The current project and execution contracts exclude ambient environment resolution,
+nested profiles, readable active-profile state, runtime-option merging, and
+`listen()` delegation from the wrapper.
+
+`@pulse-compute/pulse` now re-exports the **types** owned by
+`@pulse-compute/runtime` for authoring convenience. It does not export a second
+Router value, define another handler/context/effect algebra, or own provider
+lifecycle. The live wrapper uses the same package-internal Router implementation
+while preserving the symbolic configuration factory and opaque profile token. No
+public `handle()`, lifecycle method, or profile introspection is added.
+
+
+## Live wrapper boundary
+
+`Pulse` is now backed by the same live Router implementation as `Router`. Its
+application mode and stable opaque profile token are retained in package-private
+state for later tooling and package composition. The wrapper still performs no
+workspace discovery, profile selection, configuration evaluation, or provider
+lifecycle inside application code.

package/package.json

@@ -1,15 +1,46 @@
 {
   "name": "@pulse-compute/pulse",
-  "version": "0.0.0",
-  "description": "Inert namespace bootstrap for Pulse.",
+  "version": "1.0.0-beta.2",
   "license": "Apache-2.0",
+  "engines": {
+    "node": "^22.14.0 || ^24.0.0"
+  },
+  "description": "Project configuration, schema declarations, and the conventional Pulse application root.",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "require": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./schema": {
+      "types": "./src/schema.d.ts",
+      "require": "./src/schema.js",
+      "default": "./src/schema.js"
+    }
+  },
   "files": [
+    "src",
     "README.md",
     "LICENSE",
     "NOTICE"
   ],
+  "dependencies": {
+    "@pulse-compute/runtime": "1.0.0-beta.2",
+    "@pulse-compute/wasm-contracts": "1.0.0-beta.2"
+  },
   "publishConfig": {
-    "access": "public",
-    "tag": "bootstrap"
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pulse-compute/pulse.git",
+    "directory": "packages/pulse"
+  },
+  "homepage": "https://pulsecompute.io/v1.0.0-beta.2/packages/pulse/",
+  "bugs": {
+    "url": "https://github.com/pulse-compute/pulse/issues"
   }
-}
+}

package/src/index.d.ts

@@ -0,0 +1,164 @@
+import { Router } from '@pulse-compute/runtime';
+
+export type {
+  HeaderPair,
+  PulseEffect,
+  PulseParallelEffect,
+  PulseEffectResult,
+  PulseParallelResult,
+  PulseRequest,
+  PulseFetchInit,
+  PulseStructuredResponse,
+  PulseOpaqueResponse,
+  PulseFetchResponse,
+  PulseFetchOperation,
+  PulseResult,
+  PulseResponseOptions,
+  PulseJsonResponseOptions,
+  PulseState,
+  PulseLogger,
+  PulseKvNamespace,
+  PulseKvGeneration,
+  PulseKvVersionedResult,
+  PulseKvReadFailureReason,
+  PulseKvConditionalResult,
+  PulseKvNotStoredReason,
+  PulseEmitEvent,
+  PulseExecutionContext,
+  PulseContext,
+  PulseRouteContext,
+  PulseEvent,
+  PulseEventContext,
+  PulseEventHandler,
+  HandlerResult,
+  Handler,
+  RouterNext,
+  RouteHandler,
+  RouterMiddleware,
+  RouterErrorHandler,
+  PulseHandlerResult,
+  PulseHandler,
+  PulseRouteHandler,
+  PulseMiddleware,
+  PulseErrorHandler
+} from '@pulse-compute/runtime';
+
+export type PulseExecutionTarget = 'native' | 'javascript';
+export type PulseReportingLevel = 'off' | 'error' | 'warn' | 'info' | 'debug';
+export type PulseCryptoAlgorithm = 'HS256' | 'ES256' | 'SHA-256' | 'HMAC-SHA256';
+export type PulseCryptoRealization =
+  | 'runtime-builtin'
+  | 'guest-source:pulse-hmac-as'
+  | 'guest-linked:pulse-es256-rustcrypto-p256';
+export type PulseCryptoConfiguration =
+  | readonly PulseCryptoAlgorithm[]
+  | Readonly<Partial<Record<PulseCryptoAlgorithm, Readonly<{
+      realization?: PulseCryptoRealization;
+    }>>>>;
+
+export interface PulseConfigReference<Name extends string = string> {
+  readonly $config: Name;
+}
+
+export interface PulseSecretReference<Name extends string = string> {
+  readonly $secret: Name;
+}
+
+export type PulseSymbolicReference<Name extends string = string> =
+  | PulseConfigReference<Name>
+  | PulseSecretReference<Name>;
+
+export type PulseStaticValue =
+  | null
+  | string
+  | number
+  | boolean
+  | PulseSymbolicReference
+  | readonly PulseStaticValue[]
+  | { readonly [key: string]: PulseStaticValue };
+
+/** Symbolic configuration authority. It never exposes selected profiles or resolved values. */
+export interface PulseConfigScope {
+  config<const Name extends string>(name: Name): PulseConfigReference<Name>;
+  secret<const Name extends string>(name: Name): PulseSecretReference<Name>;
+}
+
+export interface PulseProjectOptions {
+  /** Workspace-relative application entry. Defaults to src/index.ts. */
+  readonly entry?: string;
+  /** Optional workspace-relative schema pointer. */
+  readonly schema?: string | null;
+  /** Optional workspace-relative test harness entry. */
+  readonly tests?: string | null;
+  /** Fallback after --profile and PULSE_PROFILE. No implicit local profile exists. */
+  readonly defaultProfile?: string | null;
+  /** Schema-bound request JSON is required when true. Defaults to true. */
+  readonly strict?: boolean;
+  /** Base log reporting threshold. Defaults to info. */
+  readonly reporting?: PulseReportingLevel;
+  /** Globally required crypto algorithms. A selected profile declaration replaces this value. */
+  readonly crypto?: PulseCryptoConfiguration;
+}
+
+export type PulseProfile = Readonly<{
+  host: string;
+  target: PulseExecutionTarget;
+  /** Flat profile override for pulse.reporting. */
+  reporting?: PulseReportingLevel;
+  /** Required crypto algorithms for this profile. Replaces pulse.crypto rather than merging. */
+  crypto?: PulseCryptoConfiguration;
+} & Record<string, PulseStaticValue>>;
+
+export type PulseProjectDeclaration = Readonly<{
+  pulse?: PulseProjectOptions;
+  [profile: string]: PulseProfile | PulseProjectOptions | undefined;
+}>;
+
+export interface PulseConfigFactory<out Declaration extends PulseProjectDeclaration = PulseProjectDeclaration> {
+  (scope: PulseConfigScope): Declaration;
+}
+
+/**
+ * Preserve and brand one synchronous project/profile declaration factory.
+ * The factory is evaluated only with symbolic config and secret references.
+ */
+export declare function defineConfig<const Declaration extends PulseProjectDeclaration>(
+  factory: PulseConfigFactory<Declaration>
+): PulseConfigFactory<Declaration>;
+
+export interface PulseAutoOptions {
+  readonly auto: true;
+}
+
+declare const pulseProfileTokenBrand: unique symbol;
+
+/** Opaque project-profile composition token. It has no readable public fields. */
+export interface PulseProfileToken {
+  readonly [pulseProfileTokenBrand]: true;
+}
+
+export type PulseEventDeclaration =
+  | Readonly<{ schema: string }>
+  | Readonly<{ schema: null }>;
+
+/**
+ * Project-aware application root. Pulse shares Router registration and execution
+ * semantics; the compiler attaches project/profile metadata beside Router IR.
+ */
+export declare class Pulse extends Router {
+  constructor(options: PulseAutoOptions);
+  constructor(config: PulseConfigFactory);
+  on<Payload = unknown>(
+    type: string,
+    declaration: Readonly<{ schema: string }>,
+    handler: import('@pulse-compute/runtime').PulseEventHandler<Payload>
+  ): this;
+  on(
+    type: string,
+    declaration: Readonly<{ schema: null }>,
+    handler: import('@pulse-compute/runtime').PulseEventHandler<null>
+  ): this;
+  profile(): PulseProfileToken;
+}
+
+export declare const PULSE_APPLICATION_API_VERSION: 'pulse.application-authoring.v3';

package/src/index.js

@@ -0,0 +1,8 @@
+'use strict';
+
+const { defineConfig } = require('@pulse-compute/wasm-contracts/project/config-factory');
+const { Pulse } = require('./internal/application.js');
+
+const PULSE_APPLICATION_API_VERSION = 'pulse.application-authoring.v3';
+
+module.exports = Object.freeze({ defineConfig, Pulse, PULSE_APPLICATION_API_VERSION });

package/src/internal/application.js

@@ -0,0 +1,75 @@
+'use strict';
+
+const { isConfigFactory } = require('@pulse-compute/wasm-contracts/project/config-factory');
+const { Router } = require('@pulse-compute/runtime');
+const {
+  addEventRegistration,
+  bindEventRegistrationReader,
+  createEventRegistrationTable,
+  eventRegistrationEntries
+} = require('./event-registration.js');
+
+const APPLICATION_STATE = new WeakMap();
+const EVENT_REGISTRATION_STATE = new WeakMap();
+const PROFILE_TOKEN_STATE = new WeakMap();
+const PROFILE_TOKEN_BRAND = Symbol('pulse.profile-token');
+
+function isAutoOptions(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const keys = Object.keys(value);
+  return keys.length === 1 && keys[0] === 'auto' && value.auto === true;
+}
+
+class Pulse extends Router {
+  constructor(options) {
+    super();
+    if (!isAutoOptions(options) && !isConfigFactory(options)) {
+      throw new TypeError('Pulse requires new Pulse({ auto: true }) or one defineConfig(...) factory.');
+    }
+    const token = {};
+    Object.defineProperty(token, PROFILE_TOKEN_BRAND, { enumerable: false, value: true });
+    Object.freeze(token);
+    const state = Object.freeze({
+      mode: isAutoOptions(options) ? 'auto' : 'explicit',
+      options,
+      profileToken: token
+    });
+    APPLICATION_STATE.set(this, state);
+    const eventRegistrations = createEventRegistrationTable();
+    EVENT_REGISTRATION_STATE.set(this, eventRegistrations);
+    bindEventRegistrationReader(this, eventRegistrations);
+    PROFILE_TOKEN_STATE.set(token, Object.freeze({ application: this }));
+  }
+
+  on(type, declaration, handler) {
+    addEventRegistration(EVENT_REGISTRATION_STATE.get(this), type, declaration, handler);
+    return this;
+  }
+
+  profile() {
+    return APPLICATION_STATE.get(this).profileToken;
+  }
+}
+
+function applicationState(application) {
+  const state = APPLICATION_STATE.get(application);
+  if (!state) throw new TypeError('Expected a Pulse application.');
+  return state;
+}
+
+function profileTokenOwner(token) {
+  return PROFILE_TOKEN_STATE.get(token)?.application;
+}
+
+function eventRegistrations(application) {
+  const table = EVENT_REGISTRATION_STATE.get(application);
+  if (!table) throw new TypeError('Expected a Pulse application.');
+  return eventRegistrationEntries(table);
+}
+
+module.exports = Object.freeze({
+  Pulse,
+  applicationState,
+  eventRegistrations,
+  profileTokenOwner
+});

package/src/internal/event-registration.js

@@ -0,0 +1,140 @@
+'use strict';
+
+const EVENT_REGISTRATION_VERSION = 'pulse.event-registration.v1';
+const EVENT_DECLARATION_VERSION = 'pulse.event-declaration.v1';
+const EVENT_TYPE_MAX_BYTES = 128;
+const EVENT_SCHEMA_ID_MAX_BYTES = 256;
+const SCHEMA_ID_PATTERN = /^[A-Za-z][A-Za-z0-9_-]*(?:\.[A-Za-z][A-Za-z0-9_-]*)+$/;
+const EVENT_REGISTRATION_READER_SYMBOL_KEY = 'pulse.runtime.event-registration-reader.v1';
+const EVENT_REGISTRATION_READER = Symbol.for(EVENT_REGISTRATION_READER_SYMBOL_KEY);
+
+const EVENT_REGISTRATION_DIAGNOSTIC_CODES = Object.freeze({
+  TYPE_INVALID: 'PULSEWASM_EVENTS_TYPE_INVALID',
+  SCHEMA_ID_INVALID: 'PULSEWASM_EVENTS_SCHEMA_ID_INVALID',
+  DECLARATION_INVALID: 'PULSEWASM_EVENTS_DECLARATION_INVALID',
+  HANDLER_INVALID: 'PULSEWASM_EVENTS_HANDLER_INVALID',
+  TYPE_DUPLICATE: 'PULSEWASM_EVENTS_TYPE_DUPLICATE'
+});
+
+function registrationError(code, message, detail = {}) {
+  const error = new TypeError(message);
+  error.name = 'PulseEventRegistrationError';
+  error.code = code;
+  error.detail = Object.freeze({ ...detail });
+  return error;
+}
+
+function utf8ByteLength(value) {
+  const text = String(value);
+  let bytes = 0;
+  for (let index = 0; index < text.length; index += 1) {
+    const point = text.codePointAt(index);
+    if (point <= 0x7f) bytes += 1;
+    else if (point <= 0x7ff) bytes += 2;
+    else if (point <= 0xffff) bytes += 3;
+    else {
+      bytes += 4;
+      index += 1;
+    }
+  }
+  return bytes;
+}
+
+function requireDataDeclaration(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw registrationError(EVENT_REGISTRATION_DIAGNOSTIC_CODES.DECLARATION_INVALID, 'Pulse.on declaration must be a plain object containing only schema.');
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    throw registrationError(EVENT_REGISTRATION_DIAGNOSTIC_CODES.DECLARATION_INVALID, 'Pulse.on declaration must be a plain object containing only schema.');
+  }
+  if (Object.getOwnPropertySymbols(value).length > 0) {
+    throw registrationError(EVENT_REGISTRATION_DIAGNOSTIC_CODES.DECLARATION_INVALID, 'Pulse.on declaration must not contain symbol keys.');
+  }
+  const keys = Object.keys(value);
+  if (keys.length !== 1 || keys[0] !== 'schema') {
+    throw registrationError(EVENT_REGISTRATION_DIAGNOSTIC_CODES.DECLARATION_INVALID, 'Pulse.on declaration must contain exactly one schema data property.', { fields: keys.sort() });
+  }
+  const descriptor = Object.getOwnPropertyDescriptor(value, 'schema');
+  if (!descriptor || !Object.prototype.hasOwnProperty.call(descriptor, 'value')) {
+    throw registrationError(EVENT_REGISTRATION_DIAGNOSTIC_CODES.DECLARATION_INVALID, 'Pulse.on declaration.schema must be an own data property.');
+  }
+  return descriptor.value;
+}
+
+function normalizeEventType(value) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw registrationError(EVENT_REGISTRATION_DIAGNOSTIC_CODES.TYPE_INVALID, 'Pulse.on event type must be a non-empty string.', { value });
+  }
+  const bytes = utf8ByteLength(value);
+  if (bytes > EVENT_TYPE_MAX_BYTES) {
+    throw registrationError(EVENT_REGISTRATION_DIAGNOSTIC_CODES.TYPE_INVALID, 'Pulse.on event type exceeds its UTF-8 byte limit.', { bytes, maxBytes: EVENT_TYPE_MAX_BYTES });
+  }
+  return value;
+}
+
+function normalizeEventDeclaration(value) {
+  const schema = requireDataDeclaration(value);
+  if (schema !== null && (typeof schema !== 'string' || !SCHEMA_ID_PATTERN.test(schema) || utf8ByteLength(schema) > EVENT_SCHEMA_ID_MAX_BYTES)) {
+    throw registrationError(EVENT_REGISTRATION_DIAGNOSTIC_CODES.SCHEMA_ID_INVALID, 'Pulse.on schema must be a bounded dotted schema ID or null.', { schema });
+  }
+  return Object.freeze({ version: EVENT_DECLARATION_VERSION, schemaId: schema });
+}
+
+function normalizeEventRegistration(typeInput, declarationInput, handler) {
+  const type = normalizeEventType(typeInput);
+  const declaration = normalizeEventDeclaration(declarationInput);
+  if (typeof handler !== 'function') {
+    throw registrationError(EVENT_REGISTRATION_DIAGNOSTIC_CODES.HANDLER_INVALID, 'Pulse.on requires an event handler function.');
+  }
+  return Object.freeze({
+    version: EVENT_REGISTRATION_VERSION,
+    type,
+    declaration,
+    handler
+  });
+}
+
+function createEventRegistrationTable() {
+  return { entries: [], types: new Set() };
+}
+
+function addEventRegistration(table, type, declaration, handler) {
+  const registration = normalizeEventRegistration(type, declaration, handler);
+  if (table.types.has(registration.type)) {
+    throw registrationError(EVENT_REGISTRATION_DIAGNOSTIC_CODES.TYPE_DUPLICATE, `Pulse event type ${JSON.stringify(registration.type)} is already registered.`, { type: registration.type });
+  }
+  table.types.add(registration.type);
+  table.entries.push(registration);
+  return registration;
+}
+
+function eventRegistrationEntries(table) {
+  return Object.freeze([...table.entries]);
+}
+
+function bindEventRegistrationReader(application, table) {
+  Object.defineProperty(application, EVENT_REGISTRATION_READER, {
+    enumerable: false,
+    configurable: false,
+    writable: false,
+    value: () => eventRegistrationEntries(table)
+  });
+  return application;
+}
+
+module.exports = Object.freeze({
+  EVENT_REGISTRATION_VERSION,
+  EVENT_DECLARATION_VERSION,
+  EVENT_TYPE_MAX_BYTES,
+  EVENT_SCHEMA_ID_MAX_BYTES,
+  EVENT_REGISTRATION_READER_SYMBOL_KEY,
+  EVENT_REGISTRATION_DIAGNOSTIC_CODES,
+  normalizeEventType,
+  normalizeEventDeclaration,
+  normalizeEventRegistration,
+  createEventRegistrationTable,
+  addEventRegistration,
+  eventRegistrationEntries,
+  bindEventRegistrationReader
+});

package/src/internal/index.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('./application.js');

package/src/schema.d.ts

@@ -0,0 +1,51 @@
+export type Int32 = number & { readonly __pulseInt32?: never };
+export type Uint32 = number & { readonly __pulseUint32?: never };
+
+declare const schemaDeclarationBrand: unique symbol;
+declare const responseCaseDeclarationBrand: unique symbol;
+declare const schemaRegistryBrand: unique symbol;
+
+export interface SchemaDeclaration<Type> {
+  readonly [schemaDeclarationBrand]: Type;
+}
+
+export interface ResponseCaseDeclaration<
+  Status extends number = number,
+  SchemaId extends string = string
+> {
+  readonly status: Status;
+  readonly schemaId: SchemaId;
+  readonly [responseCaseDeclarationBrand]: true;
+}
+
+export interface SchemaRegistryDeclaration<
+  Schemas extends Readonly<Record<string, SchemaDeclaration<unknown>>>,
+  Responses extends Readonly<Record<string, ResponseCaseDeclaration>>
+> {
+  readonly schemas: Schemas;
+  readonly responses?: Responses;
+  readonly [schemaRegistryBrand]: true;
+}
+
+/** Declare one required object-root schema. The stable string key is authoritative. */
+export declare function schema<Type>(): SchemaDeclaration<Type>;
+
+/** Map one semantic response-case ID to an HTTP status and registered schema ID. */
+export declare function response<const Status extends number, const SchemaId extends string>(
+  status: Status,
+  schemaId: SchemaId
+): ResponseCaseDeclaration<Status, SchemaId>;
+
+/**
+ * Preserve one static schema registry. Pulse extracts this default-exported call;
+ * it does not execute application registry code during compilation.
+ */
+export declare function defineSchemaRegistry<
+  const Schemas extends Readonly<Record<string, SchemaDeclaration<unknown>>>,
+  const Responses extends Readonly<Record<string, ResponseCaseDeclaration>>
+>(registry: {
+  readonly schemas: Schemas;
+  readonly responses?: Responses;
+}): SchemaRegistryDeclaration<Schemas, Responses>;
+
+export declare const SCHEMA_AUTHORING_VERSION: 'pulse.schema-authoring.v1';

package/src/schema.js

@@ -0,0 +1,45 @@
+'use strict';
+
+const SCHEMA_AUTHORING_VERSION = 'pulse.schema-authoring.v1';
+const SCHEMA_DECLARATION_BRAND = Symbol.for('pulse.schema-declaration.v1');
+const RESPONSE_CASE_DECLARATION_BRAND = Symbol.for('pulse.response-case-declaration.v1');
+const SCHEMA_REGISTRY_BRAND = Symbol.for('pulse.schema-registry.v1');
+
+function schema() {
+  return Object.freeze({
+    version: SCHEMA_AUTHORING_VERSION,
+    [SCHEMA_DECLARATION_BRAND]: true
+  });
+}
+
+function response(status, schemaId) {
+  if (!Number.isSafeInteger(status) || status < 100 || status > 599) {
+    throw new TypeError('response(status, schemaId) requires an HTTP status from 100 through 599.');
+  }
+  if (typeof schemaId !== 'string' || schemaId.trim() === '') {
+    throw new TypeError('response(status, schemaId) requires a non-empty schema ID.');
+  }
+  return Object.freeze({
+    version: SCHEMA_AUTHORING_VERSION,
+    status,
+    schemaId: schemaId.trim(),
+    [RESPONSE_CASE_DECLARATION_BRAND]: true
+  });
+}
+
+function defineSchemaRegistry(registry) {
+  if (!registry || typeof registry !== 'object' || Array.isArray(registry)) {
+    throw new TypeError('defineSchemaRegistry requires a static registry object.');
+  }
+  return Object.freeze({
+    ...registry,
+    [SCHEMA_REGISTRY_BRAND]: SCHEMA_AUTHORING_VERSION
+  });
+}
+
+module.exports = Object.freeze({
+  SCHEMA_AUTHORING_VERSION,
+  defineSchemaRegistry,
+  schema,
+  response
+});