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

package/docs/reference/cli.md

@@ -0,0 +1,457 @@
+# CLI reference
+
+<!-- Generated by wasm/scripts/sync-reference-docs.cjs. Edit the source catalog, not this file. -->
+
+The `pulse` CLI in `@pulse-compute/cli@1.0.0-beta.2` is the supported project workflow. One command specification generates this page, installed help, and the shipped Bash, Zsh, and Fish completion scripts, so a public command or option cannot drift between those surfaces.
+
+## Meta invocations
+
+- `pulse --help | pulse -h | pulse help` — Print public help.
+- `pulse --version | pulse -v | pulse version` — Print the installed CLI package version.
+- `pulse completion <bash|zsh|fish>` — Print a shell completion script generated from the public command specification.
+
+## Global options
+
+| Option | Behavior |
+|---|---|
+| `--help, -h` | Print public CLI help and exit. |
+| `--json` | Emit machine-readable JSON. pulse dev emits one JSON event per line. |
+| `--dry-run, --plan` | Resolve and report the command plan without executing it. |
+
+## Shell completion
+
+Completion output is generated from the same public command and option specification as help and this reference. Tooling can consume the generated [machine-readable command specification](./cli-spec.json).
+
+### `bash`
+
+```bash
+source <(pulse completion bash)
+```
+
+The package also ships `completions/pulse.bash`.
+
+### `zsh`
+
+```bash
+source <(pulse completion zsh)
+```
+
+The package also ships `completions/_pulse`.
+
+### `fish`
+
+```bash
+pulse completion fish | source
+```
+
+The package also ships `completions/pulse.fish`.
+
+## `pulse init`
+
+Create a conventional .pulse workspace with an async Pulse application and dedicated test harness.
+
+Syntax:
+
+```text
+pulse init [directory] [--name <package-name>] [--force]
+```
+
+### Positionals
+
+- `directory` — Target directory. Defaults to the current directory.
+
+### Options
+
+| Option | Behavior |
+|---|---|
+| `--force` | Allow generated files to replace entries in a non-empty target directory. |
+| `--name <package-name>` | Set the generated npm package name. |
+
+### Examples
+
+```bash
+pulse init ./my-pulse-app
+pulse init ./edge-app --name @example/edge-app
+```
+
+
+### Related diagnostics
+
+- [`PULSE_INIT_NOT_EMPTY`](diagnostics.md#pulse-init-not-empty) — Project initialization would write into a non-empty directory without explicit force.
+- [`PULSE_INIT_FILE_EXISTS`](diagnostics.md#pulse-init-file-exists) — Project initialization would replace an existing file that is not safe to overwrite.
+- [`PULSE_PROVIDER_UNSUPPORTED`](diagnostics.md#pulse-provider-unsupported) — The selected provider value is not a supported shorthand or package selection.
+
+
+### Output
+
+- Human output lists generated files and next steps.
+- With --json, emits one initialization result object.
+
+### Side effects
+
+- Creates .pulse/config.ts, an async Pulse application, a dedicated test harness, package scripts, and documentation.
+- Does not install dependencies or run npm, pnpm, or any network operation.
+
+### Exit behavior
+
+0 on success; 2 for invalid usage, provider selection, or unsafe overwrite conditions.
+
+## `pulse doctor`
+
+Audit project shape, compilation, schemas, provider bindings, output safety, and required tools.
+
+Syntax:
+
+```text
+pulse doctor [directory] [--profile <name>] [--strict]
+```
+
+### Positionals
+
+- `directory` — Project discovery start. Defaults to the current directory.
+
+### Options
+
+| Option | Behavior |
+|---|---|
+| `--strict` | Treat doctor warnings as failed checks. |
+| `--profile <profile>` | Select a project profile. Precedence: --profile, PULSE_PROFILE, pulse.defaultProfile. |
+
+### Examples
+
+```bash
+pulse doctor ./my-pulse-app
+pulse doctor ./edge-app --strict --json
+```
+
+
+### Related diagnostics
+
+- [`PULSE_CONFIG_NOT_FOUND`](diagnostics.md#pulse-config-not-found) — Project discovery did not find an explicit Pulse configuration file.
+- [`PULSE_PROJECT_COMPILE_FAILED`](diagnostics.md#pulse-project-compile-failed) — Whole-project compilation failed and contains one or more nested diagnostics.
+- [`PULSE_NODE_VERSION_UNSUPPORTED`](diagnostics.md#pulse-node-version-unsupported) — The active Node.js version is outside the supported release range.
+- [`PULSE_CANONICAL_NATIVE_COMPILE_FAILED`](diagnostics.md#pulse-canonical-native-compile-failed) — The provider-neutral native plan could not be compiled into Pulse-owned WebAssembly.
+
+
+### Output
+
+- Human output prints every check.
+- With --json, emits one completed audit object including failed and warning checks.
+
+### Side effects
+
+- Reads and compiles the project.
+- Does not write the build output.
+
+### Exit behavior
+
+0 when the audit passes; 1 when a completed audit contains failed checks; 2–5 only when the audit command itself cannot be completed.
+
+## `pulse inspect`
+
+Report canonical compiler, schema, effect, continuation, capability, provider, and build-mode details.
+
+Supported signatures:
+
+```text
+pulse inspect [directory] [--profile <name>]
+pulse inspect --artifact <file.json>
+```
+
+### Positionals
+
+- `directory` — Project discovery start. Defaults to the current directory.
+
+### Options
+
+| Option | Behavior |
+|---|---|
+| `--profile <profile>` | Select a project profile. Precedence: --profile, PULSE_PROFILE, pulse.defaultProfile. |
+| `--artifact <file.json>` | Inspect an existing JSON build or compiler artifact instead of a project. |
+
+### Examples
+
+```bash
+pulse inspect ./my-pulse-app --json
+pulse inspect --artifact ./dist/pulse-build.json
+```
+
+
+### Related diagnostics
+
+- [`PULSE_CONFIG_NOT_FOUND`](diagnostics.md#pulse-config-not-found) — Project discovery did not find an explicit Pulse configuration file.
+- [`PULSE_PROJECT_COMPILE_FAILED`](diagnostics.md#pulse-project-compile-failed) — Whole-project compilation failed and contains one or more nested diagnostics.
+- [`PULSE_CANONICAL_COMPILE_FAILED`](diagnostics.md#pulse-canonical-compile-failed) — The handler uses a source form outside the canonical Beta authoring subset.
+
+
+### Output
+
+- Human output prints a compact project/compiler summary.
+- With --json, emits one inspection or artifact object.
+
+### Side effects
+
+- Compiles and validates the project in memory.
+- Does not write the build output.
+
+### Exit behavior
+
+0 on success; 2–5 according to the emitted stable diagnostic.
+
+## `pulse test`
+
+Run configured cases through the selected provider local-conformance runtime.
+
+Syntax:
+
+```text
+pulse test [directory] [--profile <name>] [--case <name>]
+```
+
+### Positionals
+
+- `directory` — Project discovery start. Defaults to the current directory.
+
+### Options
+
+| Option | Behavior |
+|---|---|
+| `--profile <profile>` | Select a project profile. Precedence: --profile, PULSE_PROFILE, pulse.defaultProfile. |
+| `--case <name>` | Run one named project test case. |
+
+### Examples
+
+```bash
+pulse test ./my-pulse-app
+pulse test ./my-pulse-app --case smoke --json
+```
+
+
+### Related diagnostics
+
+- [`PULSE_TEST_PROVIDER_REQUIRED`](diagnostics.md#pulse-test-provider-required) — Project tests require an executable provider.
+- [`PULSE_PROVIDER_CAPABILITY_MISSING`](diagnostics.md#pulse-provider-capability-missing) — The selected provider lacks a binding required by the compiled application.
+- [`PULSE_SCHEMA_DECODE`](diagnostics.md#pulse-schema-decode) — JSON input did not satisfy the explicitly declared schema and content-type policy.
+
+
+### Output
+
+- Human output uses TAP-like case lines and a summary.
+- With --json, emits one test-run object; expected stable errors remain inside their case results.
+
+### Side effects
+
+- Compiles the project and executes configured deterministic or live fixtures.
+- Does not write the build output.
+
+### Exit behavior
+
+0 when all selected cases pass; 1 when the completed test run has failed cases; 2–5 when setup, compilation, runtime, or toolchain execution fails before a normal result.
+
+## `pulse dev`
+
+Start the foreground local server with the selected provider conformance runtime.
+
+Syntax:
+
+```text
+pulse dev [directory] [--profile <name>] [--host <host>] [--port <port>] [--watch|--no-watch] [--once]
+```
+
+### Positionals
+
+- `directory` — Project discovery start. Defaults to the current directory.
+
+### Options
+
+| Option | Behavior |
+|---|---|
+| `--once` | Close the development server after the first completed request. |
+| `--watch, --no-watch` | Enable or disable entry and schema dependency watching. Watching is enabled by default. |
+| `--profile <profile>` | Select a project profile. Precedence: --profile, PULSE_PROFILE, pulse.defaultProfile. |
+| `--host <host>` | Override the development listen host. |
+| `--port <port>` | Override the development listen port. Use 0 to request an ephemeral port. |
+
+### Examples
+
+```bash
+pulse dev ./my-pulse-app
+pulse dev ./my-pulse-app --port 0 --once --json
+```
+
+
+### Related diagnostics
+
+- [`PULSE_DEV_PROVIDER_UNSUPPORTED`](diagnostics.md#pulse-dev-provider-unsupported) — The development server requires an executable provider.
+- [`PULSE_REQUEST_BODY_TOO_LARGE`](diagnostics.md#pulse-request-body-too-large) — An incoming development request exceeded dev.maxBodyBytes.
+- [`PULSE_FETCH_NETWORK`](diagnostics.md#pulse-fetch-network) — An outbound fetch failed because the origin or network was unavailable.
+
+
+### Output
+
+- Human output reports the ready URL and reload or error messages.
+- With --json, stdout is newline-delimited JSON events: compiled, ready, reloaded, request, compile-error, and request-error. It is not one enclosing JSON document.
+
+### Side effects
+
+- Binds a foreground HTTP listener.
+- Watches the entry and schema dependency graph by default.
+- Configuration-file changes require restarting the command.
+
+### Exit behavior
+
+0 after a normal server close; 2–5 when setup, compilation, provider, runtime, or toolchain initialization fails.
+
+## `pulse compile`
+
+Compile the canonical project into provider-neutral Pulse-owned WebAssembly.
+
+Syntax:
+
+```text
+pulse compile [directory] [--profile <name>] [--out <dir>] [--clean|--no-clean] [--experimental-native-size]
+```
+
+### Positionals
+
+- `directory` — Project discovery start. Defaults to the current directory.
+
+### Options
+
+| Option | Behavior |
+|---|---|
+| `--clean, --no-clean` | Remove or preserve the selected output directory before writing artifacts. Cleaning is enabled by default. |
+| `--experimental-native-size` | Experimentally optimize Native Wasm for size. JavaScript build targets reject this flag. |
+| `--profile <profile>` | Select a project profile. Precedence: --profile, PULSE_PROFILE, pulse.defaultProfile. |
+| `--out <dir>` | Override the project-relative artifact output directory. |
+
+### Examples
+
+```bash
+pulse compile ./my-pulse-app
+pulse compile ./edge-app --out ./dist --json
+pulse compile ./edge-app --experimental-native-size
+```
+
+
+### Related diagnostics
+
+- [`PULSE_BUILD_OUT_UNSAFE`](diagnostics.md#pulse-build-out-unsafe) — The resolved build output can escape or alias outside the project root.
+- [`PULSE_CANONICAL_NATIVE_PLAN_FAILED`](diagnostics.md#pulse-canonical-native-plan-failed) — The canonical handler could not be represented by the provider-neutral native execution-plan contract.
+- [`PULSE_CANONICAL_NATIVE_COMPILE_FAILED`](diagnostics.md#pulse-canonical-native-compile-failed) — The provider-neutral native plan could not be compiled into Pulse-owned WebAssembly.
+
+
+### Output
+
+- Writes pulse-compile.json, the canonical program, native plan, generated AssemblyScript, compact Wasm, WAT, and native manifest.
+- The output is provider-neutral and does not package a deployment provider runtime.
+- Experimental size builds record the exact non-default Native compiler optimization settings.
+- With --json, emits one compile result object containing exact artifact paths and native metadata.
+
+### Side effects
+
+- Cleans the output directory by default.
+- Invokes the lockfile-pinned AssemblyScript compiler.
+- Refuses absolute, parent-traversal, and symbolic-link traversal outside the project root.
+
+### Exit behavior
+
+0 on success; 2–5 according to the emitted stable diagnostic.
+
+## `pulse build`
+
+Compile the canonical project and realize the deployment provider selected by the active project profile.
+
+Syntax:
+
+```text
+pulse build [directory] [--profile <name>] [--out <dir>] [--clean|--no-clean] [--experimental-native-size]
+```
+
+### Positionals
+
+- `directory` — Project discovery start. Defaults to the current directory.
+
+### Options
+
+| Option | Behavior |
+|---|---|
+| `--clean, --no-clean` | Remove or preserve the selected output directory before writing artifacts. Cleaning is enabled by default. |
+| `--experimental-native-size` | Experimentally optimize Native Wasm for size. JavaScript build targets reject this flag. |
+| `--profile <profile>` | Select a project profile. Precedence: --profile, PULSE_PROFILE, pulse.defaultProfile. |
+| `--out <dir>` | Override the project-relative artifact output directory. |
+
+### Examples
+
+```bash
+pulse build ./my-pulse-app
+pulse build ./edge-app --out ./dist --json
+pulse build ./edge-app --experimental-native-size
+```
+
+
+### Related diagnostics
+
+- [`PULSE_BUILD_OUT_UNSAFE`](diagnostics.md#pulse-build-out-unsafe) — The resolved build output can escape or alias outside the project root.
+- [`PULSE_BUILD_PROVIDER_REQUIRED`](diagnostics.md#pulse-build-provider-required) — pulse build requires a configured deployment provider; provider-neutral output belongs to pulse compile.
+- [`PULSE_EXPERIMENTAL_NATIVE_SIZE_UNSUPPORTED`](diagnostics.md#pulse-experimental-native-size-unsupported) — The experimental Native size optimizer cannot be used for a JavaScript build target.
+- [`PULSE_CANONICAL_NATIVE_COMPILE_FAILED`](diagnostics.md#pulse-canonical-native-compile-failed) — The provider-neutral native plan could not be compiled into Pulse-owned WebAssembly.
+
+
+### Output
+
+- Writes pulse-build.json, the provider-neutral native module, and the configured provider realization.
+- Fastly builds write generated AssemblyScript and direct-host-ABI native Wasm at bin/main.wasm; no JavaScript runtime image is packaged.
+- Experimental size builds record the exact non-default Native compiler optimization settings in portable, provider, and build metadata.
+- With --json, emits one build result object containing exact portable and provider artifact paths.
+
+### Side effects
+
+- Cleans the output directory by default.
+- Invokes the native compiler and configured provider realization.
+- Refuses absolute, parent-traversal, and symbolic-link traversal outside the project root.
+
+### Exit behavior
+
+0 on success; 2–5 according to the emitted stable diagnostic.
+
+## Configuration discovery and command precedence
+
+Project commands start discovery from their optional positional `[directory]` or the current directory, then search upward for the single configuration entrypoint:
+
+```text
+.pulse/config.ts
+```
+
+Profile selection follows `--profile`, `PULSE_PROFILE`, then `pulse.defaultProfile`. Command-line `--out`, `--host`, `--port`, and watch flags are invocation-local controls. Entry, provider, and target selection belong to `.pulse/config.ts`: `pulse compile` remains provider-neutral and `pulse build` realizes the selected provider. See [Project configuration](project-config.md).
+
+## JSON and stream contracts
+
+For completed commands, `--json` emits one JSON object followed by a newline. `pulse dev --json` is deliberately different: stdout is newline-delimited JSON, with one event object per line. Event names are `compiled`, `ready`, `reloaded`, `request`, `compile-error`, and `request-error`; consumers must not wait for one enclosing JSON document.
+
+Raw configured secret values are not included in project JSON, diagnostics, or runtime error detail fields.
+
+## Provider restrictions and build products
+
+| Provider | inspect/build | test/dev | Build result |
+|---|---:|---:|---|
+| `node` | Yes | Yes | Portable Pulse Wasm plus the configured Node-native realization and `pulse-build.json`. |
+| `fastly` | Yes | Yes, through local conformance | Portable Pulse Wasm plus generated AssemblyScript and compact direct-host-ABI `bin/main.wasm`. |
+| `none` | Compile only | No | `pulse compile` emits portable Pulse Wasm; `pulse build` rejects the missing deployment provider. |
+
+Build output is cleaned by default. `--no-clean` preserves the directory, but output safety still rejects absolute, parent-traversal, and symbolic-link traversal outside the project root.
+
+## Exit classes
+
+| Exit | Meaning |
+|---:|---|
+| `0` | Command completed successfully. |
+| `1` | Completed audit/test failure where documented, or an unexpected uncatalogued internal failure. |
+| `2` | Usage, project configuration, provider selection, or output-safety error. |
+| `3` | Canonical/schema/package-lowering/provider-binding failure. |
+| `4` | Request, test, runtime, fetch, or continuation failure. |
+| `5` | External toolchain or Fastly local-execution failure. |
+
+`pulse doctor` completes with exit `1` when its audit contains failed checks. `pulse test` completes with exit `1` when a normal test run has failed cases. Setup failures use their diagnostic exit class.
+
+Failed commands emit stable codes, categories, summaries, remediation, exit classes, and a versioned documentation URL. See [Diagnostics and remediation](diagnostics.md).

package/docs/reference/compatibility-matrix.md

@@ -0,0 +1,169 @@
+# Provider and target compatibility
+
+This page is the single compatibility matrix for the Pulse Beta.
+It records the tested source forms, provider bindings, target realizations, and
+deployment boundary for the four explicit execution modes. The same managed
+handler and Router contract applies in every column; target selection changes
+the realization, not the application model.
+
+For the exact TypeScript and JavaScript source subset behind these rows, see
+[Managed handler TypeScript and JavaScript](./handler-authoring.md).
+
+## Reading the matrix
+
+- `Yes` means the form is part of the current contract and has focused
+  cross-target evidence.
+- `JS only` means the form may remain in an explicitly selected JavaScript
+  application but makes Native lowering ineligible.
+- `No` means the form is outside the managed Pulse contract even when the
+  underlying JavaScript engine or provider offers it.
+- A provider resource name, such as `Config Store`, names the realization
+  selected by that provider/target cell. It does not expose the provider SDK to
+  application code.
+
+Pulse never changes columns automatically. A Native eligibility failure stops
+the Native build; it does not authorize automatic JavaScript fallback.
+
+## Source-form compatibility
+
+| Source form | Node JS | Fastly JS | Node Native | Fastly Native | Notes |
+|---|---:|---:|---:|---:|---|
+| Async-shaped managed handler | Yes | Yes | Yes | Yes | Native erases the authoring wrapper; it does not link Promise, JSPI, or Asyncify semantics. |
+| Static `Router` topology and terminal `next()` | Yes | Yes | Yes | Yes | Covers static `get`, `head`, `post`, `put`, `patch`, `delete`, middleware, mounts, parameters, trailing wildcard, fallthrough, and the error lane. |
+| Root-only `Pulse.on` and non-HTTP event context | Yes | No | Yes | No | Node owns the bounded reference ingress. Fastly source remains inspectable but execution/build eligibility fails closed. |
+| Awaited one-way `ctx.emit` acceptance | Yes | No | Yes | No | Static schema-bound frames only; no delivery, loopback, public bus, call surface, or target fallback. |
+| Sequential awaits of trusted Pulse effects | Yes | Yes | Yes | Yes | JavaScript preserves source order. Native lowers effects and continuations and may group adjacent independent effects without changing results. |
+| `await ctx.parallel({ fixed: effect })` | Yes | Yes | Yes | Yes | Requires a nonempty inline object with fixed non-index keys and fresh request-owned Pulse effects. |
+| Request metadata, route parameters, request state, logging, and response construction | Yes | Yes | Yes | Yes | These are synchronous managed surfaces; awaiting a proven synchronous value is redundant and may warn. |
+| Schema-bound request, fetch, and response JSON | Yes | Yes | Yes | Yes | Schema and response-case IDs are literal project declarations. |
+| Generic bounded JSON with `pulse.strict: false` | Yes | Yes | Yes | Yes | The plan records the generic host parser. Strict mode requires a declared schema. |
+| Direct opaque response pass-through | Yes | Yes | Yes | Yes | Returnable, but not inspectable, iterable, buffered, transformed, or retained in userland. |
+| Supported package-root Assets and GRIP calls | Yes | Yes | Yes | Yes | JavaScript runs the package implementation. Native accepts the package's synchronized, bounded lowerable subset. |
+| Ordinary target-compatible JavaScript package API | Yes | Yes | No | No | JavaScript packaging must include a provider-compatible dependency. Native requires a trusted package-owned lowerer. |
+| Arbitrary Promise construction or library await | JS only | JS only | No | No | Never valid inside `ctx.parallel`; Native reports the first eligibility boundary and never falls back. |
+| Ambient `fetch`, timers, environment/process access, filesystem, sockets, or provider SDK | No | No | No | No | Use `ctx` effects and configured provider bindings. |
+| Userland body streams, chunk transforms, or background work | No | No | No | No | Structured reads are bounded, opaque bodies stay host-owned, and work ends with the request. |
+
+## Provider and target realization
+
+The application-facing source form stays the same across these cells. Text in a
+cell names the provider-owned binding or artifact that realizes it.
+
+| Capability | Node JS | Fastly JS | Node Native | Fastly Native | Notes |
+|---|---:|---:|---:|---:|---|
+| Canonical handler and Router execution | Yes | Yes | Yes | Yes | Shared handler, Router, context, effect, and result contracts. |
+| Request and structured responses | Yes | Yes | Yes | Yes | Provider adapters preserve the canonical request/response model. |
+| Single, sequential, and keyed-parallel fetch | Yes | Yes | Yes | Yes | Fetch is a `ctx` effect; no ambient fetch authority is implied. |
+| Explicit JSON schemas and bounded generic JSON | Yes | Yes | Yes | Yes | Schema policy is project-owned and target-neutral. |
+| Config reads | Test/dev binding | Config Store | Test/dev binding | Config Store | Exact names are resolved from the selected profile; no ambient fallback. |
+| Secret reads | Test/dev binding | Secret Store | Test/dev binding | Secret Store | Secret values remain provider-owned and are redacted from diagnostics and logs. |
+| KV `get` and `put` | In-memory binding | KV Store | In-memory binding | KV Store | Namespaces are explicit profile bindings. |
+| Opaque pass-through | Yes | Yes | Yes | Yes | Bodies remain host-owned in all four modes. |
+| GRIP framing and configured broadcast | Yes | Yes | Yes | Yes | The package-root contract owns the portable operation shape. |
+| `ctx.log` and redaction | Yes | Yes | Yes | Yes | Provider output format may differ; the level and redaction contract does not. |
+| Reference event ingress and `ctx.emit` acceptance | Bounded Node adapter | No | Bounded Node adapter | No | Direct parity evidence only: FIFO ingress, exact-frame acceptance, no loopback, delivery promise, public bus, call surface, or automatic fallback. |
+| Local execution evidence | Node lifecycle | Provider emulation | Canonical host | Controlled ABI host | Local proof is not production provider activation. |
+| Deployment candidate | Source package | Source package plus downstream runtime Wasm | Node build | `bin/main.wasm` | A candidate records the selected target and does not contain an automatic fallback artifact. |
+| Production deployment and activation | Not applicable | Human-operated | Not applicable | Human-operated | Fastly reality, deployment, and activation remain explicit external gates. |
+
+## Entities Beta package
+
+This table records measured behavior for the implemented
+`@pulse-compute/entities` package. Release membership does not erase the
+separate ordinary-lifecycle and Fastly Native integration boundaries.
+
+| Entities capability | Node JS | Fastly JS | Node Native | Fastly Native | Notes |
+|---|---:|---:|---:|---:|---|
+| Static `EntityRouter` declarations | Yes | Yes | Yes | Yes | One literal router, first-party adapter, static registrations, named handlers, and one terminal binding. |
+| Bounded JSON-RPC request execution | Measured | Measured | Measured | Measured | Fastly cells execute generated artifacts with Viceroy 0.20.1. |
+| Declared input/output schema codecs | Measured | Measured | Measured | Measured | Selection precedes decode; only the selected schemas are available. |
+| Managed handler effects | Measured | Measured | Measured | Measured | The shared corpus includes schema work, fetch, and stable negative cases. |
+| Deterministic catalog and inspection | Yes | Yes | Yes | Yes | Catalog and redacted inspection are package-owned build artifacts. |
+| Ordinary project build integration | Yes | Yes | No | No | JavaScript source packaging emits the catalog; Native evidence uses package source outside the ordinary build adoption path. |
+| Ordinary project `test`/`dev` loading | Blocked | Blocked | Not applicable | Not applicable | The shared JavaScript loader requests an unexported physical entry instead of the public package root. |
+| Automatic target fallback | No | No | No | No | Eligibility, measured execution, and release assignment remain separate claims. |
+
+## JWT and crypto Beta packages
+
+This table records the sealed Phase D and E behavior of the synchronized
+`1.0.0-beta.2` JWT/crypto packages. Validation does not itself authorize npm
+publication.
+
+| Candidate capability | Node JS | Fastly JS | Node Native | Fastly Native | Notes |
+|---|---:|---:|---:|---:|---|
+| HS256 MAC verification | `runtime-builtin` | `runtime-builtin` | `guest-source:pulse-hmac-as` | `guest-source:pulse-hmac-as` | All cells consume one bounded corpus and return the same closed result categories. |
+| ES256 signature verification | `runtime-builtin` | `runtime-builtin` | `guest-linked:pulse-es256-rustcrypto-p256` | `guest-linked:pulse-es256-rustcrypto-p256` | The 38-case matrix runs both JavaScript cells and both Native optimization artifacts per provider with exact failure parity. |
+| Exact realization selection | Yes | Yes | Yes | Yes | Profile replacement is whole-value replacement; there is no array or object merging. |
+| Disabled fallback | Yes | Yes | Yes | Yes | Missing capability, unavailable pins, and realization failures stop without choosing another backend or target. |
+| Secret-safe realization reporting | Yes | Yes | Yes | Yes | Reports identify algorithms and realizations but never key, message, or authenticator bytes. |
+| Prebuilt `guest-linked` unit required | No | No | ES256 only | ES256 only | Native HS256 remains first-party AssemblyScript in the primary module; Native ES256 uses the exact audited RustCrypto guest. |
+| JWT verification | HS256, ES256 | HS256, ES256 | HS256, ES256 | HS256, ES256 | RS256 and EdDSA remain unavailable; no failure changes algorithms, realizations, targets, or providers. |
+| JWT authenticity before claims | Yes | Yes | Yes | Yes | Invalid authenticity exposes no claims and stops before clock, registered-claim, or schema authority. |
+| Exact final-artifact execution | Package runtime | Compute artifact | Primary Native module | `bin/main.wasm` | Native cells execute the package-owned guest sources; JavaScript cells execute the exact selected runtime builtin. |
+
+## Evidence and authority
+
+Each row above is grounded in one or more of these current contracts or focused
+proofs:
+
+- **Managed surface and target support:** `HANDLER_SURFACE_DEFINITIONS`,
+  `HANDLER_AUTHORING_MODES`, and `HANDLER_AUTHORING_POLICY_VERSION` in
+  `wasm/packages/contracts/src/handler/surface-contract.js`.
+- **Public TypeScript shape:** `packages/runtime/src/index.d.ts` owns the
+  Promise-shaped handler, terminal `RouterNext`, context, effect, body, and
+  result types.
+- **Async, trusted await, ambient authority, and `ctx.parallel` boundaries:**
+  `wasm/test/lowering/assert-canonical-api-lowering.cjs`.
+- **Native source realization without Promise or Asyncify:**
+  `wasm/test/compiled/assert-canonical-native-wasm.cjs`.
+- **Four-mode behavior and target integrity:**
+  `wasm/test/contracts/assert-four-mode-conformance.cjs` and
+  `wasm/test/support/four-mode-conformance.cjs`.
+- **JavaScript effect order and explicit parallel behavior:**
+  `wasm/test/contracts/assert-javascript-effect-adapter.cjs`.
+- **Router and context parity:**
+  `wasm/test/contracts/assert-node-router-context-parity.cjs`.
+- **Schemas, generic JSON, and body ownership:**
+  `wasm/test/contracts/assert-schema-codecs.cjs`,
+  `wasm/test/contracts/assert-fetch-projections-request-bodies.cjs`, and
+  `wasm/test/runtime/assert-canonical-opaque-passthrough.cjs`.
+- **Config, secrets, KV, exact bindings, and redaction:**
+  `wasm/test/contracts/assert-config-secrets-kv-redaction.cjs`.
+- **Assets and GRIP package-root support:**
+  `wasm/test/compiled/assert-package-root-native.cjs`,
+  `wasm/test/contracts/assert-grip-cross-target-conformance.cjs`, and the
+  package runtime tasks registered in `wasm/test/suite/registry.cjs`.
+- **Provider candidates and external reality boundary:** the Node/Fastly
+  provider tasks in `wasm/test/suite/registry.cjs` and the mandatory Fastly
+  reality gate declared by `release/pulse-release-manifest.json`.
+- **Entities package:** static catalog and inspection proofs in
+  `wasm/test/entities/assert-entities-catalog.cjs` and
+  `wasm/test/entities/assert-entities-inspection.cjs`; orchestration boundaries
+  in `wasm/test/entities/assert-entities-orchestration-demo.cjs`; and the shared
+  four-mode Viceroy corpus in
+  `wasm/test/entities/assert-entities-cross-target.cjs`.
+- **JWT/crypto packages:** the crypto corpus in
+  `packages/crypto/conformance/hs256.json`,
+  `wasm/test/crypto/assert-crypto-cross-target-conformance.cjs`, and
+  `wasm/.test-results/crypto-c4/phase-c-seal.json`; the JWT composition seal in
+  `wasm/.test-results/jwt-d4/jwt-phase-d-seal.json`; and the four-cell,
+  210-execution cross-target seal in
+  `wasm/.test-results/jwt-e4/jwt-phase-e-seal.json`. The Fastly reality tasks
+  execute generated JavaScript and Native provider artifacts locally through
+  `fastly compute serve`; they do not deploy or activate a service.
+  ES256 target alignment is recorded by the six-cell, 228-evaluation matrix in
+  `wasm/.test-results/boundary-h4/es256-six-cell-matrix.json`, including the
+  Fastly JavaScript runtime Wasm under Viceroy.
+
+The focused documentation assertion
+`wasm/test/docs/assert-compatibility-matrix.cjs` keeps the matrix header unique,
+checks the public target order, verifies its evidence paths, and compares the
+documented managed-surface rule with the canonical handler-surface registry.
+
+## Related reference
+
+- [Managed handler TypeScript and JavaScript](./handler-authoring.md)
+- [Beta scope](../preview-scope.md)
+- [Node build and execution](../guides/deploying-node.md)
+- [Fastly deployment candidates](../guides/deploying-fastly.md)
+- [Diagnostics and remediation](./diagnostics.md)