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

package/docs/packages/provider-fastly.md

@@ -0,0 +1,243 @@
+# `@pulse-compute/provider-fastly`
+
+`@pulse-compute/provider-fastly` supplies typed Fastly project configuration,
+canonical capability lowering, direct JavaScript execution, local conformance
+runtimes, Native and JavaScript Compute target generation, and an explicit
+Fastly CLI boundary.
+
+Install it only in projects that select the Fastly provider.
+
+## Install
+
+```bash
+npm install @pulse-compute/provider-fastly@1.0.0-beta.2
+```
+
+## Configure a project
+
+<!-- pulse-doc-source: examples/05-fastly-capabilities/.pulse/config.ts -->
+```ts
+import { defineConfig } from '@pulse-compute/pulse'
+
+export default defineConfig((scope) => ({
+  pulse: {
+    entry: 'src/index.ts',
+    tests: 'tests/pulse.harness.ts',
+    defaultProfile: 'local',
+    strict: true,
+  },
+  local: {
+    host: 'fastly',
+    target: 'native',
+    outDir: 'dist',
+    apiBase: scope.config('API_BASE'),
+    apiToken: scope.secret('API_TOKEN'),
+    dev: {
+      config: { API_BASE: 'https://api.example.com' },
+      secrets: {
+        API_TOKEN: 'local-example-secret',
+        GRIP_TOKEN: 'local-grip-secret',
+      },
+      kv: {
+        sessions: { 'session:123': { userId: 123 } },
+      },
+      fetches: {
+        'https://api.example.com/users/7': {
+          value: { id: 7, name: 'Ada' },
+        },
+        'POST https://publisher.example.com/publish': {
+          status: 202,
+          value: { accepted: true, messageId: 'message-1' },
+        },
+      },
+    },
+    fastly: {
+      bindings: {
+        configStore: 'app_config',
+        secretStore: 'app_secrets',
+        kv: { sessions: 'app_sessions' },
+        backends: {
+          'https://api.example.com': 'api_backend',
+          'https://publisher.example.com': 'publisher_backend',
+        },
+        dynamicBackends: false,
+        grip: {
+          publishEndpoint: 'https://publisher.example.com/publish',
+          publishBackend: 'publisher_backend',
+          authentication: {
+            scheme: 'bearer',
+            secretRef: 'GRIP_TOKEN',
+          },
+        },
+      },
+      build: { name: 'pulse-fastly-capabilities-example' },
+    },
+  },
+}))
+```
+<!-- /pulse-doc-source -->
+
+The provider maps logical origins and stores used by canonical handler calls to Fastly deployment resources. Local values and fixtures do not create or populate deployed resources.
+
+## Configuration groups
+
+The root `fastly()` helper supports:
+
+- Config Store and Secret Store names;
+- logical KV namespace to Fastly KV Store mappings;
+- origin to backend-name mappings;
+- explicit dynamic-backend policy;
+- GRIP/Fanout hold and publish bindings;
+- package name, description, and authors;
+- local network-fetch policy.
+
+See [Project configuration](../reference/project-config.md#fastly-provider-options) for field-level defaults, precedence, and constraints.
+
+## Build outputs
+
+The active `.pulse/config.ts` profile selects one target explicitly:
+
+```bash
+pulse build ./my-app
+```
+
+### Fastly Native
+
+`target: 'native'` compiles the provider-neutral plan and emits generated
+`src/main.as.ts` plus compact `bin/main.wasm` importing the required `fastly_*`
+hostcalls directly. It contains no JavaScript runtime image or `pulse_host`.
+Clock-dependent capabilities import only WASI `clock_time_get`.
+
+Conditional KV (`getVersioned`, `insertIfAbsent`, `compareAndSwap`) uses this
+Native path and the existing logical KV bindings. It preserves generation tokens
+without numeric narrowing, stages a bounded Pulse JSON envelope, and distinguishes
+confirmed rejection from unconfirmed dispatch. Pending completion and body reads
+use readiness selection with a monotonic deadline. Read bodies are closed; expired
+pending operations remain owned by invocation teardown, with no rollback promise.
+Fastly JavaScript remains explicitly incomplete for these operations. See
+[conditional KV](../concepts/effects-and-continuations.md#conditional-kv) for the
+portable contract. The generated-Wasm corpus is local evidence; it does not replace
+deployed cross-location acceptance. The legacy JavaScript fixture runner does
+not realize Native conditional KV; it reports a configuration failure. Exercise
+these operations through generated Wasm or the Compute execution lane.
+
+The required conditional KV acceptance task is `kv-conditional-acceptance`.
+It builds and installs exact tarballs and executes their Native artifact through
+Fastly CLI/Viceroy; an unavailable engine fails the task. Viceroy 0.21.0 currently
+fails the missing-key CAS contract: it creates the key instead of returning
+`conflict`. A September 12, 2026 standalone Rust SDK probe on deployed Fastly
+rejected CAS on both never-created and deleted keys, which remained absent.
+This resolves the live missing-key concern for those cases and distinguishes it
+from the Viceroy defect. The required local gate still fails, and full Pulse
+deployed cross-location acceptance remains pending the isolated development
+environment. The [K4 acceptance record](https://github.com/pulse-compute/pulse/blob/latest/wasm/test/kv/K4.md)
+retains both captures and their scope. Neither that standalone probe nor passing
+injected-host or portable tests clears the full acceptance gates.
+
+### Fastly JavaScript
+
+`target: 'javascript'` emits a deterministic, self-contained source closure:
+
+```text
+src/index.js
+src/application.js
+fastly.toml
+package.json
+pulse-esbuild.config.js
+pulse-fastly-javascript-candidate.json
+pulse-fastly-javascript-deployment.json
+pulse-fastly-javascript-source-package.json
+```
+
+The closure pins `esbuild` and `@fastly/js-compute`, bundles the reachable Pulse
+application and package implementations, and contains no Pulse Native artifact.
+The generated build first produces `dist/index.js`, then the pinned Fastly
+JavaScript compiler produces `bin/main.wasm`. Candidate, source-package,
+deployment, and top-level manifests agree on the selected `fastly-javascript`
+target and retain `automaticFallback: false`.
+
+The release gate builds the source closure twice, compares its bytes, and
+successfully invokes the pinned downstream compiler. The resulting runtime Wasm
+is bound to the candidate by SHA-256. Wizer-owned runtime snapshot bytes are not
+claimed byte-reproducible; the Pulse-owned closure and deployment metadata are.
+
+Provider selection is configuration-owned. Removed public `--provider` and
+`--source-only` flags are rejected with stable diagnostics.
+
+Use:
+
+```bash
+pulse doctor ./my-app --json
+```
+
+to inspect compiler and Fastly CLI readiness before a release build.
+
+## Local conformance and external reality
+
+For Fastly Native, `pulse test` and `pulse dev` use the provider’s local
+canonical runtime. For Fastly JavaScript, they use explicit provider emulation
+and the same provider-owned bundled application closure. Both paths use
+configured values, fixtures, and optional network fetch; neither silently runs
+through the Node provider.
+
+The native provider module is checked by the explicit reality profile through an inspected local Compute launcher. `PULSE_FASTLY_BIN` selects CLI-owned `fastly compute serve --file`; `PULSE_VICEROY_BIN` selects direct `viceroy serve` when no explicit Fastly CLI launcher is selected. Both are documented in [Environment variables](../reference/environment.md#pulse-fastly-bin).
+
+The Fastly reality gate proves Native local host-ABI compatibility through real
+HTTP requests covering schemas, configuration, secrets, KV persistence,
+named-backend fetch, opaque bytes, repeated headers, and GRIP hold/publish. The
+JavaScript candidate gate proves downstream runtime compilation but does not
+invoke `fastly compute serve`. Neither gate claims that remote resources or a
+deployed Fastly service are healthy; remote deployment remains separately
+unvalidated.
+
+Fastly JavaScript is generally available under the full-target-support policy:
+all declared runtime, capability, packaging, four-mode, tooling, and offline
+candidate gates are satisfied. General availability is a supported-target
+statement, not evidence that a particular candidate was deployed.
+
+## Public entry points
+
+| Entry point | Purpose |
+|---|---|
+| `@pulse-compute/provider-fastly` | Typed `fastly()` project configuration. |
+| `@pulse-compute/provider-fastly/contract` | Canonical descriptor and lowering-plan integration. |
+| `@pulse-compute/provider-fastly/runtime/canonical-api-runtime` | Local canonical runtime used by project execution. |
+| `@pulse-compute/provider-fastly/build/canonical-target` | Fastly source/target writer. |
+| `@pulse-compute/provider-fastly/testing/fastly-cli` | Explicit Fastly CLI discovery and serve boundary. |
+
+Other exported compiler/runtime subpaths are compatibility or implementation surfaces and do not gain the same application-facing promise.
+
+## Handler isolation
+
+Application source continues to import only `@pulse-compute/runtime` and supported package facades. The provider plan records:
+
+```json
+{
+  "providerSpecificUserland": false,
+  "providerSdkUserland": false,
+  "capabilityDiscoveryFromUserland": false
+}
+```
+
+Do not import Fastly SDK objects into canonical handlers. Bindings belong in project configuration.
+
+## Current limitations
+
+- The official `fastly` shorthand resolves this package's explicit
+  `./toolchain` export. That narrow bootstrap is not automatic plugin
+  discovery, self-registration, or a lowerer extension API.
+- Local fixtures do not provision Fastly resources.
+- Offline candidate validation does not deploy, activate, or publish a Fastly service.
+- Dynamic backends are disabled unless explicitly enabled.
+- GRIP requires the documented Fanout/publish bindings for the operations used.
+- Full userland stream processing and provider SDK escape hatches remain
+  outside the Beta.
+
+## Related documentation
+
+- [Fastly deployment candidates](../guides/deploying-fastly.md)
+- [Fastly config, secrets, and KV](../guides/fastly-capabilities.md)
+- [GRIP and Fanout](../guides/grip.md)
+- [Contracts and providers](../concepts/contracts-and-providers.md)
+- [Add a core provider](../contributing/adding-core-provider.md)
+- [Fastly diagnostics](../reference/diagnostics.md#toolchain-diagnostics)

package/docs/packages/pulse.md

@@ -0,0 +1,159 @@
+# `@pulse-compute/pulse`
+
+`@pulse-compute/pulse` is the conventional application-authoring package for a
+Pulse project. It owns the project-aware `Pulse` application root, deferred
+configuration factory, and static schema declarations while reusing the
+provider-neutral runtime contract.
+
+## Install
+
+```bash
+npm install @pulse-compute/pulse@1.0.0-beta.2
+```
+
+The package exposes two supported entry points:
+
+- `@pulse-compute/pulse` for `Pulse`, `defineConfig`, and runtime-owned
+  authoring types;
+- `@pulse-compute/pulse/schema` for `schema`, `response`, and
+  `defineSchemaRegistry`.
+
+## 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
+```
+
+`Pulse` extends the same live `Router` implementation exposed by
+`@pulse-compute/runtime`; it does not introduce a second routing or execution
+system. Compiler analysis normalizes the application into the canonical Router
+IR before target selection and provider realization.
+
+`Pulse` also owns root-only static event registration:
+
+```ts
+app.on('device.reading', { schema: 'events.DeviceReading' }, async (ctx) => {
+  const reading = ctx.event.payload
+  await ctx.config.get('MODE')
+  void reading
+})
+
+app.on('system.tick', { schema: null }, async (ctx) => {
+  void ctx.event.type
+})
+```
+
+Event types and schema IDs are literal compiler inputs, every type has one
+owner, and non-null schemas must resolve through the project registry. Event
+handlers receive a non-HTTP context and complete with `void`. The compiler
+places HTTP and event handlers in separate planes of one application-entry
+table. Eligible event handlers can lower through the conditional
+provider-neutral Native event ABI. Node has a bounded invocation-scoped
+reference ingress and outbound-acceptance adapter for direct JavaScript/Native
+parity, but no public event bus, deployment listener, delivery guarantee, or
+other provider target support is implied.
+
+The complete authoring, frame, queue, target, diagnostic, and no-call boundary
+is documented in [Static events and outbound emission](../guides/events.md).
+
+The statically analyzable root forms are:
+
+```ts
+new Pulse({ auto: true })
+new Pulse(configFactory)
+```
+
+Aliases, subclasses, factories returning `Pulse`, mounted `Pulse` instances, and
+re-exported application roots remain outside the initial single-entry grammar.
+Use `Router` for mounted and child applications.
+
+## Project 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: 'local',
+    strict: true,
+    reporting: 'info',
+  },
+  local: {
+    host: 'node',
+    target: 'native',
+    apiBase: scope.config('API_BASE'),
+    token: scope.secret('API_TOKEN'),
+  },
+}))
+```
+
+The scope produces symbolic configuration and secret references only. It does
+not expose selected-profile state, resolved values, commands, or ambient
+environment authority.
+
+## Schema declarations
+
+```ts
+import {
+  defineSchemaRegistry,
+  response,
+  schema,
+} from '@pulse-compute/pulse/schema'
+
+interface User {
+  id: number
+  name: string
+}
+
+export default defineSchemaRegistry({
+  schemas: {
+    'app.User': schema<User>(),
+  },
+  responses: {
+    'app.UserResponse': response(200, 'app.User'),
+  },
+})
+```
+
+Schema calls are static declarations consumed by the compiler. They do not add
+runtime reflection or generic JSON parsing to the guest module.
+
+## Async-shaped handlers and execution state
+
+Conventional projects require async-shaped handlers. Native lowering erases the
+wrapper and lowers only recognized Pulse effects; it does not add Promise or
+Asyncify runtimes.
+
+See [Managed handler TypeScript and
+JavaScript](../reference/handler-authoring.md) for the canonical static source
+rules and JavaScript-only boundary, and the [compatibility
+matrix](../reference/compatibility-matrix.md) for four-mode support.
+
+`ctx.state` is an execution-scoped string map. HTTP executions share it across
+the forward Router cursor, mounted routers, error recovery, and Native
+continuation resumption; event executions share it across their continuation
+resumption. It is reset between HTTP requests and event invocations and does
+not expose enumeration, object values, or persistence.
+
+## Ownership boundary
+
+This package owns application ergonomics and declarations. It does not own
+Handler IR, effects, continuations, Native lowering, provider lifecycle, or
+provider-specific bootstraps. Fastly and other host realization remains in the
+corresponding provider package.
+
+For the lower-level static Router and complete context contract, see
+[`@pulse-compute/runtime`](./runtime.md). For project orchestration, see
+[`@pulse-compute/cli`](./cli.md).

package/docs/packages/runtime.md

@@ -0,0 +1,265 @@
+# `@pulse-compute/runtime`
+
+`@pulse-compute/runtime` is the canonical, provider-neutral TypeScript authoring surface for Pulse applications. Install it in every canonical project and import handler types or the static `Router` marker from the package root.
+
+## Install
+
+```bash
+npm install @pulse-compute/runtime@1.0.0-beta.2
+```
+
+A project created by `pulse init` depends on the public
+`@pulse-compute/pulse` conventional application package, which re-exports these
+runtime types for convenience. Public package availability remains
+release-manifest-owned.
+
+Conventional `.pulse` projects require async-shaped managed handlers and report `PULSE_HANDLER_ASYNC_REQUIRED` for synchronous forms. The compiler erases the wrapper and lowers trusted awaited Pulse effects through the Promise-free effect/continuation machinery.
+
+## Minimal handler
+
+<!-- pulse-doc-source: examples/01-hello-json/src/index.ts -->
+```ts
+import { Pulse } from '@pulse-compute/pulse'
+
+const app = new Pulse({ auto: true })
+
+app.get('/health', async (ctx) => ctx.json({ ok: true }))
+app.get('/hello', async (ctx) => ctx.json({ message: 'hello from Pulse' }))
+app.get('/*', async (ctx) => ctx.text('not found', { status: 404 }))
+
+export default app
+```
+<!-- /pulse-doc-source -->
+
+The source-bound example is the conventional authoring shape. Managed handlers are async-shaped, while `ctx` remains the handler's only authority.
+
+## Public contract
+
+The package exports:
+
+- `PulseRequest` for method, URL, path, headers, bounded text, and bounded JSON reads;
+- `PulseFetchInit` and `PulseFetchResponse` for canonical outbound fetches;
+- structured and opaque response types;
+- `PulseExecutionContext`, shared by HTTP and event handlers, with state, logging,
+  fetch, config, secret, KV, keyed parallel, and one-way event emission;
+- `PulseContext` with the shared authority plus HTTP request and response construction;
+- `PulseEvent`, `PulseEventContext`, and `PulseEventHandler` for exact type,
+  immutable schema payload, non-HTTP authority, and void completion;
+- `PulseResult`, `Handler`, `PulseRouteContext`, `RouteHandler`, `RouterMiddleware`, `RouterErrorHandler`, and `RouterNext`;
+- `Router`, the compile-time marker for static route topology;
+- `RUNTIME_API_VERSION`, currently `pulse.runtime-authoring.v4`, and `ROUTER_API_VERSION`, currently `pulse.router-authoring.v2`.
+
+The complete type-by-type reference is in [Canonical API](../../API.md).
+
+
+## Static Router applications
+
+```ts
+import { Router } from '@pulse-compute/runtime'
+
+const app = new Router()
+app.use(async (ctx, next) => {
+  if (!ctx.req.header('authorization')) return ctx.text('Unauthorized', { status: 401 })
+  return next()
+})
+app.get('/health', async (ctx) => ctx.json({ ok: true }))
+app.get('/users/:id', async (ctx) => ctx.json({ id: ctx.param('id') }))
+export default app
+```
+
+The compiler extracts and flattens static routes, middleware, mounts, and error entries before normal canonical lowering. `return next()` and `return next(error)` are terminal control transfers; the current handler never resumes. The marker does not dispatch through a JavaScript runtime. See [Static Router authoring](../guides/routing.md).
+
+## Request access
+
+```ts
+const method = ctx.req.method
+const path = ctx.req.path
+const requestId = ctx.req.header('x-request-id')
+const text = await ctx.req.text()
+const input = await ctx.req.json<{ name: string }>('app.CreateUserInput')
+```
+
+Schema-backed JSON reads use an exact ID declared by the selected `.pulse/config.ts` profile:
+
+```ts
+const input = await ctx.req.json<CreateUserInput>('app.CreateUserInput')
+```
+
+See [Explicit JSON schemas](../guides/json-schemas.md).
+
+
+## Async and execution state
+
+Native targets treat `async` and trusted `await` as authoring notation. The compiler erases the async wrapper, lowers awaited Pulse effects into the existing continuation state machine, warns when `await` wraps a proven synchronous `ctx` value, and rejects arbitrary library awaits for native selection. No Promise runtime or Asyncify transform is linked.
+
+The exact accepted source shapes, `ctx.parallel` record restrictions, and
+JavaScript-only forms live in [Managed handler TypeScript and
+JavaScript](../reference/handler-authoring.md). The tested four-mode claims live
+in the [compatibility matrix](../reference/compatibility-matrix.md).
+
+`ctx.state` is a synchronous execution-local string map:
+
+```ts
+ctx.state.set('request-id', 'r1')
+const requestId = ctx.state.get('request-id') // string | undefined
+```
+
+For HTTP, state is visible across forward middleware, mounted Routers, error
+recovery, and effect continuation resume. Event handlers use the same state
+surface across continuation resume. State is isolated between HTTP requests and
+between event invocations.
+
+With project `pulse.strict: true` (the default), schema-less request JSON is rejected. Explicit `pulse.strict: false` enables the byte-bounded `host-generic-json` capability for reachable schema-less calls; the native plan and manifest report that dynamic-host choice. Schema-bound JSON remains specialized in either mode.
+
+## Event context and Native ingress
+
+Static event handlers receive `PulseEventContext<Payload>`:
+
+```ts
+app.on('device.reading', { schema: 'events.DeviceReading' }, async (ctx) => {
+  const reading = ctx.event.payload
+  const mode = await ctx.config.get('MODE')
+  ctx.state.set('last-mode', mode)
+  void reading
+})
+```
+
+`ctx.event.type` is the exact registered event type. The payload is validated
+against the registration schema and detached before entry; a `schema: null`
+registration receives `null`. Event contexts expose shared execution authority
+but no request, route, response, middleware, or Router-transfer surface, and
+handlers complete with `void`.
+
+Eligible event handlers lower to the provider-neutral Native plan and execute
+through the conditional `pulse.native-event-abi.v1` entry. Event-only and mixed
+artifacts are supported; HTTP-only Native bytes remain unchanged. Node wraps
+this entry with an invocation-scoped bounded FIFO reference adapter for direct
+JavaScript/Native parity. That adapter is provider-maintainer infrastructure,
+not a public listener, deployment transport, or process-global bus.
+
+## Outbound events
+
+HTTP and event handlers can create a one-way, schema-bound effect:
+
+```ts
+await ctx.emit('device.led.set', {
+  schema: 'events.DeviceLedSet',
+  payload: { enabled: true },
+})
+
+await ctx.emit('system.tick', { schema: null })
+```
+
+The call must be awaited directly or through an awaited `ctx.parallel` group.
+Event type and schema IDs must be literal at compilation; non-null schemas must
+resolve in the project registry and require a payload, while `schema: null`
+forbids one. JavaScript and Native execution validate and detach the same frame
+before host acceptance and return `undefined`. Native suspends and resumes
+through the ordinary effect/continuation protocol. The Node reference adapter
+records exact accepted frames independently from its FIFO ingress queue, so it
+never performs automatic loopback. It does not deliver a receipt, persistence,
+retry, or public provider transport.
+
+`ctx.emit` is not a call operation. The runtime exposes no request/reply
+correlation, automatic local dispatch, `ctx.call`, or reserved call capability.
+See [Static events and outbound emission](../guides/events.md) for the frame,
+queue, target, and Native-extension details.
+
+## Logging
+
+`ctx.log` exposes four synchronous string methods:
+
+```ts
+ctx.log.error('failed to publish event')
+ctx.log.warn('retrying origin request')
+ctx.log.info('user created')
+ctx.log.debug('decoded request body')
+```
+
+The active profile’s flat `reporting` setting resolves `off`, `error`, `warn`,
+`info`, or `debug`; the default is `info`. Native lowering removes calls below
+the resolved threshold and writes enabled messages through the synchronous
+`pulse_log(level, ptr, len)` host ABI. JavaScript targets use the same threshold
+and provider-owned destination at runtime.
+
+Logging is not a Pulse effect and cannot suspend a handler. Sink failures are
+request-contained, and known request secrets are redacted before managed output.
+Messages are strings only; structured logging and application-significant side
+effects inside message expressions are outside the Beta contract.
+
+## Responses
+
+```ts
+return ctx.json({ ok: true }, { status: 201 })
+return ctx.text('not found', { status: 404 })
+return ctx.response({ status: 204 })
+```
+
+A schema-backed JSON response names its compiled schema:
+
+```ts
+return ctx.json(output, { schema: 'app.CreateUserOutput' })
+```
+
+## Host capabilities
+
+Canonical host work is requested through `ctx`:
+
+```ts
+const upstream = await ctx.fetch('https://api.example.test/items').json('app.ItemList')
+const mode = await ctx.config.get('MODE')
+const token = await ctx.secret.get('API_TOKEN')
+const session = await ctx.kv<{ userId: number }>('sessions').get('current')
+```
+
+Conditional KV extends the same namespace with `getVersioned`, `insertIfAbsent`,
+and `compareAndSwap`. The Node reference realizes them through JavaScript and
+compiled Native execution; Fastly Native uses direct conditional KV hostcalls. Reads pair a value with an opaque string generation;
+writes distinguish `stored`, `conflict`, `not-stored`, and `unknown` (possibly
+committed). Pulse snapshots candidates, preserves tokens without numeric
+coercion, and performs no automatic retry. Fastly JavaScript remains incomplete;
+K4 retains the deployed acceptance gate.
+The detailed contract is in [Effects and continuations](../concepts/effects-and-continuations.md#conditional-kv).
+
+Those calls are compiled into explicit effects and validated against the selected provider. See [Compilation and lowering](../concepts/compilation-and-lowering.md).
+
+## Structured and opaque fetch results
+
+A response can be inspected as bounded structured data:
+
+```ts
+const item = await ctx.fetch('https://api.example.test/item').json<{ id: number }>('app.Item')
+return ctx.json(item)
+```
+
+Or returned directly as an opaque pass-through response:
+
+```ts
+return ctx.fetch('https://assets.example.test/archive.bin')
+```
+
+Opaque bodies are returnable but not inspectable or iterable. See [Structured and opaque bodies](../concepts/bodies.md).
+
+## Deliberate exclusions
+
+The runtime contract does not expose:
+
+- arbitrary Promise construction or general Promise semantics under native lowering;
+- ambient `process.env`, global fetch, timers, or randomness;
+- provider SDK objects or provider-specific namespaces;
+- arbitrary binary body inspection;
+- userland stream transforms or background tasks;
+- raw sockets.
+
+The compiler rejects unsupported forms rather than treating them as
+provider-dependent behavior. See the
+[Beta scope](../preview-scope.md).
+
+## Package and installed references
+
+The npm tarball includes:
+
+- `docs/API.md` — the canonical API reference;
+- `docs/preview-scope.md` — the supported and excluded Beta surface.
+
+For workflow and project configuration, use [`@pulse-compute/cli`](./cli.md).