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

package/docs/concepts/effects-and-continuations.md

@@ -0,0 +1,300 @@
+# Effects and continuations
+
+A Pulse handler is written as async-shaped TypeScript. Host operations such as fetch, KV, secrets, and GRIP are awaited in source, but Native targets do not link a JavaScript Promise runtime. The compiler erases the managed async wrapper and trusted Pulse awaits into **effects** and the code that follows into **continuations**. JavaScript targets execute the same source through the live runtime and provider-owned effect adapter.
+
+Application authors do not create or resume continuation objects. They write canonical TypeScript; the compiler and provider runtime own the lifecycle.
+
+## Effect
+
+An effect is an explicit request for host authority. Each effect has an identity, capability, operation, resource, source position, and result shape. Common examples include:
+
+- dispatching an outbound fetch;
+- reading config or a secret;
+- getting or putting a KV value;
+- accepting one outbound event through `ctx.emit`;
+- declaring a GRIP channel;
+- holding or publishing through GRIP.
+
+Pure value construction, branching, property reads, and arithmetic are not effects.
+
+## Continuation
+
+A continuation identifies the compiled work that can proceed after one effect—or one effect group—settles. It carries no application-accessible provider object. The runtime resumes it with a normalized result or failure.
+
+```text
+compiled values
+    │
+    ├── effect request ──► provider/runtime
+    │                         │
+    └── continuation ◄────────┘ normalized result or failure
+```
+
+A continuation is single-use and time-bounded. Expired or duplicate resume attempts fail with stable diagnostics such as [`PULSE_CONTINUATION_EXPIRED`](../reference/diagnostics.md#pulse-continuation-expired) and [`PULSE_CONTINUATION_DOUBLE_RESUME`](../reference/diagnostics.md#pulse-continuation-double-resume).
+
+## Independent effects form a group
+
+The multi-fetch example declares three independent fetch values before consuming any of them:
+
+<!-- pulse-doc-source: examples/03-fetch-composition/src/index.ts -->
+```ts
+import { Pulse } from '@pulse-compute/pulse'
+
+interface User {
+  id: number
+  name: string
+}
+
+interface Stats {
+  score: number
+}
+
+interface Flags {
+  enabled: boolean
+}
+
+const app = new Pulse({ auto: true })
+
+// One structured origin.
+app.get('/user', async (ctx) => {
+  const user = await ctx
+    .fetch('https://users.example.test/users/123')
+    .json<User>()
+  return ctx.json({ found: true, user })
+})
+
+// Multiple origins with explicit sequential awaits.
+app.get('/user-summary', async (ctx) => {
+  const user = await ctx
+    .fetch('https://users.example.test/users/123')
+    .json<User>()
+  const stats = await ctx
+    .fetch('https://stats.example.test/users/123')
+    .json<Stats>()
+  const flags = await ctx
+    .fetch('https://flags.example.test/users/123')
+    .json<Flags>()
+  return ctx.json({
+    id: user.id,
+    name: user.name,
+    score: stats.score,
+    enabled: flags.enabled,
+  })
+})
+
+// Multiple origins with explicit portable concurrency.
+app.get('/user-summary-parallel', async (ctx) => {
+  const { user, stats, flags } = await ctx.parallel({
+    user: ctx.fetch('https://users.example.test/users/123').json<User>(),
+    stats: ctx.fetch('https://stats.example.test/users/123').json<Stats>(),
+    flags: ctx.fetch('https://flags.example.test/users/123').json<Flags>(),
+  })
+  return ctx.json({
+    id: user.id,
+    name: user.name,
+    score: stats.score,
+    enabled: flags.enabled,
+  })
+})
+
+export default app
+```
+<!-- /pulse-doc-source -->
+
+```bash
+pulse inspect examples/03-fetch-composition --json
+```
+
+The compiler can issue those fetches as one effect group because none depends on another result. The continuation becomes eligible only after the group settles.
+
+Grouping provides concurrency without linking a general Promise runtime into Native artifacts. Source declaration order remains deterministic for identities and result binding, but providers may perform independent operations concurrently.
+
+
+## Explicit portable groups with `ctx.parallel`
+
+Native Pulse may discover independent adjacent effects and place them in one group
+for performance. Direct JavaScript execution does not rewrite ordinary `await`
+semantics, so separate awaits remain sequential there. Use `ctx.parallel({ ... })`
+when concurrency is required application behavior across targets:
+
+```ts
+const { profile, flags } = await ctx.parallel({
+  profile: ctx.fetch(profileUrl).json<Profile>(),
+  flags: ctx.fetch(flagsUrl).json<Flags>(),
+})
+```
+
+The first contract accepts a nonempty inline object literal with fixed,
+non-index string keys and Pulse effect expressions as values. Property order owns
+dispatch identity, trace order, deterministic primary-failure selection, and keyed
+result reconstruction. Providers may complete members in any order, but every
+member settles before the continuation resumes.
+
+On JavaScript, all members execute through one execution-owned shared effect adapter.
+On Native, lowering erases `ctx.parallel`, emits the member operations into one
+canonical effect group, and reconstructs the ordinary keyed result object after
+one continuation. Arrays, spreads, computed keys, dynamic records, arbitrary
+promises, reused roots, and nested groups are outside the initial portable shape.
+
+## One-way outbound events
+
+HTTP and event handlers share the direct JavaScript `ctx.emit` effect:
+
+```ts
+await ctx.emit('device.led.set', {
+  schema: 'events.DeviceLedSet',
+  payload: { enabled: true },
+})
+
+await ctx.emit('system.tick', { schema: null })
+```
+
+The event type and schema are static compiler inputs. A non-null schema requires
+`payload`; `schema: null` forbids it. The runtime schema-validates and detaches
+the canonical frame before dispatch, and the effect resolves only when the
+configured host adapter accepts that frame. It returns `undefined`: there is no
+delivery receipt, correlation ID, handler result, retry guarantee, or local
+loopback.
+
+`ctx.emit` may be awaited directly or used as a fresh member of an awaited
+`ctx.parallel` group. It consumes the same execution effect budget, cancellation,
+redaction, and disposal boundary as fetch, config, secret, and KV effects. The
+JavaScript dispatch uses the execution-owned effect adapter. Native lowering
+emits the same canonical `event.emit` descriptor, suspends on the ordinary
+continuation protocol, and resumes after host acceptance; it adds no JavaScript,
+Promise, or Asyncify runtime. The Node provider has a bounded, invocation-scoped
+FIFO reference adapter for direct JavaScript/Native ingress and exact accepted
+frame evidence. Its outbound ledger never loops back into ingress, and its
+success still promises no delivery, persistence, retry, receipt, or public
+event-bus behavior. No other provider realization or automatic fallback is
+claimed.
+
+One-way acceptance is also the recursion boundary. Pulse exposes no
+`ctx.call`, generic request/reply effect, automatic local dispatch, or reserved
+call opcode. A future reflexive mechanism cannot be inferred from `ctx.emit`;
+it requires a separately specified host and lifecycle. See [Static events and
+outbound emission](../guides/events.md).
+
+## Dependencies split continuation stages
+
+When later control flow or a later host operation depends on an earlier result, the compiler creates another continuation stage. For example, inspecting a first response and choosing a second URL is dependent work; it cannot be moved into the first independent group.
+
+The rule is semantic rather than stylistic:
+
+- independent operations may share one group;
+- operations that need prior values start in a later continuation;
+- pure computation between effects stays in the continuation that owns it;
+- returning a final response completes the request lifecycle.
+
+Use `pulse inspect --json` to see the actual grouping rather than inferring it from line spacing.
+
+## Failure behavior
+
+An effect failure is normalized into a stable public error. Examples include:
+
+- [`PULSE_FETCH_TIMEOUT`](../reference/diagnostics.md#pulse-fetch-timeout);
+- [`PULSE_FETCH_NETWORK`](../reference/diagnostics.md#pulse-fetch-network);
+- [`PULSE_PROVIDER_CAPABILITY_UNSUPPORTED`](../reference/diagnostics.md#pulse-provider-capability-unsupported);
+- [`PULSE_FASTLY_BACKEND_REQUIRED`](../reference/diagnostics.md#pulse-fastly-backend-required).
+
+For an independent group, the runtime settles the group and reports the normalized failures through the owning continuation boundary. Userland does not receive partially live provider handles or background tasks that can outlive the request.
+
+## Timeouts have two scopes
+
+A fetch can have an operation timeout through `PulseFetchInit.timeoutMs`. The request runtime also owns a continuation lifetime configured by the execution environment or test case. These are different controls:
+
+- the operation timeout bounds one host operation;
+- the continuation TTL bounds how long compiled execution may remain suspended before resumption is rejected.
+
+Project tests can set `continuationTtlMs` in a case inside the dedicated `tests/pulse.harness.ts` module for deterministic failure coverage.
+
+## Managed async, not arbitrary async
+
+Write managed handlers with `async` and await trusted Pulse effects. On Native targets, the compiler erases that notation into effects and continuations. On JavaScript targets, the live runtime executes the same async-shaped handler normally.
+
+Arbitrary Promise construction, ambient asynchronous APIs, and unrecognized library awaits remain outside Native eligibility. They must not be mistaken for Pulse effects or silently trigger target fallback.
+
+This design keeps:
+
+- effects visible to the compiler;
+- provider capability checks complete before execution;
+- failures and timeouts normalized;
+- request completion bounded;
+- Node and Fastly behavior comparable.
+
+## Inspect and test the lifecycle
+
+A useful workflow is:
+
+```bash
+pulse inspect ./my-app --json
+pulse test ./my-app --json
+```
+
+`inspect` proves compilation, effects, grouping, continuations, and provider lowering without executing application test cases. `test` executes configured cases through the selected provider’s local conformance runtime.
+
+## Related documentation
+
+- [Managed handler TypeScript and JavaScript](../reference/handler-authoring.md)
+- [Provider and target compatibility](../reference/compatibility-matrix.md)
+- [Compilation and lowering](./compilation-and-lowering.md)
+- [Structured and opaque bodies](./bodies.md)
+- [Fetching and composing data](../guides/fetching-and-composition.md)
+- [Project configuration](../reference/project-config.md)
+- [Troubleshooting](../guides/troubleshooting.md)
+
+## Conditional KV
+
+`ctx.kv<T>('name')` exposes `getVersioned(key)`, `insertIfAbsent(key, value)`, and
+`compareAndSwap(key, generation, value)` as direct awaited or keyed parallel
+effects. The Node reference implements the contract for JavaScript and compiled
+Native control flow. Fastly Native implements it through direct KV hostcalls;
+Fastly JavaScript conditional KV remains explicitly incomplete.
+
+The condition and mutation are atomic at one key's authority. A versioned read
+returns a value and an opaque generation from the same observation, which may be
+stale. Generations are strings, not numbers, hashes or application versions.
+Create conflicts when present; CAS conflicts when absent or when its token is
+stale. Equal-byte replacement is still a write and changes its generation.
+Existing unconditional `get` and `put` remain available.
+
+A write returns `stored`, `conflict`, `not-stored` with a bounded reason, or
+`unknown` with a bounded reason. Unknown may have committed. A complete explicit
+provider rejection establishes no write; an exception from a send primitive
+does not. Pulse does not retry, reread-and-rebase, or invent a generation from a
+write acknowledgement. A subsequent missing or stale read cannot resolve an
+ambiguous write by itself.
+
+Admission detaches and freezes the candidate before provider preparation. The
+host's monotonic ten-second deadline starts at admission and is shortened by an
+owning request deadline. Preparation may resolve bindings and stage data but
+cannot send. Entry into the returned provider primitive marks dispatch even if
+it throws synchronously. Timeout before that boundary is `not-stored`; timeout
+or transport loss after it is `unknown`. Cancellation suppresses delivery to an
+inactive execution and records whether dispatch occurred; it promises no rollback.
+
+Exact keys are bounded Unicode scalar strings; generations are bounded visible
+ASCII strings. Values retain the portable KV JSON limits. Conditional storage
+uses a strict UTF-8 JSON envelope with exactly `__pulseKv: 1` and `value`, rejecting
+duplicate members, invalid values, and oversized bodies. The wrapper is not
+recursively unwrapped. Legacy raw JSON requires explicit migration. Keys, tokens,
+and values are omitted or redacted from runtime evidence and managed errors;
+application responses are not silently rewritten.
+
+Node reference instances retain nonreused generation identities for their own
+lifetime. Host code can explicitly reuse one reference across requests and target
+runners; independent instances isolate their state. Deterministic identities,
+clocks, and failure hooks belong to host evidence, not handler authority. This
+local model does not establish durability, global visibility, cross-key
+transactions, or a portable physical-delete/recreate guarantee. Fastly SDK
+limitations cannot redefine this contract or gate other targets.
+
+Fastly Native preserves all 64 generation bits in an opaque string. ADD and
+generation-conditioned overwrite remain distinct operations, including an explicit
+condition for zero bits. The adapter stages the complete envelope before dispatch,
+uses monotonic deadlines and readiness selection before pending waits and body
+reads, and closes acquired bodies. It accepts up to 65,560 wire bytes, including
+wrapper overhead. Provider key restrictions return `invalid-key` without changing
+the key. Pending KV operations have no cancellation hostcall; an expired operation
+is abandoned to invocation teardown and may still commit. Host termination never
+resumes an inactive handler. Local Wasm evidence is separate from K4's deployed
+cross-location acceptance.

package/docs/concepts/entities-and-adapters.md

@@ -0,0 +1,71 @@
+# Entity engine, adapters, and facades
+
+Pulse Entities separates governed operation semantics from the protocol that
+selects an operation and from any facade that presents those operations to an
+external ecosystem.
+
+## The four layers
+
+| Layer | Owns | Does not own |
+|---|---|---|
+| Entity engine | Static operation names, schema declarations, handler identity, governed execution, deterministic catalog | HTTP/JSON-RPC syntax, MCP lifecycle, provider SDKs |
+| JSON-RPC adapter | Bounded envelope parsing, request/notification selection, named params, stable JSON-RPC result/error framing | Handler semantics, schema registry authority, direct provider access |
+| Tools or MCP facade | Catalog projection, external tool naming/annotations, transport-facing invocation policy | Direct handler calls, runtime registry mutation, hidden Pulse authority |
+| Worker/event adapter (future) | A separately specified event/request binding and response/acknowledgement mapping | Changes to entity declarations or handler effect authority |
+
+The entity engine is therefore not a server. `EntityRouter` records a static
+registry and binds it to one governed request. `jsonRpc()` is the only current
+adapter. A facade may read the emitted `entities-catalog.json` and construct a
+request for that adapter, but it cannot enumerate live handler functions or
+call them outside a Pulse request context.
+
+## Why the catalog is protocol-neutral
+
+The catalog contains operation names, schema IDs, static metadata, and target
+eligibility. It excludes handlers, raw requests, request IDs, provider objects,
+secrets, and runtime values. That makes it suitable for build-time discovery
+without making discovery a new ambient runtime authority.
+
+The inspection artifact is richer and maintainer-facing: it adds redacted
+handler-effect summaries and measured target evidence. Neither artifact is a
+mutable service registry.
+
+## Authority flow
+
+1. Project configuration owns declared schemas and provider selection.
+2. The trusted first-party lowerer extracts entity declarations without
+   evaluating application code.
+3. The selected adapter owns bounded protocol decoding and operation selection.
+4. The selected schema codecs decode only the chosen input and encode only the
+   chosen output.
+5. The handler receives the normal request-owned `PulseContext`; every fetch,
+   config, secret, KV, log, or package effect remains governed by that context.
+6. The adapter frames completion. A facade sees only the framed boundary.
+
+No layer may silently choose another target. Native ineligibility fails closed;
+it never authorizes JavaScript fallback.
+
+## MCP/tools boundary
+
+The [Entities tools example](../../examples/10-entities-tools/) demonstrates a
+small facade that projects static metadata and invokes JSON-RPC. It is
+intentionally not a complete MCP implementation. Pulse runtime core does not
+gain SSE, sessions, tasks, resources, prompts, sampling, authorization,
+transport negotiation, or MCP lifecycle state from this candidate.
+
+A complete MCP server could be built outside the entity engine if it preserves
+these rules: static discovery comes from an emitted catalog, invocation crosses
+a governed adapter boundary, external protocol state stays outside runtime
+core, and MCP behavior never becomes a source of provider or schema authority.
+
+## Future adapters
+
+A Worker, queue, scheduled-event, or other event adapter would be a new
+first-party adapter contract. It would define bounded selection and completion
+for that event shape while retaining the same static declaration, schema,
+handler, effect, catalog, and no-fallback rules. The current package does not
+open third-party adapter registration or claim those adapters exist.
+
+See the [Entities package guide](../packages/entities.md) for current behavior
+and [Entities lowering](../contributing/entities-lowering.md) for the trusted
+maintainer boundary.

package/docs/concepts/package-owned-lowering.md

@@ -0,0 +1,175 @@
+# Package-owned lowering
+
+Package-owned lowering lets a synchronized Pulse package extend the canonical compiler with narrow, statically recognized operations while keeping domain rules out of compiler core.
+
+The synchronized `1.0.0-beta.2` release uses this pattern for Assets, GRIP,
+JWT, and Entities.
+It is a **trusted first-party synchronization mechanism**, not a public
+registry that executes arbitrary npm compiler plugins.
+
+## One package API, two execution paths
+
+Application code imports the normal package root:
+
+```ts
+import { assets } from '@pulse-compute/assets'
+import { grip } from '@pulse-compute/grip'
+import { jwt } from '@pulse-compute/jwt'
+```
+
+On the JavaScript target, the actual package TypeScript/JavaScript implementation executes. On Native targets, the compiler recognizes supported package-root symbols and lowers them into canonical package effects. Lowering restrictions remain eligibility and diagnostic rules; they do not require target-specific application source.
+
+Older `/pulsewasm` imports are compatibility-only and are isolated in the
+[migration guide](../guides/compatibility-imports.md).
+
+## Why the package owns the lowerer
+
+A domain package knows details that compiler core should not:
+
+- which root symbols are effects or pure result adapters;
+- which argument shapes are statically representable;
+- which payload versions and diagnostics belong to the domain;
+- which sidecar symbols compiled Wasm requires;
+- which capabilities a provider must implement;
+- which JavaScript behavior is broader than the lowerable Native subset.
+
+## Package anatomy
+
+A lowerable package normally ships:
+
+```text
+package.json                 application exports and discovery pointers
+pulse.package.json           product, target, ownership, and conformance metadata
+src/                         actual JavaScript implementation and portable API
+pulsewasm.manifest.cjs       trusted lowerer and compatibility declaration
+pulsewasm.compiler.cjs       package-specific validation and effect construction
+as/index.as.ts               optional compiled-Wasm sidecar ABI
+README.md                    current product and compatibility boundary
+```
+
+`pulse.package.json` is static metadata. It cannot register or execute compiler code. `pulsewasm.manifest.cjs` identifies the trusted first-party compiler builder. Product metadata and executable compiler authority remain separate.
+
+## Discovery and trust
+
+The canonical project compiler:
+
+1. builds the reachable module graph;
+2. attributes package imports from that graph rather than source substrings;
+3. loads synchronized package product contracts;
+4. selects a trusted package compiler only for a reachable supported Native operation;
+5. invokes it through the exact immutable shared builder envelope;
+6. normalizes its artifact and contributions before compiler orchestration;
+7. combines canonical package effects with core effects and continuations;
+8. validates the complete provider capability envelope.
+
+A package manifest must declare first-party trust and ownership matching the
+package. Dynamic third-party compiler registration is not part of the Beta
+contract.
+
+Caller option bags do not cross this boundary. In particular, provider target
+descriptors, drivers, runtime objects, raw CLI configuration, compiler caches,
+resolved secrets, and arbitrary compiler services are not builder inputs.
+Package builders emit canonical requirements; later compiler/provider
+eligibility checks decide whether the selected target can satisfy them.
+
+## Request-bound package effects
+
+A package effect is created through an explicit `PulseContext`:
+
+```ts
+await grip.broadcast(ctx, {
+  channel: 'events:demo',
+  data: { type: 'message', value: 'hello' },
+})
+```
+
+The shared package bridge returns the same request-owned effect value used by core operations. It therefore supports:
+
+- direct `await`;
+- keyed `ctx.parallel({ ... })`;
+- request cancellation and completion containment;
+- deterministic grouped failure selection;
+- known-secret redaction;
+- generic provider dispatch.
+
+The bridge has a fixed first-party identity catalog. It does not use ambient current-request state, `AsyncLocalStorage`, or mutable global registration.
+
+## Pure package operations
+
+Not every package function is an effect. Pure request classification and response decoration should remain ordinary JavaScript:
+
+```ts
+if (grip.isWebSocket(ctx.req)) {
+  return grip.handoff({ channel: 'events:demo' })
+}
+
+return grip.subscribe(new Response(null), {
+  channel: 'events:demo',
+  mode: 'stream',
+})
+```
+
+Similarly, `assets.respond()` is a pure result adapter. Native lowering may erase that helper around an `assets.lookup()` result without turning response decoration into another provider effect.
+
+## Static call shapes
+
+Native package lowering intentionally accepts less than arbitrary TypeScript. A package may require:
+
+- a known package-root import and symbol;
+- supported direct-await, variable, return, or `ctx.parallel()` placement;
+- fixed object-literal options;
+- statically representable resources or operation selectors;
+- no escaping internal handles;
+- no provider SDK values.
+
+Unsupported shapes make the Native project ineligible with a source-located diagnostic. The same package may still support broader direct JavaScript behavior when the selected JavaScript target and provider contract allow it.
+
+## Provider completion
+
+A package is not complete merely because its compiler emits an effect. Every provider advertised for that operation must:
+
+- declare the capability;
+- map it to a stable operation;
+- validate required bindings;
+- execute it in local conformance;
+- realize it in deployable output when claimed;
+- preserve structured or opaque result ownership.
+
+Assets demonstrates package-root JavaScript execution plus Native package lowering and opaque response ownership. GRIP provides stateless JavaScript framing, bounded broadcast provider realization, and Native/root conformance.
+
+JWT demonstrates a package-owned verification effect whose Native lowering
+composes package-owned JWT logic with crypto-owned realizations. HS256 Native
+compiles the crypto guest source into the primary module; ES256 Native
+contributes one exact prebuilt guest unit through the guest-link boundary.
+JavaScript uses the same package contract with the selected runtime builtin for
+HS256 and ES256. Provider eligibility begins only after the package emits its
+provider-neutral capability and crypto requirements.
+
+A package-selected prebuilt guest is a separate canonical contribution, not a
+filesystem or compiler object. It carries only its version, stable ID,
+package-relative manifest, exact owner/package version, and
+`package-prebuilt` origin. The compiler resolves the synchronized package root
+as a separate selection fact. Guest-link then receives that exact contribution
+through its own invocation contract; `packageRoot`, target descriptors,
+compiler realizations, and option bags are never fields of the contribution.
+
+## Release expectations
+
+A supported package-owned lowerer needs:
+
+- product and trusted-manifest validation;
+- positive and negative static lowering tests;
+- JavaScript runtime tests for the real package implementation;
+- direct-await and keyed-parallel package-effect tests;
+- provider capability and binding tests;
+- packed-package discovery and clean installation;
+- documentation distinguishing canonical roots from compatibility subpaths;
+- explicit evidence classifying every unsupported shape.
+
+See [Pulse-aware package
+authoring](../contributing/pulse-aware-packages.md), [Add a first-party
+package-owned lowerer](../contributing/adding-first-party-lowerer.md), [Managed
+handler TypeScript and JavaScript](../reference/handler-authoring.md),
+[Provider and target compatibility](../reference/compatibility-matrix.md),
+[Contracts and providers](./contracts-and-providers.md), and [Compilation and
+lowering](./compilation-and-lowering.md).

package/docs/concepts/targets-and-hosts.md

@@ -0,0 +1,70 @@
+# Targets and host work
+
+Pulse is centered on one application contract. A host is the explicit
+realization layer for that contract, not an object application code imports or
+branches on. The release distinguishes current execution proof from forward
+host work so architectural direction does not become an accidental support
+claim.
+
+An explicit JavaScript profile can retain resolved static package imports and
+project-relative helpers, including awaited calls into ordinary JavaScript
+dependencies. Pulse checks the canonical application surface and packages its
+original source graph. Native eligibility is reported separately and does not
+block JavaScript execution. Unsupported dynamic module boundaries and missing
+`await` on Pulse effects still fail validation. `pulse compile` continues to
+require Native-compatible source; use `pulse build` for a JavaScript package.
+
+## Current Beta targets
+
+`1.0.0-beta.2` exercises four explicit modes through one conformance corpus:
+
+| Host | Target | Current release status | Build shape |
+|---|---|---|---|
+| Node | Native | Beta candidate | Provider-neutral application Wasm with the Node host runtime. |
+| Node | JavaScript | Beta candidate | Explicit Node JavaScript source package. |
+| Fastly | Native | Beta candidate | Provider-neutral application Wasm plus deployable `bin/main.wasm`. |
+| Fastly | JavaScript | Beta candidate | Explicit Fastly JavaScript package. |
+
+Target selection is part of the active project profile. Pulse does not switch
+targets automatically when source crosses a Native boundary. The
+[compatibility matrix](../reference/compatibility-matrix.md) owns exact
+capability differences, and [Beta scope](../preview-scope.md) owns the release
+claim.
+
+The `none` selector is compile-only: it can inspect and emit canonical Native
+artifacts without claiming an executable host.
+
+## Forward boundary witnesses
+
+Forward hosts are useful because they pressure the contract in different ways.
+They remain outside the Beta execution matrix until they have their own
+adapter, lifecycle, conformance evidence, and package claim.
+
+### ESP32
+
+The [ESP32 reference host](https://github.com/pulsecompute/pulse-esp32-host)
+tests whether the event/effect/continuation model remains useful without a
+JavaScript fallback, abundant memory, or an HTTP-centered lifecycle. It is a
+boundary witness, not a `1.0.0-beta.2` provider or compatibility promise. The
+[architecture vision](../architecture/vision.md#esp32-as-a-boundary-witness)
+describes the intended host-owned interrupt queue and non-reentrant Wasm entry.
+
+### Browser event conformance
+
+The browser is a forward event-conformance target: a future browser host should
+accept the same canonical event frames, keep HTTP and event entries separate,
+preserve invocation-local state, and report outbound frame acceptance through
+the same bounded contract. Pulse does not currently claim a browser runtime,
+provider package, listener, delivery service, or event transport.
+
+This is deliberately narrower than saying “Pulse runs in the browser.” The
+[events guide](../guides/events.md) defines the current Node reference boundary
+and the evidence a new host must supply.
+
+## Where provider details belong
+
+Application docs lead with `ctx`, Router, schemas, and capabilities. Provider
+details belong in project profiles, deployment guides, compatibility tables,
+and package pages where build or runtime behavior actually differs. That keeps
+the common surface readable while leaving each host’s authority and limits
+explicit.

package/docs/contributing/README.md

@@ -0,0 +1,38 @@
+<!-- pulse-doc-meta:start
+owner: docs-platform
+status: active
+last-reviewed: 2026-07-25
+review-by: 2027-01-25
+pulse-doc-meta:end -->
+
+# Contributing documentation
+
+These pages describe changes to the synchronized Pulse repository. They are not application-author extension APIs.
+
+## Choose the extension boundary
+
+- [Pulse-aware package authoring](./pulse-aware-packages.md) — ordinary JavaScript packages, bounded package-root Native lowering, trusted builders, and the separate scoped-provider boundary.
+
+## Package-owned lowering
+
+- [Package lowerer contract reference](./package-lowerer-contract.md) — manifest fields, builder protocol, effect shape, trust rules, and release invariants.
+- [Add a first-party package-owned lowerer](./adding-first-party-lowerer.md) — end-to-end implementation tutorial using the GRIP/assets pattern.
+- [Entities lowering maintainer reference](./entities-lowering.md) — static extraction, schema authority, Native realization, catalog, and seal invariants for the Entities package.
+
+## Providers
+
+- [Add a provider toolchain](./adding-core-provider.md) — descriptor, bindings, runtime, target, namespace bootstrap, diagnostics, docs, and tests.
+
+## Repository context
+
+- [Package support policy](../packages/README.md)
+- [Architecture overview](../architecture/overview.md)
+- [Current architecture contracts](../architecture/current-contracts.md)
+- [Reference overview](../reference/README.md)
+
+The current release executes only trusted first-party lowerer builders. Built-in
+provider shorthand is release-owned, while an exact scoped project provider may
+export the versioned `./toolchain` contract without self-registration or
+dependency scanning. Changes that widen either executable trust boundary
+require an explicit security and compatibility design, not only another
+manifest or package export.