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

package/docs/packages/crypto.md

@@ -0,0 +1,71 @@
+# `@pulse-compute/crypto`
+
+`@pulse-compute/crypto` provides bounded, provider-neutral cryptographic
+verification for Pulse applications and first-party capability packages.
+
+```bash
+npm install @pulse-compute/crypto@1.0.0-beta.1
+```
+
+## Verification surface
+
+Applications may import the package root and request MAC or signature
+verification. Inputs are explicit bytes; the package does not perform ambient
+string encoding or expose backend objects.
+
+```ts
+import { crypto } from '@pulse-compute/crypto'
+
+const result = await crypto.mac.verify({
+  algorithm: 'HS256',
+  key: {
+    type: 'hmac-key-bytes',
+    bytes: secretBytes,
+  },
+  data: messageBytes,
+  tag: authenticatorBytes,
+})
+```
+
+The result is one frozen status:
+
+- `valid`
+- `invalid-authenticator`
+- `invalid-key`
+- `invalid-input`
+- `realization-failure`
+
+HS256 accepts bounded key, data, and authenticator bytes. ES256 accepts an
+exact P-256 public point, the original signing input bytes, and an exact JOSE
+signature. Neither algorithm retries another realization after failure.
+
+## Profiles and realization
+
+Profiles declare the exact algorithms a project may use:
+
+```ts
+export default {
+  prod: {
+    crypto: ['HS256', 'ES256'],
+  },
+}
+```
+
+Planning proves that reachable demand is covered by the selected profile and
+target capability. JavaScript providers use their selected Web Crypto
+realization. Native compilation links the selected first-party guest
+realization. Target probing and automatic fallback are prohibited.
+
+## Boundary
+
+The package root is the supported application contract. Native integration,
+guest provenance, and realization records are toolchain-owned surfaces. JWT
+owns compact-JWS parsing, key selection, and claims semantics; this package
+owns normalized cryptographic verification.
+
+## Related material
+
+- [JWT verification](./jwt.md)
+- [Project configuration](../reference/project-config.md)
+- [Provider and target compatibility](../reference/compatibility-matrix.md)
+- [Package-owned lowering](../concepts/package-owned-lowering.md)

package/docs/packages/entities.md

@@ -0,0 +1,129 @@
+# `@pulse-compute/entities`
+
+`@pulse-compute/entities` provides bounded, statically declared, schema-bound
+operations through the first-party JSON-RPC adapter.
+
+```bash
+npm install @pulse-compute/entities@1.0.0-beta.1
+```
+
+## Declare an entity router
+
+```ts
+import { EntityRouter, jsonRpc } from '@pulse-compute/entities'
+
+const rpc = new EntityRouter({
+  adapter: jsonRpc({ namedParamsOnly: true }),
+})
+
+rpc.on('customer.lookup', {
+  input: 'tools.CustomerLookupInput',
+  output: 'tools.CustomerLookupOutput',
+  metadata: {
+    title: 'Look up customer',
+    description: 'Returns one customer from the governed directory backend.',
+  },
+}, lookupCustomer)
+
+export default function handler(ctx: unknown) {
+  return rpc.handle(ctx as never)
+}
+```
+
+`input` and `output` are literal schema IDs declared by the selected Pulse
+project, or `null`. A `null` input passes `undefined` to the handler; a `null`
+output requires `undefined` and becomes JSON `null`. Metadata must be bounded,
+static JSON. Handlers must be resolvable named references and may use the same
+governed `ctx` effects as ordinary managed handlers.
+
+The compiler recognizes a deliberately narrow static form: one module-level
+router, an inline first-party adapter declaration, standalone module-level
+registrations, and one terminal request binding. It rejects aliases, dynamic
+names, computed schema IDs, conditional registration, chained registration,
+and multiple request-body owners.
+
+## JSON-RPC behavior
+
+The first adapter accepts JSON-RPC 2.0 request objects and named object params.
+It does not accept batches or positional params. It selects an entity before
+schema decoding, invokes the handler once, validates output, and emits stable
+JSON-RPC failures without application exception details.
+
+| Input | HTTP result | JSON-RPC result |
+|---|---:|---|
+| Valid request with `id` | `200` | `result` or a stable `error` with the same `id` |
+| Notification without `id` | `204` | Empty body after synchronous completion |
+| Unknown method | `200` | `-32601` / `Method not found` |
+| Invalid params or schema input | `200` | `-32602` / `Invalid params` |
+| Handler or output failure | `200` | `-32603` / `Internal error` |
+| Malformed JSON | `200` | `-32700` / `Parse error` |
+
+`acceptEmptyObjectForNoInput: true` additionally permits `{}` for an operation
+whose input is `null`. `namedParamsOnly` can only be `true` in this contract.
+
+## Inspect and release evidence
+
+Inspect the static declaration and run the focused candidate proof from this
+source checkout:
+
+```bash
+pulse inspect
+node wasm/scripts/run-wasm-tests.cjs --task entities-orchestration-demo --no-report
+```
+
+`pulse inspect` reports the entity plan, deterministic catalog, schema linkage,
+redacted handler effects, and target evidence. A successful build writes:
+
+- `entities-catalog.json`: protocol-neutral discovery metadata;
+- `entities-inspection.json`: declarations, handler identities/effects, and
+  eligibility/measured-execution evidence.
+
+Both artifacts are static and checkout-independent. They intentionally omit
+request/runtime values, request IDs, raw payloads, resolved secrets, and
+provider objects. Consumers such as a tools facade should project discovery
+from the catalog and invoke a governed adapter boundary; they should not gain a
+direct handler or runtime-registry API.
+
+## Target status
+
+| Mode | Beta evidence | Important boundary |
+|---|---|---|
+| Node JavaScript | Measured execution | Package JavaScript runtime |
+| Fastly JavaScript | Measured with Viceroy 0.20.1 | Provider JavaScript package/runtime |
+| Node Native | Measured execution | Package-owned Native source |
+| Fastly Native | Measured with Viceroy 0.20.1 | Explicit provider-owned adapter; not the ordinary project build path |
+
+Native remains `provider-dependent`, and every target keeps automatic fallback
+disabled. The complete matrix is in [Provider and target compatibility](../reference/compatibility-matrix.md).
+
+## Diagnostics
+
+These codes are package-owned entries in the synchronized Beta diagnostic
+catalog.
+
+| Code or family | Meaning | Remediation |
+|---|---|---|
+| `PULSE_ENTITIES_ADAPTER_STATIC_REQUIRED` | Router/adapter declaration is not the supported static form. | Construct one module-level `const` router with inline `adapter: jsonRpc(...)`. |
+| `PULSE_ENTITIES_ADAPTER_UNSUPPORTED` | The adapter is not the first-party JSON-RPC adapter. | Use `jsonRpc()`; third-party adapter authoring is not open. |
+| `PULSE_ENTITIES_ADAPTER_OPTIONS_INVALID` | Adapter options are unknown or dynamic. | Use literal `namedParamsOnly: true` and an optional literal boolean `acceptEmptyObjectForNoInput`. |
+| `PULSE_ENTITIES_DISCRIMINATOR_STATIC_REQUIRED`, `..._INVALID`, `..._DUPLICATE` | An operation name is dynamic, malformed, or repeated. | Use one unique bounded string literal per router. |
+| `PULSE_ENTITIES_SCHEMA_MISSING`, `..._ID_INVALID` | `input`/`output` is absent or not a declared literal schema ID/`null`. | Declare both fields and synchronize the project schema registry. |
+| `PULSE_ENTITIES_HANDLER_UNRESOLVED`, `..._INVALID` | The handler is not a resolvable named function. | Pass a named module-level function reference. |
+| `PULSE_ENTITIES_REGISTRATION_UNSUPPORTED` | Registration is conditional, nested, chained, or otherwise dynamic. | Use standalone module-level `rpc.on(...)` statements. |
+| `PULSE_ENTITIES_BINDING_UNSUPPORTED` | The request binding is not one terminal `return rpc.handle(ctx)`. | Return the call directly from the request handler. |
+| `PULSE_ENTITIES_BODY_CONSUMER_CONFLICT` | Another owner also consumes the request body. | Give the entity adapter exclusive ownership of the request body. |
+| `PULSE_ENTITIES_METADATA_INVALID`, `PULSE_ENTITIES_LIMIT_INVALID`, `PULSE_ENTITIES_LIMIT_EXCEEDED` | Static metadata or bounded data exceeds the contract. | Reduce or correct the declaration; limits are package-owned and not app-configurable. |
+| `PULSE_ENTITIES_TARGET_INELIGIBLE` | The chosen provider/target cannot realize the declaration. | Select an evidenced mode or supply the separately governed provider integration. Never rely on fallback. |
+
+Malformed envelopes can additionally produce bounded scanner codes such as
+`PULSE_ENTITIES_JSON_MALFORMED`, `PULSE_ENTITIES_JSON_TOO_DEEP`,
+`PULSE_ENTITIES_ENVELOPE_TOO_LARGE`, and
+`PULSE_ENTITIES_PAYLOAD_TOO_LARGE`. Clients receive only the stable JSON-RPC
+mapping, while provider observability records a redacted failure category.
+
+## Related material
+
+- [Entity engine, adapters, and facades](../concepts/entities-and-adapters.md)
+- [Canonical API](../../API.md#entities-api)
+- [Entities lowering maintainer reference](../contributing/entities-lowering.md)
+- [Executable Entities tools example](../../examples/10-entities-tools/)

package/docs/packages/grip.md

@@ -0,0 +1,82 @@
+# `@pulse-compute/grip`
+
+`@pulse-compute/grip` provides stateless HTTP framing for an external GRIP/Fanout gateway. Pulse does not own WebSocket objects, connection registries, backpressure, reconnect behavior, or connection-length continuations. The gateway owns the open connection; Pulse classifies requests, returns subscription or handoff instructions, and emits outbound broadcast effects.
+
+## Install
+
+```bash
+npm install @pulse-compute/grip@1.0.0-beta.1
+```
+
+## Package-root API
+
+```ts
+import { Router } from '@pulse-compute/runtime'
+import { grip } from '@pulse-compute/grip'
+
+const app = new Router()
+
+app.get('/events/:accountId', async (ctx) => {
+  const channel = `account:${ctx.param('accountId')}`
+
+  if (grip.isWebSocket(ctx.req)) {
+    return grip.handoff({ channel })
+  }
+
+  return grip.subscribe(
+    new Response(null, { status: 200 }),
+    { channel, mode: 'stream' },
+  )
+})
+
+app.post('/publish/:accountId', async (ctx) => {
+  const data = await ctx.req.json()
+  await grip.broadcast(ctx, {
+    channel: `account:${ctx.param('accountId')}`,
+    data,
+  })
+  return ctx.json({ accepted: true }, { status: 202 })
+})
+
+export default app
+```
+
+The root API separates pure HTTP behavior from provider interaction:
+
+- `grip.isWebSocket(request)` — pure request classification;
+- `grip.subscribe(response, options)` — pure response decoration with GRIP subscription headers;
+- `grip.handoff(options)` — pure HTTP response construction for gateway handoff;
+- `grip.broadcast(ctx, message)` — request-bound outbound effect, directly awaitable and valid inside `ctx.parallel({ ... })`.
+
+## Realization boundary
+
+The canonical root has bounded JavaScript and Native framing realization.
+Configured Node and Fastly providers realize `grip.broadcast`; a missing publish
+capability fails with a stable capability-required diagnostic rather than
+falling back or taking ownership of a connection. Native options and messages
+must use supported static shapes, and unsupported expressions fail at the exact
+source boundary.
+
+The publish/control endpoint, named backend, authentication, and optional
+trusted-proxy verification are provider-owned configuration. Public gateway
+URLs and ingress routes are separate. Configuration stores only secret
+references; values remain inside the shared secret/redaction boundary.
+
+Cross-target conformance covers framing, cancellation, bounds,
+acknowledgements, redaction, and deterministic Node/Fastly provider artifacts.
+This bounded realization is included in both generally available JavaScript
+targets.
+
+## Compatibility Native facade
+
+`@pulse-compute/grip/pulsewasm` remains a compatibility surface for the Native
+`channel`, `hold`, and `publish` contract. It is not the recommended API for
+new applications and is not evidence that Pulse owns WebSocket lifecycle. See
+[Compatibility imports and migration](../guides/compatibility-imports.md).
+
+## Related documentation
+
+- [GRIP and Fanout guide](../guides/grip.md)
+- [Contracts and providers](../concepts/contracts-and-providers.md)
+- [Package-owned lowering](../concepts/package-owned-lowering.md)
+- [Diagnostics](../reference/diagnostics.md)

package/docs/packages/implementation-packages.md

@@ -0,0 +1,113 @@
+# Implementation packages
+
+<!-- Generated by wasm/scripts/sync-reference-docs.cjs. Edit the source catalog, not this file. -->
+
+These packages are synchronized parts of the release set for compiler, provider, runtime, and package-lowering maintainers. They are not application-author SDKs.
+
+The package status and supported entry-point lists below come from the synchronized Pulse 1.0.0-beta.1 release policy.
+
+## `@pulse-compute/wasm-build-support`
+
+Pulse release-set and compiler maintainers.
+
+- **Install directly:** No for application projects; it is installed transitively where required.
+- **Stability:** Internal release-set interface; exported modules may change with compiler implementation needs.
+
+### Supported entry points
+
+- `None for application authors.`
+
+## `@pulse-compute/wasm-compiler`
+
+Pulse compiler and release maintainers.
+
+- **Install directly:** No for application projects; use the pulse CLI.
+- **Stability:** Internal compiler interface; no application-author compatibility guarantee.
+- **Canonical replacement:** `@pulse-compute/cli`
+
+### Supported entry points
+
+- `None for application authors.`
+
+## `@pulse-compute/wasm-guest-link`
+
+Pulse compiler, release, and first-party guest-unit maintainers.
+
+- **Install directly:** No for application projects; it is an internal synchronized compiler dependency.
+- **Stability:** Internal first-party prebuilt guest-link interface synchronized with the compiler; no application-author or third-party guest compatibility guarantee.
+
+### Supported entry points
+
+- `None for application authors.`
+
+## `@pulse-compute/wasm-contracts`
+
+Pulse compiler, runtime, provider, and package-lowering maintainers.
+
+- **Install directly:** Provider toolchain authors may install it for the versioned bootstrap contract; application projects receive it transitively.
+- **Stability:** The provider toolchain contract is versioned and supported for the Beta; other protocol and proof interfaces remain internal.
+
+### Supported entry points
+
+- `@pulse-compute/wasm-contracts/provider/toolchain`
+
+## `@pulse-compute/wasm-host-runtime`
+
+Pulse host-runtime and provider maintainers.
+
+- **Install directly:** No for application projects; it is installed transitively.
+- **Stability:** Internal compiler/runtime interface synchronized with this release set.
+
+### Supported entry points
+
+- `None for application authors.`
+
+## `@pulse-compute/wasm-library-kit`
+
+Pulse package-lowering and compiler maintainers.
+
+- **Install directly:** No for application projects; it is installed transitively.
+- **Stability:** Internal package-lowering interface synchronized with this release set.
+
+### Supported entry points
+
+- `None for application authors.`
+
+## `@pulse-compute/provider-node`
+
+Pulse canonical Node provider and compiler maintainers.
+
+- **Install directly:** No for application projects; select provider: node through the CLI.
+- **Stability:** The listed built-in toolchain entry is synchronized with the Beta bootstrap contract; other canonical Node provider interfaces remain internal.
+- **Canonical replacement:** `provider: 'node' through @pulse-compute/cli`
+
+### Supported entry points
+
+- `@pulse-compute/provider-node/toolchain`
+
+## `@pulse-compute/wasm-runtime-core-as`
+
+Pulse AssemblyScript runtime-core and compiler maintainers.
+
+- **Install directly:** No for application projects; it is installed transitively.
+- **Stability:** Internal code-generation interface synchronized with this release set.
+
+### Supported entry points
+
+- `None for application authors.`
+
+## `@pulse-compute/wasm-schema-json`
+
+Pulse schema compiler and runtime maintainers.
+
+- **Install directly:** No for application projects; declare schemas in the selected .pulse/config.ts profile.
+- **Stability:** Internal schema compiler interface synchronized with this release set.
+- **Canonical replacement:** `schemas in .pulse/config.ts through the Pulse project workflow`
+
+### Supported entry points
+
+- `None for application authors.`
+
+## Support boundary
+
+Only the entry points explicitly listed above carry the stated release promise. Exported implementation subpaths are not promoted into application-author APIs merely because npm can resolve them.

package/docs/packages/jwt.md

@@ -0,0 +1,55 @@
+# `@pulse-compute/jwt`
+
+`@pulse-compute/jwt` provides bounded, provider-neutral JWT verification for
+Pulse handlers.
+
+```bash
+npm install @pulse-compute/jwt@1.0.0-beta.1
+```
+
+## Verify a bearer token
+
+```ts
+import { jwt } from '@pulse-compute/jwt'
+
+const verified = await jwt.verify(
+  ctx,
+  jwt.bearer(ctx.req),
+  {
+    algorithms: ['HS256'],
+    key: { type: 'secret', binding: 'JWT_SECRET' },
+    issuer: 'https://issuer.example',
+    audience: 'pulse-api',
+  },
+)
+```
+
+The provider resolves request-owned secret material and passes bounded bytes to
+`@pulse-compute/crypto`. JWT authenticates the compact JWS before exposing
+claims, captures one wall-clock instant after authenticity, evaluates
+registered claims, and then applies an optional runtime schema. Results are
+detached and deeply frozen.
+
+## Algorithms and keys
+
+The Beta supports HS256 and ES256 verification. ES256 accepts inline public
+P-256 JWKs or static JWKS values with at most 16 entries. Key selection is
+deterministic and fails closed for duplicate, missing, ambiguous, or unknown
+identities.
+
+RS256, EdDSA, signing, remote discovery, custom crypto providers, and automatic
+fallback are not part of this release.
+
+## Boundary
+
+JWT verifies identity claims; it does not authorize application or host
+behavior. The package root is the supported application contract. Provider,
+compiler, and Native lowering exports are first-party integration surfaces and
+are not application APIs.
+
+## Related material
+
+- [Crypto verification](./crypto.md)
+- [Project configuration](../reference/project-config.md)
+- [Provider and target compatibility](../reference/compatibility-matrix.md)
+- [Package-owned lowering](../concepts/package-owned-lowering.md)

package/docs/packages/provider-fastly.md

@@ -0,0 +1,217 @@
+# `@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.1
+```
+
+## 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, `pulse_host`, or
+WASI dependency.
+
+### 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)