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

package/docs/reference/documentation-versions.json

@@ -0,0 +1,14 @@
+{
+  "schemaVersion": "pulse.documentation-versions.v1",
+  "latest": "1.0.0-beta.1",
+  "versions": [
+    {
+      "version": "1.0.0-beta.1",
+      "segment": "v1.0.0-beta.1",
+      "channel": "beta",
+      "releasedAt": "2026-08-01",
+      "status": "current",
+      "sourceManifest": "release/pulse-release-manifest.json"
+    }
+  ]
+}

package/docs/reference/environment.md

@@ -0,0 +1,347 @@
+# Environment-variable reference
+
+<!-- Generated by wasm/scripts/sync-reference-docs.cjs. Edit the source catalog, not this file. -->
+
+Pulse canonical handlers do not receive ambient process environment access. Handler authority comes only through the documented `ctx` capabilities and project/provider bindings. The variables here configure release tooling, compatibility helpers, or repository tests.
+
+Do not use these variables as a substitute for `ctx.config`, `ctx.secret`, or provider bindings. Secret-bearing compatibility URIs must be handled as credentials and must not be copied into diagnostics.
+
+## Index
+
+| Variable | Scope | Stability |
+|---|---|---|
+| [`PULSE_FASTLY_BIN`](#pulse-fastly-bin) | Supported tooling configuration | Supported Beta tooling override. |
+| [`PULSE_VICEROY_BIN`](#pulse-viceroy-bin) | Supported tooling configuration | Supported Beta tooling override. |
+| [`PULSE_PROFILE`](#pulse-profile) | Supported tooling configuration | Supported project-selection input. |
+| [`PULSE_RELEASE_REF`](#pulse-release-ref) | Contributor and test-only configuration | Repository release-workflow internal; not an application setting. |
+| [`PULSE_RELEASE_SHA`](#pulse-release-sha) | Contributor and test-only configuration | Repository release-workflow internal; not an application setting. |
+| [`PULSEWASM_ARTIFACTS_DIR`](#pulsewasm-artifacts-dir) | Contributor and test-only configuration | Contributor/test-only. |
+| [`PULSEWASM_TEST_TMP_ROOT`](#pulsewasm-test-tmp-root) | Contributor and test-only configuration | Contributor/test-only; may change with test-runner updates. |
+| [`PULSE_FASTLY_REALITY_EVIDENCE`](#pulse-fastly-reality-evidence) | Contributor and test-only configuration | Contributor/release tooling override. |
+| [`PULSE_FOUR_MODE_EVIDENCE`](#pulse-four-mode-evidence) | Contributor and test-only configuration | Contributor/release tooling override. |
+| [`PULSE_SOURCE_REVISION`](#pulse-source-revision) | Contributor and test-only configuration | Repository release-evidence internal; not an application setting. |
+| [`PULSE_SOURCE_IDENTITY_KIND`](#pulse-source-identity-kind) | Contributor and test-only configuration | Repository release-evidence internal; not an application setting. |
+| [`PULSE_SOURCE_DIGEST_SHA256`](#pulse-source-digest-sha256) | Contributor and test-only configuration | Repository release-evidence internal; not an application setting. |
+| [`PULSE_SOURCE_FILE_COUNT`](#pulse-source-file-count) | Contributor and test-only configuration | Repository release-evidence internal; not an application setting. |
+| [`PULSE_FAKE_FASTLY_CAPTURE`](#pulse-fake-fastly-capture) | Contributor and test-only configuration | Fixture-only; not a public tooling setting. |
+| [`PULSE_FAKE_VICEROY_CAPTURE`](#pulse-fake-viceroy-capture) | Contributor and test-only configuration | Fixture-only; not a public tooling setting. |
+| [`PULSE_ES256_REPRODUCTION_ROOT`](#pulse-es256-reproduction-root) | Contributor and test-only configuration | Contributor/test-only proof reproduction control. |
+| [`PULSE_ES256_REPRODUCTION_ARCHIVE`](#pulse-es256-reproduction-archive) | Contributor and test-only configuration | Contributor/test-only proof reproduction control. |
+| [`PULSE_RUST_CARGO`](#pulse-rust-cargo) | Contributor and test-only configuration | Contributor/test-only proof reproduction control. |
+| [`PULSE_RUSTC`](#pulse-rustc) | Contributor and test-only configuration | Contributor/test-only proof reproduction control. |
+
+## Supported tooling configuration
+
+Documented environment inputs accepted by release tooling. These configure tools, not handler authority.
+
+<a id="pulse-fastly-bin"></a>
+
+### `PULSE_FASTLY_BIN`
+
+Selects the Fastly CLI binary used for external target inspection and local Compute execution.
+
+| Property | Contract |
+|---|---|
+| Value | Absolute or relative executable path |
+| Default | No explicit path; discover `fastly` on `PATH`. |
+| Precedence | An explicit `binary` option wins, then `PULSE_FASTLY_BIN`, then `PATH` discovery. |
+| Consumer | Fastly CLI inspection and the external Compute reality gate. |
+| Secret safety | Not a secret. Do not point it at an untrusted executable. |
+| Stability | Supported Beta tooling override. |
+| Source owners | `packages/provider-fastly/src/testing/fastly-cli.js` |
+
+<a id="pulse-viceroy-bin"></a>
+
+### `PULSE_VICEROY_BIN`
+
+Selects an inspected Viceroy executable for direct local Compute execution when no explicit Fastly CLI launcher is selected.
+
+| Property | Contract |
+|---|---|
+| Value | Absolute or relative executable path |
+| Default | Unset; discover the Fastly CLI first, then Viceroy, on `PATH`. |
+| Precedence | An explicit launcher choice wins. Without one, an explicit Fastly CLI path selects CLI ownership; otherwise an explicit `viceroyBinary` or `PULSE_VICEROY_BIN` selects direct Viceroy execution. |
+| Consumer | External Fastly Compute reality gates, either as the direct local engine or as an explicit Fastly CLI engine override. |
+| Secret safety | Not a secret. Do not point it at an untrusted executable. |
+| Stability | Supported Beta tooling override. |
+| Source owners | `packages/provider-fastly/src/testing/fastly-cli.js` |
+
+<a id="pulse-profile"></a>
+
+### `PULSE_PROFILE`
+
+Selects the flat Pulse project profile when no explicit `--profile` option is supplied.
+
+| Property | Contract |
+|---|---|
+| Value | Pulse profile name |
+| Default | Unset; use `pulse.defaultProfile` when declared. |
+| Precedence | `--profile` wins, then `PULSE_PROFILE`, then `pulse.defaultProfile`. |
+| Consumer | Project-aware Pulse CLI commands using the `.pulse/config.ts` convention. |
+| Secret safety | Not a secret. It selects a committed profile and never carries resolved binding values. |
+| Stability | Supported project-selection input. |
+| Source owners | `wasm/packages/cli/src/project-config.js` |
+
+## Contributor and test-only configuration
+
+Repository harness controls. They are intentionally outside the application compatibility contract.
+
+<a id="pulse-release-ref"></a>
+
+### `PULSE_RELEASE_REF`
+
+Carries the sealed candidate release ref into the protected publish process for an equality check against GitHub's native identity.
+
+| Property | Contract |
+|---|---|
+| Value | Full Git ref (`refs/tags/v<version>`) |
+| Default | Unset; the protected npm workflow derives it from the sealed candidate. |
+| Precedence | When set by the workflow, it must exactly equal GitHub's native release-tag ref. |
+| Consumer | Protected npm publication identity binding. |
+| Secret safety | Not a secret. It is validated rather than trusted as independent authority. |
+| Stability | Repository release-workflow internal; not an application setting. |
+| Source owners | `scripts/release-publication.cjs` |
+
+<a id="pulse-release-sha"></a>
+
+### `PULSE_RELEASE_SHA`
+
+Carries the sealed candidate source commit into the protected publish process for an equality check against GitHub's native identity.
+
+| Property | Contract |
+|---|---|
+| Value | Full lowercase 40-character Git commit SHA |
+| Default | Unset; the protected npm workflow derives it from the sealed candidate. |
+| Precedence | When set by the workflow, it must exactly equal GitHub's native release-tag commit. |
+| Consumer | Protected npm publication identity binding. |
+| Secret safety | Not a secret. It is validated rather than trusted as independent authority. |
+| Stability | Repository release-workflow internal; not an application setting. |
+| Source owners | `scripts/release-publication.cjs` |
+
+<a id="pulsewasm-artifacts-dir"></a>
+
+### `PULSEWASM_ARTIFACTS_DIR`
+
+Redirects generated build and test artifacts away from the default repository directory.
+
+| Property | Contract |
+|---|---|
+| Value | Directory path |
+| Default | `wasm/artifacts`. |
+| Precedence | Overrides the repository artifact root for scripts that opt into it. |
+| Consumer | Build and test isolation. |
+| Secret safety | Not a secret. Use an isolated writable directory. |
+| Stability | Contributor/test-only. |
+| Source owners | `wasm/packages/build-support/src/artifacts-dir.js`, `wasm/scripts/build.cjs`, `wasm/scripts/run-wasm-tests.cjs` |
+
+<a id="pulsewasm-test-tmp-root"></a>
+
+### `PULSEWASM_TEST_TMP_ROOT`
+
+Pins test workspaces beneath a caller-managed temporary root.
+
+| Property | Contract |
+|---|---|
+| Value | Directory path |
+| Default | A suite-specific temporary directory. |
+| Precedence | When set, tests create their working directories beneath this root. |
+| Consumer | Documentation, CLI, provider, package-release, and clean-machine acceptance tests. |
+| Secret safety | Not a secret. The directory may contain generated projects and test data. |
+| Stability | Contributor/test-only; may change with test-runner updates. |
+| Source owners | `wasm/test/docs/assert-executable-documentation.cjs`, `wasm/test/release/assert-release-packages.cjs` |
+
+<a id="pulse-fastly-reality-evidence"></a>
+
+### `PULSE_FASTLY_REALITY_EVIDENCE`
+
+Selects the output path for the real Fastly host evidence report.
+
+| Property | Contract |
+|---|---|
+| Value | File path |
+| Default | Unset; the reality gate prints its normal test result without retaining a proof file. |
+| Precedence | When set, the real-host gate writes its redacted machine-readable proof to this path. |
+| Consumer | Fastly CLI-managed or direct-Viceroy local Compute reality gate. |
+| Secret safety | Not a secret. The proof intentionally excludes secret values and authorization plaintext. |
+| Stability | Contributor/release tooling override. |
+| Source owners | `wasm/test/provider/assert-fastly-compute-reality.cjs` |
+
+<a id="pulse-four-mode-evidence"></a>
+
+### `PULSE_FOUR_MODE_EVIDENCE`
+
+Selects the output path for the four-mode conformance evidence report.
+
+| Property | Contract |
+|---|---|
+| Value | File path |
+| Default | `wasm/.test-results/four-mode-conformance.json`. |
+| Precedence | When set, the four-mode conformance suite writes its revision-bound proof to this path. |
+| Consumer | Node/Fastly Native/JavaScript conformance evidence. |
+| Secret safety | Not a secret. The proof records target identities, support hashes, and test outcomes without application secrets. |
+| Stability | Contributor/release tooling override. |
+| Source owners | `wasm/test/contracts/assert-four-mode-conformance.cjs` |
+
+<a id="pulse-source-revision"></a>
+
+### `PULSE_SOURCE_REVISION`
+
+Propagates one source identity through an aggregate release replay so independently written evidence cannot drift.
+
+| Property | Contract |
+|---|---|
+| Value | 40-character lowercase source identity |
+| Default | Current Git commit, or a deterministic archive-tree identity outside a Git checkout. |
+| Precedence | When set by the release runner, every child evidence shard validates and reuses this exact identity. |
+| Consumer | Release-seal task, four-mode, and offline deployment-candidate evidence binding. |
+| Secret safety | Not a secret. It identifies source but grants no publication or deployment authority. |
+| Stability | Repository release-evidence internal; not an application setting. |
+| Source owners | `scripts/source-identity.cjs` |
+
+<a id="pulse-source-identity-kind"></a>
+
+### `PULSE_SOURCE_IDENTITY_KIND`
+
+Labels the provenance class of the propagated source identity.
+
+| Property | Contract |
+|---|---|
+| Value | Source identity classification |
+| Default | `git-commit` in a checkout or `archive-tree-sha256-160` for an extracted source tree. |
+| Precedence | Meaningful only with `PULSE_SOURCE_REVISION`; the release runner supplies both together. |
+| Consumer | Release-seal reports, test reports, four-mode evidence, and offline candidate manifests. |
+| Secret safety | Not a secret. It prevents an archive digest from being represented as a Git commit. |
+| Stability | Repository release-evidence internal; not an application setting. |
+| Source owners | `scripts/source-identity.cjs` |
+
+<a id="pulse-source-digest-sha256"></a>
+
+### `PULSE_SOURCE_DIGEST_SHA256`
+
+Preserves the full archive-tree digest behind the compatibility-width source revision field.
+
+| Property | Contract |
+|---|---|
+| Value | 64-character lowercase SHA-256 digest |
+| Default | Unset for Git commits; the full archive-tree digest outside a Git checkout. |
+| Precedence | The release runner supplies it with an archive-tree source identity. |
+| Consumer | Release-seal reports, test reports, four-mode evidence, and offline candidate manifests. |
+| Secret safety | Not a secret. It is integrity metadata and carries no release authority. |
+| Stability | Repository release-evidence internal; not an application setting. |
+| Source owners | `scripts/source-identity.cjs` |
+
+<a id="pulse-source-file-count"></a>
+
+### `PULSE_SOURCE_FILE_COUNT`
+
+Carries the source-file count associated with an archive-tree digest for audit clarity.
+
+| Property | Contract |
+|---|---|
+| Value | Non-negative integer |
+| Default | Unset for Git commits; the deterministic archive-tree inventory count otherwise. |
+| Precedence | The release runner supplies it with an archive-tree source identity. |
+| Consumer | Release-seal reports, test reports, four-mode evidence, and offline candidate manifests. |
+| Secret safety | Not a secret. It records only the number of source files in the identity inventory. |
+| Stability | Repository release-evidence internal; not an application setting. |
+| Source owners | `scripts/source-identity.cjs` |
+
+<a id="pulse-fake-fastly-capture"></a>
+
+### `PULSE_FAKE_FASTLY_CAPTURE`
+
+Tells the fake Fastly CLI where to write its captured invocation.
+
+| Property | Contract |
+|---|---|
+| Value | File path |
+| Default | Unset. |
+| Precedence | Used only by the fake Fastly CLI fixture when present. |
+| Consumer | Fastly CLI surface test fixture. |
+| Secret safety | Not a secret. The file records test arguments and paths. |
+| Stability | Fixture-only; not a public tooling setting. |
+| Source owners | `wasm/test/provider/assert-fastly-cli-gate-surface.cjs` |
+
+<a id="pulse-fake-viceroy-capture"></a>
+
+### `PULSE_FAKE_VICEROY_CAPTURE`
+
+Tells the fake Viceroy launcher where to write its captured invocation.
+
+| Property | Contract |
+|---|---|
+| Value | File path |
+| Default | Unset. |
+| Precedence | Used only by the fake direct-Viceroy fixture when present. |
+| Consumer | Fastly local-engine surface test fixture. |
+| Secret safety | Not a secret. The file records test arguments and paths. |
+| Stability | Fixture-only; not a public tooling setting. |
+| Source owners | `wasm/test/provider/assert-fastly-cli-gate-surface.cjs` |
+
+<a id="pulse-es256-reproduction-root"></a>
+
+### `PULSE_ES256_REPRODUCTION_ROOT`
+
+Adds an independent source-identical raw guest artifact and Rust metadata comparison to G5.
+
+| Property | Contract |
+|---|---|
+| Value | Directory path |
+| Default | Unset; the G5 seal still performs its required local maintainer reconstruction. |
+| Precedence | The `--reproduction-root` G5 option wins, then `PULSE_ES256_REPRODUCTION_ROOT`. |
+| Consumer | Optional independent clean-container output comparison in the ES256 G5 seal. |
+| Secret safety | Not a secret. The directory must contain only the public verifier source and build output. |
+| Stability | Contributor/test-only proof reproduction control. |
+| Source owners | `wasm/test/jwt/assert-jwt-es256-final-seal.cjs` |
+
+<a id="pulse-es256-reproduction-archive"></a>
+
+### `PULSE_ES256_REPRODUCTION_ARCHIVE`
+
+Records the byte size and hash of the independently supplied ES256 reproduction archive.
+
+| Property | Contract |
+|---|---|
+| Value | File path |
+| Default | Unset; no external archive identity is recorded. |
+| Precedence | The `--reproduction-archive` G5 option wins, then `PULSE_ES256_REPRODUCTION_ARCHIVE`. |
+| Consumer | Optional independent clean-container archive identity in the ES256 G5 seal. |
+| Secret safety | Not a secret. The archive must contain only the public verifier source and build output. |
+| Stability | Contributor/test-only proof reproduction control. |
+| Source owners | `wasm/test/jwt/assert-jwt-es256-final-seal.cjs` |
+
+<a id="pulse-rust-cargo"></a>
+
+### `PULSE_RUST_CARGO`
+
+Selects the Cargo executable used to reproduce the sealed first-party Rust guest proof.
+
+| Property | Contract |
+|---|---|
+| Value | Absolute or relative executable path |
+| Default | No explicit path; discover `cargo` on `PATH`. |
+| Precedence | `PULSE_RUST_CARGO` overrides `PATH` discovery in the guest-link proof harnesses. |
+| Consumer | Phase A guest-link Rust fixture compilation and toolchain recording. |
+| Secret safety | Not a secret. Do not point it at an untrusted executable. |
+| Stability | Contributor/test-only proof reproduction control. |
+| Source owners | `wasm/test/guest-link/assert-scalar-link-control.cjs`, `wasm/test/guest-link/assert-memory-matrix.cjs`, `wasm/test/guest-link/assert-final-artifact-reality.cjs` |
+
+<a id="pulse-rustc"></a>
+
+### `PULSE_RUSTC`
+
+Selects the Rust compiler used to reproduce the sealed first-party Rust guest proof.
+
+| Property | Contract |
+|---|---|
+| Value | Absolute or relative executable path |
+| Default | No explicit path; discover `rustc` on `PATH`. |
+| Precedence | `PULSE_RUSTC` overrides `PATH` discovery in the guest-link proof harnesses. |
+| Consumer | Phase A guest-link Rust fixture compilation and toolchain recording. |
+| Secret safety | Not a secret. Do not point it at an untrusted executable. |
+| Stability | Contributor/test-only proof reproduction control. |
+| Source owners | `wasm/test/guest-link/assert-scalar-link-control.cjs`, `wasm/test/guest-link/assert-memory-matrix.cjs`, `wasm/test/guest-link/assert-final-artifact-reality.cjs` |
+
+## Standard process variables
+
+Pulse also observes normal operating-system inputs such as `PATH` while locating external tools. Standard process variables are not renamed as Pulse configuration and are outside this catalog.

package/docs/reference/handler-authoring.md

@@ -0,0 +1,264 @@
+# Managed handler TypeScript and JavaScript
+
+This is the canonical language reference for managed Pulse handlers. It defines
+the shared TypeScript/JavaScript authoring shape, the subset that can lower to
+Native, and the extensions available only under an explicitly selected
+JavaScript target.
+
+The authoritative four-mode support table is
+[Provider and target compatibility](./compatibility-matrix.md). Target
+selection never silently rewrites the application or falls back to another
+target.
+
+## One source model
+
+Pulse accepts `.ts`, `.mts`, `.js`, and `.mjs` project modules through the
+reachable project graph. TypeScript annotations, interfaces, type-only imports,
+generic arguments, and `as const`-style authoring metadata do not become
+runtime capabilities. JavaScript and TypeScript use the same managed handler,
+Router, context, effect, and result contract.
+
+Portable handler code should stay inside the subset the Native plan can encode:
+
+- scalar, array, and object literals, including supported literal spreads;
+- simple local declarations and assignments;
+- property and element reads;
+- template strings;
+- arithmetic, comparison, equality, boolean, bitwise, and nullish operators;
+- prefix unary operators, updates, and conditional expressions;
+- `if`/`else`, blocks, expression statements, and explicit returns;
+- static calls to the documented `ctx`, Router, and supported package-root
+  surfaces.
+
+The compiler, not the file extension, decides Native eligibility. A `.js` file
+can be Native-eligible, and a `.ts` file can cross the Native boundary.
+
+## Native language boundary
+
+Native lowering requires source that resolves to the bounded canonical plan.
+The current Native subset rejects or records a boundary for:
+
+- `for`, `for...of`, `for...in`, `while`, and `do...while` loops;
+- `switch`, `try`/`catch`/`finally`, and authored `throw`;
+- classes, constructors, `new`, `this`, generators, and optional chaining;
+- nested function or closure execution in a managed handler;
+- general destructuring declarations, except the recognized static result
+  binding produced by `await ctx.parallel({ ... })`;
+- dynamic imports, CommonJS `require`, runtime module discovery, and dynamic
+  calls the compiler cannot resolve;
+- recursion, top-level mutable runtime state, or capture of module-evaluation
+  values;
+- arbitrary Promise construction or library awaits;
+- ambient authority such as global `fetch`, timers, process/environment,
+  filesystem, sockets, randomness, or provider SDKs.
+
+An explicitly selected JavaScript application may keep ordinary
+provider-compatible JavaScript packages, Promise construction, and library
+awaits. Those forms are recorded as Native eligibility boundaries. They do not
+permit ambient host authority, do not become Pulse effects, and cannot be used
+inside `ctx.parallel`.
+
+## Why handlers are async-shaped
+
+Every managed handler returns a promise-shaped result in TypeScript:
+
+```ts
+type Handler = (
+  ctx: PulseContext
+) => Promise<PulseResult | PulseFetchResponse>
+```
+
+JavaScript targets execute that shape through a provider-owned request
+lifecycle. Native targets treat the wrapper as authoring notation. The compiler
+turns trusted host operations into explicit effects and the following code into
+continuations, then removes `async` and `await` from generated Native code.
+
+This gives one familiar source shape without pretending that Native contains a
+general JavaScript Promise runtime.
+
+Static event handlers use the same managed notation with a non-HTTP context and
+void completion:
+
+```ts
+app.on('device.reading', { schema: 'events.DeviceReading' }, async (ctx) => {
+  const mode = await ctx.config.get('MODE')
+  ctx.state.set('mode', mode)
+  void ctx.event.payload
+})
+```
+
+`ctx.event.type` is the exact registered type and `ctx.event.payload` is the
+immutable schema-validated payload, or `null` for a no-payload registration.
+Event handlers cannot access request metadata, route parameters, response
+builders, Router transfer, middleware, or a response result. Eligible handlers
+lower through the conditional provider-neutral Native event entry and reuse the
+existing effect/continuation state machine. This does not activate a provider
+event transport or target-support claim.
+
+See [Static events and outbound emission](../guides/events.md) for the complete
+frame, queue, harness, target, Native-extension, and explicit no-call contract.
+
+## Trusted awaits
+
+The portable awaited forms are Pulse-owned operations:
+
+- `ctx.req.text()` and `ctx.req.json(schemaId?)`;
+- `ctx.fetch(url, init)` and its `.text()` or `.json(schemaId?)` projections;
+- `ctx.config.get(name)` and `ctx.secret.get(name)`;
+- `ctx.kv(namespace).get(key)` and `.put(key, value)`;
+- `ctx.parallel({ ... })`;
+- request-bound effects from supported package roots, such as
+  `grip.broadcast(ctx, message)`.
+
+Response construction, request metadata, route parameters, `ctx.state`, and
+`ctx.log` are synchronous. Awaiting a proven synchronous value is redundant and
+may produce a warning.
+
+The canonical synchronous context forms include `ctx.req.method`,
+`ctx.req.url`, `ctx.req.path`, immutable `ctx.req.headers`, the
+case-insensitive `ctx.req.header(name)` helper, `ctx.param(name)` inside matched
+route handlers, `ctx.state.get` / `ctx.state.set`, response builders, and fixed
+`ctx.log` methods. The [context API map](../../API.md#context-at-a-glance)
+separates HTTP-only, route-only, event-only, and shared execution authority.
+
+Arbitrary library awaits and Promise construction are JavaScript-only. They are
+not Pulse effects, do not enter `ctx.parallel`, and make the same source
+ineligible for Native compilation.
+
+`ctx.emit(type, { schema, payload? })` is a recognized Pulse effect for direct
+JavaScript execution and Native lowering. It requires literal event/schema
+identities and direct await, or placement as a fresh member of an awaited
+`ctx.parallel` group. Native emits the same canonical effect descriptor and
+resumes its ordinary continuation after host acceptance; no Promise runtime,
+JavaScript import, Asyncify transform, or fallback is added. Node has a bounded
+reference ingress/acceptance realization for direct parity evidence. It is not
+a public bus or a delivery guarantee, and other provider eligibility remains
+separate.
+
+## `ctx.parallel` is an explicit portable group
+
+Use `ctx.parallel` when operations must begin together across all four modes:
+
+```ts
+const { profile, flags } = await ctx.parallel({
+  profile: ctx.fetch(profileUrl).json<Profile>(),
+  flags: ctx.fetch(flagsUrl).json<Flags>(),
+})
+```
+
+The accepted shape is deliberately narrow:
+
+- one nonempty inline object literal;
+- fixed, unique, non-index string keys;
+- no spreads, computed keys, getters, methods, arrays, or dynamic records;
+- one fresh execution-owned `PulseParallelEffect` per value;
+- no arbitrary promises, reused roots, cross-request effects, or nested groups.
+
+Property order owns effect identity, trace order, deterministic primary-failure
+selection, and keyed result reconstruction. Every member settles before the
+continuation resumes.
+
+Separate awaits retain normal sequential behavior on JavaScript. Native may
+also group adjacent independent trusted effects internally, but that
+optimization is not a portable concurrency promise. Use `ctx.parallel` when
+concurrency is application behavior.
+
+## Static application boundaries
+
+Beyond the expression and statement subset above, Native eligibility requires
+an application graph the compiler can prove:
+
+- a statically reachable project entry and module graph;
+- async-shaped managed handlers with a simple `ctx` identifier;
+- static Router construction, route methods, paths, mounts, and handler
+  references;
+- root-only static `Pulse.on` registrations with literal event/schema identities,
+  one exact owner per event type, and void event-handler completion;
+- literal schema and response-case identities;
+- supported `ctx` call shapes and bounded object options;
+- supported package-root imports with the package's documented static
+  arguments;
+- no dynamic import, generator handler, nested async handler, provider SDK, or
+  ambient authority.
+
+JavaScript targets preserve a broader ordinary package and async surface, but
+the provider's runtime and packaging environment still decide whether a
+dependency is compatible. A Node-only dependency does not become Fastly
+compatible merely because both targets are JavaScript.
+
+## Router topology and terminal transfer
+
+`Router` is a compile-time authoring marker. The v2 surface supports static
+`get`, `head`, and `post` routes; exact, named-parameter, and trailing-wildcard
+paths; global and path-scoped middleware; acyclic mounts; fallthrough; and
+error middleware.
+
+`next()` is terminal:
+
+```ts
+app.use(async (ctx, next) => {
+  if (!authorized(ctx)) return ctx.text('unauthorized', { status: 401 })
+  return next()
+})
+```
+
+The current handler never resumes after `return next()` or
+`return next(error)`. Assigning, awaiting, or calling `next()` without returning
+it is rejected. Pulse does not provide onion-style post-`next()` work.
+
+## JSON and body ownership
+
+With the default `pulse.strict: true`, request, fetch, and response JSON
+boundaries use static schema or response-case IDs declared by the project.
+Setting `pulse.strict: false` deliberately enables bounded generic JSON and
+records that parser requirement in the plan.
+
+Structured bodies may be read as bounded text or JSON. Opaque bodies remain
+host-owned. Return an opaque fetch or package result directly; do not inspect
+its bytes, iterate chunks, transform it, or retain it beyond the request.
+
+## Supported imports and extension boundaries
+
+Canonical source may import:
+
+- `@pulse-compute/pulse` and `@pulse-compute/runtime`;
+- supported package roots such as `@pulse-compute/assets` and
+  `@pulse-compute/grip`;
+- ordinary JavaScript dependencies when the explicitly selected JavaScript
+  target can package and execute them.
+
+Native lowering recognizes only the core contract and synchronized trusted
+package-root lowerers. Compatibility `/pulsewasm` subpaths are not the preferred
+authoring surface. Arbitrary third-party lowerer loading and provider SDK
+imports are unsupported.
+
+See [Pulse-aware package authoring](../contributing/pulse-aware-packages.md),
+[Compatibility imports and migration](../guides/compatibility-imports.md), and
+the target cells in the [compatibility matrix](./compatibility-matrix.md).
+
+## How Native ineligibility is reported
+
+For a Native-selected profile, `doctor`, `inspect`, `compile`, and `build`
+report source-located eligibility diagnostics and stop before target
+realization. Common classes include unsupported awaits, ambient authority,
+dynamic topology, unresolved package ownership, and unsupported package call
+shapes.
+
+For an explicitly selected JavaScript profile, inspection records Native
+eligibility separately from JavaScript target support. A JavaScript build may
+proceed when its own project, package, capability, and provider requirements
+are eligible. A Native failure never triggers automatic JavaScript fallback,
+and Pulse does not choose Native after an explicit JavaScript selection.
+
+Use:
+
+```bash
+pulse doctor --json
+pulse inspect --json
+```
+
+Then follow the stable diagnostic and its source location. See
+[Troubleshooting](../guides/troubleshooting.md), [Diagnostics and
+remediation](./diagnostics.md), [Static Router authoring](../guides/routing.md),
+[Effects and continuations](../concepts/effects-and-continuations.md), and
+[Structured and opaque bodies](../concepts/bodies.md).