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

package/docs/packages/s3.md

@@ -0,0 +1,101 @@
+# `@pulse-compute/s3`
+
+S3 provides bounded exact-key `head`, `getText` and `putText` effects. It is a
+supported extension in the synchronized `1.0.0-beta.2` candidate. Candidate
+preparation does not assert that the package has been published to npm. Consume
+the exact compatible S3, Pulse, CLI and provider tarballs from one release pack.
+
+## Authoring and lowering
+
+```ts
+import { s3 } from '@pulse-compute/s3'
+
+const written = await s3.putText(ctx, 'objects', key, text, {
+  contentType: 'application/json',
+})
+const inspected = await ctx.parallel({
+  metadata: s3.head(ctx, 'objects', key),
+  object: s3.getText(ctx, 'objects', key),
+})
+```
+
+Use these expressions inside a Pulse handler. Await into a local variable or
+use keyed `ctx.parallel`. The logical binding must be a string literal. Key and
+text may be runtime strings; content type is optional literal metadata and does
+not serialize the text. Strict JSON responses require a response schema.
+
+S3 owns its facade, operation contract, compiler recognition, Native lowering,
+key encoding, SigV4 protocol and result interpretation. Native targets compose
+the packaged AssemblyScript implementation with Crypto's SHA-256 and HMAC-SHA256
+primitives. Node JavaScript uses the package protocol and Crypto's bounded Web
+Crypto realization. Providers own fixed authority, credential resolution,
+deadlines, raw metadata and transport. Application imports use only the package
+root; `/provider`, manifest, compiler and Native exports are toolchain integration.
+
+## Binding map
+
+Declare `crypto: ['SHA-256', 'HMAC-SHA256']` in Pulse configuration. Map each
+logical name under `<profile>.node.bindings.s3` or
+`<profile>.fastly.bindings.s3`.
+
+| Field | Contract |
+| --- | --- |
+| `endpoint` | Fixed HTTPS origin, without a path, query or credentials |
+| `bucket`, `region` | Explicit bucket and signing region |
+| `accessKeyIdSecret`, `secretAccessKeySecret` | Names of provider secrets |
+| `sessionTokenSecret` | Optional provider secret name |
+| `maxTextBytes` | 1–32768; default 32768 |
+| `timeoutMs` | 1–30000; default 10000; includes credentials, signing and body completion |
+| `backend` | Fastly requires a named static backend; configure its secret store in `fastly.bindings.secretStore` |
+
+Runtime keys cannot select an origin, bucket, region, backend or credentials.
+Keys are 1–1024 UTF-8 bytes, with no controls or `.`/`..` path segments. Slashes,
+repeated slashes and Unicode normalization are preserved; encoding occurs once.
+
+## Results and bounds
+
+| Operation | Successful result | Other results |
+| --- | --- | --- |
+| `head` | `found`: byte length, optional opaque ETag and content type | `not-found` or `failed` with bounded reason and observed HTTP status |
+| `getText` | `found`: exact UTF-8 text, raw byte length and SHA-256, optional metadata | `not-found` or `failed`; malformed UTF-8 is rejected |
+| `putText` | `stored`: sent byte length and SHA-256, optional opaque ETag | `not-stored` before dispatch or for complete explicit 4xx rejection except 408; `unknown` when dispatch may have stored bytes |
+
+GET and PUT are bounded to 32768 UTF-8 bytes, or the lower binding limit. Empty
+text is allowed and a BOM is preserved. HEAD requires a safe Content-Length and
+can describe an object larger than the text limit. Metadata is bounded to 16384
+aggregate bytes and 1024 bytes per selected value; duplicate selected headers,
+malformed lengths, truncated bodies and compression fail closed.
+
+PUT succeeds only on a complete 200 acknowledgement with an empty body. Its
+digest identifies sent bytes, not origin durability. Cancellation terminates
+the request lifecycle without a typed S3 result or a rollback promise. There
+are no retries, redirects, decompression or caches. For a JSON request carrying
+32768 escaped control characters, configure `schemas.maxBytes: 262144`; the
+object byte limit remains unchanged.
+
+## Target support and evidence
+
+| Target | S3 support | Local acceptance |
+| --- | --- | --- |
+| Node Native | Supported | Compiled Wasm with the Node provider |
+| Node JavaScript | Supported | Package runtime with bounded Web Crypto |
+| Fastly Native | Supported | Compiled provider Wasm with host ABI fixtures |
+| Fastly JavaScript | Ineligible | SDK header projection loses required raw metadata |
+
+The read and write corpus is repeated from isolated exact-version tarball
+installs, using installed compilers, package lowering and provider realizations.
+It covers signatures, key encoding, malformed and truncated data, limits,
+credentials, redaction, deadlines and ambiguous writes. Fastly JavaScript's
+exclusion does not gate these supported targets.
+
+Local fixtures do not establish live Fastly Object Storage semantics. Live
+origin acceptance follows infrastructure setup (T2) and records endpoint,
+region, target artifact, exact observed bytes and acknowledgement behavior.
+There is no listing, multipart upload, copy, presigning, arbitrary bucket
+selection or conditional creation. Assets alignment remains separate.
+
+## Related material
+
+- [Project configuration](../reference/project-config.md)
+- [Package-owned lowering](../concepts/package-owned-lowering.md)
+- [Crypto](./crypto.md)

package/docs/preview-scope.md

@@ -0,0 +1,142 @@
+# Beta scope
+
+Pulse `1.0.0-beta.2` is a Beta of one provider-neutral application contract
+with explicit Native and JavaScript execution targets. The intended 1.0
+surface is present, but deliberate corrections may still occur before the
+stable `1.0.0` release.
+
+The Beta is intentionally strict: Pulse builds the target selected by the
+active `.pulse/config.ts` profile, and unsupported source stops at the exact
+lowering boundary with a stable diagnostic. Pulse never silently switches
+targets.
+
+## Supported application behavior
+
+- Async-shaped provider-neutral TypeScript handlers; trusted Pulse awaits lower
+  into explicit effects and continuations without a Promise runtime.
+- Static Router v2 with terminal middleware, route fallthrough, error
+  middleware, GET/HEAD/POST/PUT/PATCH/DELETE routes, exact paths, named parameters, trailing
+  wildcards, and acyclic mounts.
+- Basic branching and structured object, array, and scalar manipulation.
+- Request method, URL, path, headers, text, and JSON access.
+- Bounded, memoized structured body decoding.
+- Explicit TypeScript JSON schema declarations and literal schema IDs.
+- GET, HEAD, and POST fetch effects.
+- Independent Native effect grouping, dependent continuation chains, and
+  explicit cross-target `ctx.parallel({ ... })` keyed groups.
+- HTTP status and headers as ordinary response data.
+- JSON, text, custom, and direct pass-through responses.
+- Exact-name config and secret reads.
+- Named KV `get` and `put`.
+- Opaque host-owned binary and stream pass-through.
+- Stateless package-root GRIP request classification, response subscription and
+  handoff framing, and configured request-bound broadcast.
+- Synchronous string logging through `ctx.log.error`, `warn`, `info`, and
+  `debug`, with flat profile reporting thresholds and provider-owned output.
+- Root-only static `Pulse.on` declarations, immutable schema-validated event
+  contexts, and one-way `ctx.emit` acceptance through the bounded Node
+  JavaScript/Native reference adapter.
+- Provider-neutral portable Wasm and configured Native Node or Fastly builds.
+- Direct JavaScript execution and deterministic source packaging for Node and
+  Fastly.
+
+## Execution contract
+
+The Beta has two target classes and four explicitly selected
+execution modes over one application model:
+
+```text
+source
+├─ Node / Native        → canonical analysis → Pulse-owned Wasm → Node realization
+├─ Node / JavaScript    → graph-backed loader → live packages → Node lifecycle
+├─ Fastly / Native      → canonical analysis → direct-host-ABI bin/main.wasm
+└─ Fastly / JavaScript  → deterministic source package → Fastly JS runtime candidate
+```
+
+Native source that crosses the supported lowering boundary fails visibly with a
+stable diagnostic. JavaScript core Router execution, request/response lifecycle,
+eligibility inspection, effects, package realizations, source packaging, schema
+enforcement, target integrity, and bounded GRIP realization are implemented.
+Native/JavaScript conformance covers Router context, body handling, fetch
+projections, configuration, secrets, KV, schema codecs, GRIP framing, logging,
+and target identity. All declared Node and Fastly full-target-support gates are
+satisfied for the implemented four-mode contract.
+
+Fastly JavaScript candidate evidence compiles the deterministic source package
+with the exact pinned downstream toolchain and records a structurally deployable
+runtime artifact. The final release candidate must additionally pass the
+mandatory external Fastly CLI-managed reality lane. Neither result authorizes a
+service deployment or activation.
+
+There is no automatic fallback. An operator must select the target through
+project configuration or an explicitly permitted CLI target selection. A
+successful provider-neutral compile does not silently change a
+JavaScript-selected project into a Native one.
+
+## Deliberately unsupported
+
+- Automatic fallback from Native lowering to JavaScript execution.
+- Declaring general target availability without satisfying every declared
+  full-target-support gate.
+- Arbitrary Promise construction, arbitrary library awaits under Native
+  selection, JSPI, or Asyncify semantics. Managed `async` wrappers and trusted
+  Pulse awaits are supported notation, not a Promise runtime.
+- Ambient `fetch`, environment variables, filesystem, process, sockets, or
+  timers.
+- Provider SDK objects or `ctx.fastly` / `ctx.cloudflare` namespaces.
+- Capability enumeration or runtime provider introspection.
+- Automatic discovery of arbitrary TypeScript types.
+- Dynamic schema IDs.
+- Arbitrary binary body inspection or mutation.
+- Userland chunk iteration, transform streams, or manual backpressure.
+- Background tasks and work that outlives the request.
+- Raw TCP or UDP sockets.
+- Dynamic GRIP channel, framing-option, or message shapes under Native
+  selection.
+- Onion-style post-`next()` middleware, assigning or awaiting `next()`, Router
+  `throw` transfer, realtime hooks, channels, timeout scopes, `ctx.resolve`, or
+  `ctx.resolved`.
+- Third-party provider or lowerer self-registration.
+- A public event listener, production event transport, delivery/retry
+  guarantee, automatic loopback or reentrancy, generic bus, `ctx.call`, or
+  request/reply event routing.
+- Fastly, browser, or ESP32 event ingress/emit realization. Fastly fails closed
+  with exact eligibility diagnostics; browser and ESP32 remain unclaimed.
+
+## Compatibility authority
+
+The single source-form, provider-binding, artifact, and deployment-boundary
+table is [Provider and target compatibility](./reference/compatibility-matrix.md).
+It uses one public target order—Node JavaScript, Fastly JavaScript, Node Native,
+and Fastly Native—and links every row to a focused proof or canonical contract.
+
+The exact portable language subset and the JavaScript-only Native eligibility
+boundaries are defined in
+[Managed handler TypeScript and JavaScript](./reference/handler-authoring.md).
+
+## Body model
+
+If a body is inspected as text or JSON, Pulse treats it as a bounded immutable
+value. If a body is passed through as binary or a stream, it remains an opaque
+host-owned capability handle.
+
+```text
+inspect it → bounded structured value
+pass it through → opaque handle
+```
+
+## Compatibility and release signals
+
+- Documented behavior is intentional and evidence-backed.
+- Unsupported behavior fails explicitly.
+- No execution target silently falls back.
+- Public surfaces may still change deliberately before stable `1.0.0`.
+- Implementation and historical subpaths do not gain accidental compatibility
+  guarantees.
+- Package names, release artifacts, and published versions are immutable once
+  released.
+
+The intended npm dist-tag for the Beta is `beta`. It becomes
+active only through the atomic documentation-release transaction and an
+explicitly authorized publication. The workflow never assigns `latest`
+implicitly.

package/docs/reference/README.md

@@ -0,0 +1,33 @@
+<!-- pulse-doc-meta:start
+owner: docs-platform
+status: active
+last-reviewed: 2026-08-01
+review-by: 2027-02-01
+pulse-doc-meta:end -->
+
+# Reference
+
+Use this section for exact application, command, configuration, compatibility,
+and diagnostic contracts.
+
+- [API reference](../../API.md) — a context-at-a-glance map plus the exact
+  Router, request, header, route parameter, state, response, and capability
+  surfaces.
+- [Provider and target compatibility](./compatibility-matrix.md) — supported
+  behavior across Node and Fastly Native and JavaScript targets.
+- [Managed handler TypeScript and JavaScript](./handler-authoring.md) — the
+  accepted authoring language and Native eligibility boundary.
+- [CLI reference](./cli.md) — commands, flags, and machine-readable command
+  specification.
+- [Project configuration](./project-config.md) — profiles, providers, targets,
+  bindings, and schemas.
+- [Diagnostics and remediation](./diagnostics.md) — stable public diagnostic
+  codes and corrective actions.
+- [Environment variables](./environment.md) — supported tooling inputs and
+  contributor-only controls.
+- [Shell completion](./shell-completion.md) — Bash, Zsh, and Fish integration.
+
+Repository governance, release operations, publication, deployment, and
+evidence procedures are intentionally separated from the application
+reference. Maintainers can enter that narrower surface through the
+[maintainer documentation](../maintainers/).