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

package/docs/guides/deploying-node.md

@@ -0,0 +1,143 @@
+# Node build and execution
+
+Pulse exposes Node Native and Node JavaScript as explicit targets over the same
+provider-neutral application contract. This guide ends at a validated Node
+candidate. The Beta does not install a process manager, create
+infrastructure, or publish a managed Node service.
+
+## Configure the Node provider
+
+The hello example is a source-bound Node Native project:
+
+<!-- pulse-doc-source: examples/01-hello-json/.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: 'node',
+    target: 'native',
+    outDir: 'dist',
+    dev: { host: '127.0.0.1', port: 8787 },
+  },
+}))
+```
+<!-- /pulse-doc-source -->
+
+Select JavaScript deliberately by changing only the target:
+
+```ts
+local: {
+  host: 'node',
+  target: 'javascript',
+  outDir: 'dist',
+}
+```
+
+Target choice belongs to the profile. Pulse does not retry a failed Native
+selection as JavaScript.
+
+## Validate the application
+
+Use the normal lifecycle:
+
+```bash
+pulse doctor
+pulse test
+pulse dev
+pulse build
+```
+
+`test` and `dev` execute through the selected Node target's provider-owned local
+lifecycle. They prove the configured application and local inputs; they do not
+create a production process or remote service.
+
+## Node Native candidate
+
+With `target: 'native'`, `pulse build` emits:
+
+```text
+canonical-program.json
+canonical-handler.cjs
+canonical-native-plan.json
+canonical-native.wasm
+pulse-build.json
+```
+
+The Wasm imports the provider-neutral `pulse_host` contract. The build manifest
+records the Node Native target, compiler identity, imports/exports,
+optimization profile, provider requirements, and artifact hashes.
+
+Use `pulse test` or `pulse dev` for the maintained Node host execution path.
+The built Wasm and manifest are host-integration inputs; the Beta
+does not promise a standalone production Native launcher.
+
+## Node JavaScript candidate
+
+With `target: 'javascript'`, `pulse build` emits a deterministic CommonJS
+package containing:
+
+```text
+index.cjs
+package.json
+application/
+pulse-build.json
+pulse-javascript-application-plan.json
+pulse-javascript-source-package.json
+schema-json-registry.json       # when schemas are active
+schema-json-codecs.cjs          # when schemas are active
+```
+
+The package contains the reachable application graph and exact reachable Pulse
+dependencies. It contains no Pulse Native Wasm, AssemblyScript source, Native
+plan, or automatic fallback.
+
+`index.cjs` exports the packaged Pulse application. The maintained local
+execution path is `pulse dev`; embedding the package in a production HTTP
+server requires a separately owned Node host integration. The current
+implementation adapter remains an internal provider surface rather than an
+application compatibility promise.
+
+## Inspect the candidate
+
+```bash
+pulse inspect --artifact ./dist/pulse-build.json --json
+```
+
+Check:
+
+- `configuredTarget` and `providerTarget.target`;
+- `automaticFallback: false` for JavaScript;
+- Native import/export and optimization identity, or JavaScript source-package
+  identity;
+- schema registry and codec identity when active;
+- the project entry and output root;
+- target-support and project-eligibility evidence.
+
+## Deployment-owner boundary
+
+After Pulse produces and validates the candidate, the deployment owner remains
+responsible for:
+
+- selecting the Node process/container host;
+- installing the candidate's exact dependencies;
+- wiring HTTP, signals, health checks, credentials, and resource bindings;
+- enforcing operating-system and network policy;
+- retaining build and deployment provenance;
+- deciding activation and rollback.
+
+Those decisions do not grant application handlers ambient `process.env`,
+filesystem, socket, or provider-object authority. Handler access remains
+through `ctx` and configured bindings.
+
+See [Project lifecycle](./project-lifecycle.md), [Managed handler TypeScript and
+JavaScript](../reference/handler-authoring.md), [Provider and target
+compatibility](../reference/compatibility-matrix.md), [Contracts and
+providers](../concepts/contracts-and-providers.md), and [Release
+acceptance](../maintainers/release-acceptance.md).

package/docs/guides/events.md

@@ -0,0 +1,233 @@
+# Static events and outbound emission
+
+Pulse events are a second, provider-neutral application plane beside HTTP.
+`Pulse.on` declares exact inbound event handlers and `ctx.emit` requests
+one-way outbound host acceptance. Neither surface creates a process-global bus,
+a listener, delivery machinery, or reflexive application routing.
+
+The current executable realization is deliberately narrow: Node JavaScript and
+Node Native provide a bounded invocation-scoped reference adapter for tests and
+direct parity evidence. Fastly fails closed for event ingress or emit, while
+browser and ESP32 hosts remain unclaimed. Target selection never falls back.
+
+## Declare the topology
+
+Event registrations belong only to the resolved `Pulse` application root. The
+type, declaration, and handler are static compiler inputs:
+
+<!-- pulse-doc-source: examples/11-events/src/index.ts -->
+```ts
+import { Pulse } from '@pulse-compute/pulse'
+
+type DeviceReading = Readonly<{
+  deviceId: string
+  temperatureC: number
+}>
+
+const app = new Pulse({ auto: true })
+
+app.get('/health', async (ctx) => ctx.text('ok'))
+
+app.on<DeviceReading>('device.reading', { schema: 'events.DeviceReading' }, async (ctx) => {
+  const reading = ctx.event.payload
+  ctx.log.info('device reading accepted')
+  await ctx.emit('device.reading.accepted', {
+    schema: 'events.DeviceReadingAccepted',
+    payload: { deviceId: reading.deviceId, accepted: true },
+  })
+})
+
+app.on('system.tick', { schema: null }, async (ctx) => {
+  ctx.log.info('system tick accepted')
+  await ctx.emit('system.heartbeat', { schema: null })
+})
+
+export default app
+```
+<!-- /pulse-doc-source -->
+
+Each exact event type has one owner. A schema ID must be a literal dotted ID
+present in the project registry. `schema: null` declares an explicit
+no-payload event. Registrations cannot be hidden in helpers, aliased, mounted on
+a `Router`, or created dynamically.
+
+## Event context
+
+An event handler receives `PulseEventContext<Payload>` and completes with
+`Promise<void>`:
+
+| Available | Deliberately absent |
+|---|---|
+| `ctx.event.type` and immutable `ctx.event.payload` | `ctx.req`, route parameters, and HTTP metadata |
+| execution-local `ctx.state` and synchronous `ctx.log` | response builders or a response result |
+| fetch, config, secret, KV, and `ctx.parallel` | middleware and Router `next()` transfer |
+| one-way `ctx.emit` | provider SDKs, listeners, or transport handles |
+
+Schema selection and payload validation complete before handler entry. The
+payload is detached from host input and immutable. State, effects,
+continuations, cancellation, logging, redaction, completion, and disposal are
+owned by one invocation and do not leak into another event or HTTP request.
+
+## Canonical frame and schema rules
+
+Ingress and outbound acceptance use `pulse.event-frame.v1` internally:
+
+```ts
+type EventFrame =
+  | { version: 'pulse.event-frame.v1'; type: string; schemaId: string; payload: unknown }
+  | { version: 'pulse.event-frame.v1'; type: string; schemaId: null }
+```
+
+The public authoring and harness shapes use `schema`, while emitted artifacts
+and host-runtime frames normalize it to `schemaId`. A schema-bound frame must
+contain `payload`; a no-payload frame must omit it. Unknown fields, accessors,
+sparse arrays, cycles, non-finite numbers, symbols, and non-JSON values fail
+before dispatch.
+
+Default host bounds are:
+
+| Bound | Default |
+|---|---:|
+| Event type | 128 UTF-8 bytes |
+| Schema ID | 256 UTF-8 bytes |
+| Payload | 65,536 UTF-8 JSON bytes |
+| Payload nesting | 32 levels |
+| Payload entries | 4,096 |
+| Static registrations | 256 |
+| Adapter queue depth | 65,536 |
+| Bounded error text | 4,096 UTF-8 bytes |
+
+These are containment limits, not an application-facing tuning API. A provider
+or direct host may impose a stricter bound.
+
+## `ctx.emit` means acceptance, not delivery
+
+`ctx.emit(type, { schema, payload? })` must use literal event and schema
+identities. It may be awaited directly or supplied as a fresh member of an
+awaited `ctx.parallel({ ... })` group. The effect resolves to `undefined` only
+after the execution-owned adapter accepts a detached, schema-validated frame.
+
+Acceptance does not promise:
+
+- delivery, persistence, retry, acknowledgement, or a receipt;
+- a correlation ID or remote handler result;
+- automatic invocation of a matching local `Pulse.on` handler;
+- same-stack reentry or an implicit queue consumer;
+- substitution through HTTP, GRIP, logging, or another target.
+
+The Node reference adapter maintains separate FIFO ingress and exact outbound
+acceptance ledgers. Outbound frames never feed the ingress queue automatically.
+Queue overflow, cancellation, invalid acceptance results, schema failures, and
+effect-budget exhaustion remain bounded invocation failures.
+
+## Harness event cases
+
+`pulse test` uses an explicit discriminant so event input never masquerades as
+an HTTP request:
+
+<!-- pulse-doc-source: examples/11-events/tests/pulse.harness.ts -->
+```ts
+export default { cases: [
+  {
+    name: 'http health remains separate',
+    request: { method: 'GET', path: '/health' },
+    expect: { status: 200, text: 'ok' },
+  },
+  {
+    name: 'schema event emits an accepted frame',
+    kind: 'event',
+    event: {
+      type: 'device.reading',
+      schema: 'events.DeviceReading',
+      payload: { deviceId: 'sensor-7', temperatureC: 21 },
+    },
+    expect: {
+      status: 'completed',
+      emitted: [{
+        type: 'device.reading.accepted',
+        schema: 'events.DeviceReadingAccepted',
+        payload: { deviceId: 'sensor-7', accepted: true },
+      }],
+    },
+  },
+  {
+    name: 'no-payload event emits a no-payload frame',
+    kind: 'event',
+    event: { type: 'system.tick', schema: null },
+    expect: {
+      status: 'completed',
+      emitted: [{ type: 'system.heartbeat', schema: null }],
+    },
+  },
+] }
+```
+<!-- /pulse-doc-source -->
+
+`expect.emitted` is ordered and exact. It verifies host acceptance, not
+transport delivery. `pulse dev` continues to serve the HTTP plane only; there
+is no public event injection command.
+
+## Target eligibility
+
+| Selected target | Ingress and emit status | Meaning |
+|---|---|---|
+| Node JavaScript | Eligible | Live application execution through the bounded Node reference adapter. |
+| Node Native | Eligible | Provider-neutral Native event entry driven through the bounded Node reference adapter. |
+| Fastly JavaScript | Blocked | No Fastly event ingress or emit adapter is claimed. |
+| Fastly Native | Blocked | No Fastly event ingress or emit adapter is claimed. |
+| `none` compile-only | Inspection only | Catalog and Native plan may be produced without execution authority. |
+| Browser or ESP32 | Unclaimed | A future host must define and prove its own adapter and queue ownership. |
+
+For a blocked Fastly project, `inspect` remains available and `doctor`, `build`,
+and `test` report the exact eligibility boundary. Pulse never produces an
+alternate target artifact.
+
+## Inspection, artifacts, and diagnostics
+
+`pulse inspect --json` and `pulse doctor --json` report registrations,
+emission callsites, referenced schemas, `event.ingress`/`event.emit` host
+requirements, command eligibility, and `automaticFallback: false`. Eligible
+builds and compile-only output write deterministic `event-catalog.json` and
+`event-inspection.json` files.
+
+Common public workflow diagnostics include:
+
+- [`PULSE_TEST_EVENT_INVALID`](../reference/diagnostics.md#pulse-test-event-invalid)
+  for a malformed harness frame;
+- [`PULSE_EVENT_TARGET_UNSUPPORTED`](../reference/diagnostics.md#pulse-event-target-unsupported)
+  for a target without the required event plane;
+- [`PULSE_FASTLY_EVENT_INGRESS_UNSUPPORTED`](../reference/diagnostics.md#pulse-fastly-event-ingress-unsupported)
+  and
+  [`PULSE_FASTLY_EVENT_EMIT_UNSUPPORTED`](../reference/diagnostics.md#pulse-fastly-event-emit-unsupported)
+  for the explicit Fastly boundary.
+
+Compiler diagnostics additionally point to the exact dynamic type, unresolved
+schema, hidden or duplicate registration, missing await, invalid payload, HTTP
+surface in an event handler, or event surface in an HTTP handler.
+
+## Native extension
+
+Event-reachable Native artifacts conditionally expose
+`pulse.native-event-abi.v1` through `pulse_event_abi_version()` and
+`pulse_event_start(runtimeId, payloadHandle)`. The host validates the frame and
+schema before module entry. A positive payload handle references an immutable
+host-owned value; `0` means a declared no-payload event.
+
+The extension adds no imports. Event-only artifacts expose the event entry;
+mixed artifacts retain independent HTTP and event entries. HTTP-only source
+adds no event imports, exports, catalog data, code, or byte changes. Native
+event effects reuse the ordinary continuation protocol and add no JavaScript,
+Promise, Asyncify, target probing, or fallback.
+
+## No `call` or reflexive routing
+
+The event contract intentionally exposes no `ctx.call`, `app.call`, generic
+call effect, request/reply bus, correlation protocol, or compiler/runtime
+reservation for one. `ctx.emit` cannot observe or invoke a local handler. Any
+future call mechanism requires a separately specified host, ownership model,
+failure contract, recursion/reentrancy guard, and explicit authorization; it is
+not latent in this candidate.
+
+See the [canonical API](../../API.md), [effects and
+continuations](../concepts/effects-and-continuations.md), [compatibility
+matrix](../reference/compatibility-matrix.md), and [event example](../../examples/11-events/).

package/docs/guides/fastly-capabilities.md

@@ -0,0 +1,153 @@
+# Fastly config, secrets, KV, and backends
+
+User code stays provider-neutral:
+
+<!-- pulse-doc-source: examples/05-fastly-capabilities/src/index.ts -->
+```ts
+import { grip } from '@pulse-compute/grip'
+import { Pulse } from '@pulse-compute/pulse'
+
+interface User {
+  id: number
+  name: string
+}
+
+interface Session {
+  userId: number
+}
+
+const app = new Pulse({ auto: true })
+
+// Config, secret, and a named Fastly backend.
+app.get('/users/7', async (ctx) => {
+  const base = await ctx.config.get('API_BASE')
+  const token = await ctx.secret.get('API_TOKEN')
+  const user = await ctx
+    .fetch('https://api.example.com/users/7', {
+      headers: {
+        authorization: `Bearer ${token}`,
+        accept: 'application/json',
+        'x-api-base': base,
+      },
+    })
+    .json<User>()
+  return ctx.json({ user })
+})
+
+// Named Fastly KV storage.
+app.get('/session', async (ctx) => {
+  const current = await ctx.kv<Session>('sessions').get('session:123')
+  if (current === undefined) {
+    return ctx.json({ error: 'not_found' }, { status: 404 })
+  }
+  await ctx.kv<Session>('sessions').put('session:last', current)
+  return ctx.json({ session: current })
+})
+
+// Request-bound GRIP broadcast through the supported package root.
+app.post('/publish', async (ctx) => {
+  const acknowledgement = await grip.broadcast(ctx, {
+    channel: 'events:demo',
+    event: 'pulse.message',
+    id: 'message-1',
+    data: { message: 'hello from Pulse' },
+  })
+  return ctx.json(
+    { accepted: acknowledgement.accepted },
+    { status: 202 },
+  )
+})
+
+export default app
+```
+<!-- /pulse-doc-source -->
+
+Fastly bindings belong in project configuration:
+
+<!-- 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 same example maps its logical `sessions` store and its GRIP publish endpoint
+inside the provider-owned Fastly configuration boundary:
+[`examples/05-fastly-capabilities`](../../examples/05-fastly-capabilities/).
+
+Dynamic backends are disabled by default. Map every known origin to a named backend or opt in deliberately.
+
+Secret values are never included raw in trace output, errors, snapshots, or CLI project JSON.
+
+For `target: 'native'`, `pulse build` compiles the generated Compute package to
+direct-host-ABI `bin/main.wasm`. For `target: 'javascript'`, it emits the
+deterministic source/deployment closure consumed by the pinned Fastly JavaScript
+runtime compiler. Both targets use these same logical bindings.
+
+The external reality task records its selected launcher and executes the Native
+candidate through either direct Viceroy:
+
+```bash
+PULSE_VICEROY_BIN=/path/to/viceroy \
+node wasm/scripts/run-wasm-tests.cjs --task provider-fastly-compute-reality --no-report
+```
+
+or `fastly compute serve --file` selected with `PULSE_FASTLY_BIN`. The gate
+sends real HTTP requests through the Native module. It remains separate from
+portable and offline JavaScript-candidate validation and does not deploy a
+service.

package/docs/guides/fetching-and-composition.md

@@ -0,0 +1,101 @@
+# Fetching and composing data
+
+`ctx.fetch` is the primary host effect for data workflows.
+
+## One project, three composition forms
+
+<!-- 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 -->
+
+The comments separate one structured origin, explicit sequential composition,
+and `ctx.parallel`. Separate awaits retain sequential JavaScript semantics. The
+explicit keyed group is the portable concurrency contract across JavaScript and
+Native targets. Results retain their source keys even when hosts resolve the
+operations in another order.
+
+HTTP 404 and 500 remain ordinary response data. DNS, connection, timeout, and
+host failures fail the effect.
+
+## Dependent requests
+
+A request whose URL or options depend on a previous result lowers to a later continuation point. The compiler does not pretend that dependent effects are an independent group.
+
+## Pass-through
+
+<!-- pulse-doc-source: examples/07-opaque-proxy/src/index.ts -->
+```ts
+import { Pulse } from '@pulse-compute/pulse'
+
+const app = new Pulse({ auto: true })
+
+app.get('/archive', async (ctx) => {
+  return ctx.fetch('https://assets.example.com/archive.bin')
+})
+
+export default app
+```
+<!-- /pulse-doc-source -->
+
+The direct response path preserves status, headers, repeated headers, and the host-owned body. User code cannot inspect or transform the opaque body.