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

package/docs/guides/routing.md

@@ -0,0 +1,202 @@
+# Static Router authoring
+
+Use `Router` when an application has several method/path entry points or needs compile-time middleware. It is a static authoring marker from `@pulse-compute/runtime`, not a JavaScript runtime dispatcher. The shared async/static restrictions are defined in [Managed handler TypeScript and JavaScript](https://pulsecompute.io/v1.0.0-beta.2/reference/handler-authoring/); target claims live in the [compatibility matrix](https://pulsecompute.io/v1.0.0-beta.2/reference/compatibility-matrix/).
+
+<!-- pulse-doc-source: examples/09-router-lowering/src/index.ts -->
+```ts
+import { Router } from '@pulse-compute/runtime'
+
+interface User {
+  id: number
+  name: string
+}
+
+const users = new Router()
+const api = new Router()
+const app = new Router()
+
+app.use(async (ctx, next) => {
+  if (ctx.req.header('x-pulse-deny') === '1') {
+    return ctx.json(
+      { error: 'denied by middleware' },
+      { status: 401 },
+    )
+  }
+  return next()
+})
+
+api.use(async (ctx, next) => {
+  if (ctx.req.header('x-api-state') === 'closed') {
+    return ctx.text('api closed', { status: 503 })
+  }
+  return next()
+})
+
+users.get('/:id', async (ctx) => {
+  const id = ctx.param('id')
+  const user = await ctx
+    .fetch('https://users.example.test/users/' + id)
+    .json<User>()
+  return ctx.json({ route: 'user', id, user })
+})
+
+api.get('/health', async (ctx, next) => {
+  if (ctx.req.header('x-health-handler') === 'fallback') {
+    return next()
+  }
+  return ctx.json({ ok: true, handler: 'primary' })
+})
+api.get('/health', async (ctx) => ctx.json({ ok: true, handler: 'fallback' }))
+api.head('/health', async (ctx) => ctx.text('', {
+  status: 204,
+  headers: [['x-pulse-route', 'health']],
+}))
+api.post('/users', async (ctx) => ctx.json(
+  { route: 'create', method: ctx.req.method },
+  { status: 201 },
+))
+api.get('/files/*', async (ctx) => ctx.text(ctx.req.path))
+api.get('/failure', async (ctx, next) => next('documented-failure'))
+
+api.mount('/users', users)
+app.mount('/api', api)
+
+app.error(async (error, ctx, next) => {
+  if (error === 'documented-failure') {
+    return ctx.json({ error: 'handled' }, { status: 418 })
+  }
+  return next(error)
+})
+
+export default app
+```
+<!-- /pulse-doc-source -->
+
+## Supported v2 surface
+
+- `new Router()` with a default-exported root router;
+- `use(handler)` and `use(path, handler)` middleware;
+- `get`, `head`, `post`, `put`, `patch`, and `delete` registrations;
+- exact paths, named `:parameters`, and a trailing `*` wildcard;
+- static acyclic `mount` composition;
+- named or inline async-shaped route handlers using `(ctx)` or `(ctx, next)`;
+- async-shaped middleware using `(ctx, next)`;
+- async-shaped error middleware using `(error, ctx, next)`;
+- `ctx.param('name')` for a parameter declared by the matched route;
+- first-match order, explicit route fallthrough, and compiler-owned 404/500 exhaustion.
+
+Every Router handler uses the normal canonical context. Fetches, schemas, config, secrets, KV, opaque responses, and trusted package effects lower into the same native execution plan as single-handler authoring.
+
+`Pulse` inherits the same route registration methods. Each registration matches
+its exact HTTP method; a method mismatch advances the route cursor and normal
+exhaustion remains `404`. There is no automatic `OPTIONS` or `405` response.
+Ingress route methods do not widen the separate outbound `ctx.fetch` contract.
+
+The `catalog-router-parity` conformance task exercises the original Catalog
+consumer probe and all 14 of its PUT/PATCH/DELETE operations with their existing
+methods and paths. Its shared cases check mounted parameters, request text,
+middleware state, exact method misses, registration order, terminal fallthrough,
+404 exhaustion and handled errors on Node/Fastly JavaScript and Native. Native
+lanes execute compiled Wasm; Fastly evidence uses local provider emulation and
+the target ABI mock host, not a deployed service. The fixtures establish routing
+acceptance only; they do not implement Catalog persistence or authorization.
+
+```sh
+node wasm/scripts/run-wasm-tests.cjs --task catalog-router-parity --no-report
+```
+
+## `next()` is a terminal transfer
+
+`next()` is not an onion-style callback. It is a compiler-visible control transfer:
+
+```ts
+app.use(async (ctx, next) => {
+  if (!authorized(ctx)) return ctx.text('unauthorized', { status: 401 })
+  return next()
+})
+```
+
+After `return next()`, the current handler is finished permanently. The Router cursor advances to the next applicable middleware or route. The handler never resumes and `next()` has no downstream response value.
+
+These forms are rejected:
+
+```ts
+next()
+return ctx.text('too late')
+```
+
+```ts
+const response = next()
+return response
+```
+
+Use `return next(error)` to enter the error lane:
+
+```ts
+app.get('/account', async (ctx, next) => {
+  if (!ctx.req.header('x-account')) return next('missing-account')
+  return ctx.text('ok')
+})
+
+app.error(async (error, ctx, next) => {
+  if (error === 'missing-account') return ctx.text('account required', { status: 400 })
+  return next(error)
+})
+```
+
+If the normal lane is exhausted, Pulse returns `404 Not Found`. If the error lane is exhausted, Pulse returns `500 Internal Server Error`.
+
+## Middleware scope and effects
+
+A path-scoped `use('/api', handler)` applies only to that subtree. Middleware declared on a mounted child Router is naturally limited to the mounted subtree.
+
+Middleware may request normal canonical effects before transferring control:
+
+```ts
+app.use(async (ctx, next) => {
+  const access = await ctx.fetch('https://auth.example.test/check').json<{ allowed: boolean }>()
+  if (!access.allowed) return ctx.text('denied', { status: 403 })
+  return next()
+})
+```
+
+Pulse owns suspension and resumption for the effect. `pulse inspect` attributes the effect and continuation to the middleware entry and then resumes the same flat Router execution graph.
+
+
+Use `ctx.parallel({ ... })` inside any managed route or middleware when named
+operations must begin together on both JavaScript and Native targets. Its fixed
+object-literal property order owns effect identity and result reconstruction, and
+the group settles completely before Router execution continues. Separate awaits
+retain ordinary sequential JavaScript behavior; Native may additionally group
+adjacent eligible effects as an optimization.
+
+
+## Deliberately outside v2
+
+Canonical Router v2 does not support onion-style post-`next()` work, assigning or awaiting `next()`, user-authored `throw` as Router transfer, post-response hooks, realtime lifecycle registrations, channels, timeout scopes, `ctx.resolve`, or `ctx.resolved`.
+
+Observability and explicit post-response work should use dedicated future contracts such as trace or defer effects rather than hidden middleware unwinding.
+
+## Inspect the lowering
+
+```bash
+pulse inspect examples/09-router-lowering --json
+```
+
+Look at:
+
+```text
+compiler.authoring.kind
+compiler.routing.entries
+compiler.routing.semantics
+compiler.effects[*].routerEntryStableId
+compiler.continuations[*].routerEntryStableId
+compiler.native.planHash
+```
+
+The same project can then be compiled or built normally:
+
+```bash
+pulse compile examples/09-router-lowering
+pulse build examples/09-router-lowering
+```

package/docs/preview-scope.md

@@ -0,0 +1,142 @@
+# Beta scope
+
+Pulse `1.0.0-beta.2` is a Beta of one provider-neutral application contract
+with explicit Native and JavaScript execution targets. The intended 1.0
+surface is present, but deliberate corrections may still occur before the
+stable `1.0.0` release.
+
+The Beta is intentionally strict: Pulse builds the target selected by the
+active `.pulse/config.ts` profile, and unsupported source stops at the exact
+lowering boundary with a stable diagnostic. Pulse never silently switches
+targets.
+
+## Supported application behavior
+
+- Async-shaped provider-neutral TypeScript handlers; trusted Pulse awaits lower
+  into explicit effects and continuations without a Promise runtime.
+- Static Router v2 with terminal middleware, route fallthrough, error
+  middleware, GET/HEAD/POST/PUT/PATCH/DELETE routes, exact paths, named parameters, trailing
+  wildcards, and acyclic mounts.
+- Basic branching and structured object, array, and scalar manipulation.
+- Request method, URL, path, headers, text, and JSON access.
+- Bounded, memoized structured body decoding.
+- Explicit TypeScript JSON schema declarations and literal schema IDs.
+- GET, HEAD, and POST fetch effects.
+- Independent Native effect grouping, dependent continuation chains, and
+  explicit cross-target `ctx.parallel({ ... })` keyed groups.
+- HTTP status and headers as ordinary response data.
+- JSON, text, custom, and direct pass-through responses.
+- Exact-name config and secret reads.
+- Named KV `get` and `put`.
+- Opaque host-owned binary and stream pass-through.
+- Stateless package-root GRIP request classification, response subscription and
+  handoff framing, and configured request-bound broadcast.
+- Synchronous string logging through `ctx.log.error`, `warn`, `info`, and
+  `debug`, with flat profile reporting thresholds and provider-owned output.
+- Root-only static `Pulse.on` declarations, immutable schema-validated event
+  contexts, and one-way `ctx.emit` acceptance through the bounded Node
+  JavaScript/Native reference adapter.
+- Provider-neutral portable Wasm and configured Native Node or Fastly builds.
+- Direct JavaScript execution and deterministic source packaging for Node and
+  Fastly.
+
+## Execution contract
+
+The Beta has two target classes and four explicitly selected
+execution modes over one application model:
+
+```text
+source
+├─ Node / Native        → canonical analysis → Pulse-owned Wasm → Node realization
+├─ Node / JavaScript    → graph-backed loader → live packages → Node lifecycle
+├─ Fastly / Native      → canonical analysis → direct-host-ABI bin/main.wasm
+└─ Fastly / JavaScript  → deterministic source package → Fastly JS runtime candidate
+```
+
+Native source that crosses the supported lowering boundary fails visibly with a
+stable diagnostic. JavaScript core Router execution, request/response lifecycle,
+eligibility inspection, effects, package realizations, source packaging, schema
+enforcement, target integrity, and bounded GRIP realization are implemented.
+Native/JavaScript conformance covers Router context, body handling, fetch
+projections, configuration, secrets, KV, schema codecs, GRIP framing, logging,
+and target identity. All declared Node and Fastly full-target-support gates are
+satisfied for the implemented four-mode contract.
+
+Fastly JavaScript candidate evidence compiles the deterministic source package
+with the exact pinned downstream toolchain and records a structurally deployable
+runtime artifact. The final release candidate must additionally pass the
+mandatory external Fastly CLI-managed reality lane. Neither result authorizes a
+service deployment or activation.
+
+There is no automatic fallback. An operator must select the target through
+project configuration or an explicitly permitted CLI target selection. A
+successful provider-neutral compile does not silently change a
+JavaScript-selected project into a Native one.
+
+## Deliberately unsupported
+
+- Automatic fallback from Native lowering to JavaScript execution.
+- Declaring general target availability without satisfying every declared
+  full-target-support gate.
+- Arbitrary Promise construction, arbitrary library awaits under Native
+  selection, JSPI, or Asyncify semantics. Managed `async` wrappers and trusted
+  Pulse awaits are supported notation, not a Promise runtime.
+- Ambient `fetch`, environment variables, filesystem, process, sockets, or
+  timers.
+- Provider SDK objects or `ctx.fastly` / `ctx.cloudflare` namespaces.
+- Capability enumeration or runtime provider introspection.
+- Automatic discovery of arbitrary TypeScript types.
+- Dynamic schema IDs.
+- Arbitrary binary body inspection or mutation.
+- Userland chunk iteration, transform streams, or manual backpressure.
+- Background tasks and work that outlives the request.
+- Raw TCP or UDP sockets.
+- Dynamic GRIP channel, framing-option, or message shapes under Native
+  selection.
+- Onion-style post-`next()` middleware, assigning or awaiting `next()`, Router
+  `throw` transfer, realtime hooks, channels, timeout scopes, `ctx.resolve`, or
+  `ctx.resolved`.
+- Third-party provider or lowerer self-registration.
+- A public event listener, production event transport, delivery/retry
+  guarantee, automatic loopback or reentrancy, generic bus, `ctx.call`, or
+  request/reply event routing.
+- Fastly, browser, or ESP32 event ingress/emit realization. Fastly fails closed
+  with exact eligibility diagnostics; browser and ESP32 remain unclaimed.
+
+## Compatibility authority
+
+The single source-form, provider-binding, artifact, and deployment-boundary
+table is [Provider and target compatibility](https://pulsecompute.io/v1.0.0-beta.2/reference/compatibility-matrix/).
+It uses one public target order—Node JavaScript, Fastly JavaScript, Node Native,
+and Fastly Native—and links every row to a focused proof or canonical contract.
+
+The exact portable language subset and the JavaScript-only Native eligibility
+boundaries are defined in
+[Managed handler TypeScript and JavaScript](https://pulsecompute.io/v1.0.0-beta.2/reference/handler-authoring/).
+
+## Body model
+
+If a body is inspected as text or JSON, Pulse treats it as a bounded immutable
+value. If a body is passed through as binary or a stream, it remains an opaque
+host-owned capability handle.
+
+```text
+inspect it → bounded structured value
+pass it through → opaque handle
+```
+
+## Compatibility and release signals
+
+- Documented behavior is intentional and evidence-backed.
+- Unsupported behavior fails explicitly.
+- No execution target silently falls back.
+- Public surfaces may still change deliberately before stable `1.0.0`.
+- Implementation and historical subpaths do not gain accidental compatibility
+  guarantees.
+- Package names, release artifacts, and published versions are immutable once
+  released.
+
+The intended npm dist-tag for the Beta is `beta`. It becomes
+active only through the atomic documentation-release transaction and an
+explicitly authorized publication. The workflow never assigns `latest`
+implicitly.

package/package.json

@@ -1,15 +1,48 @@
 {
   "name": "@pulse-compute/runtime",
-  "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": "Portable Pulse authoring and execution contract for handlers, contexts, and static routers.",
+  "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"
+    },
+    "./host": {
+      "types": "./src/host.d.ts",
+      "require": "./src/host.js",
+      "default": "./src/host.js"
+    },
+    "./package": {
+      "types": "./src/package.d.ts",
+      "require": "./src/package.js",
+      "default": "./src/package.js"
+    }
+  },
   "files": [
+    "src",
     "README.md",
+    "docs",
     "LICENSE",
     "NOTICE"
   ],
   "publishConfig": {
-    "access": "public",
-    "tag": "bootstrap"
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pulse-compute/pulse.git",
+    "directory": "packages/runtime"
+  },
+  "homepage": "https://pulsecompute.io/v1.0.0-beta.2/packages/runtime/",
+  "bugs": {
+    "url": "https://github.com/pulse-compute/pulse/issues"
   }
-}
+}