Project configuration reference#

Conventional `.pulse/config.ts`#

Conventional projects use one deferred, synchronous defineConfig factory from @pulse-compute/pulse. Every top-level key except pulse is a flat profile. The scope exposes symbolic config and secret references; it never resolves ambient values while the project plan is built.

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',
    apiBase: scope.config('API_BASE'),
    apiToken: scope.secret('API_TOKEN'),
  },
}))

Project pointers are workspace-relative. Profile selection is explicit and deterministic:

--profile
PULSE_PROFILE
pulse.defaultProfile

Project commands accept one optional positional directory and otherwise start from the current directory. Discovery searches upward only for .pulse/config.ts. Public entry, config-file, workspace, provider, and target overrides are not supported.

Discovery starts at the positional directory or the current working directory and searches upward for .pulse/config.ts.
Profile precedence is --profile, PULSE_PROFILE, then pulse.defaultProfile.
A selected-profile crypto declaration replaces pulse.crypto completely; array and object forms never merge.
Command-line output, host, port, and watch values override the corresponding active-profile field for that command. Entry, provider, and target remain project-configured.
Dedicated harness case inputs replace development inputs for that case; they do not configure deployment resources.
Provider deployment bindings come from the configured provider object; handler source never receives provider SDK objects.

Project and provider selection#

Select the canonical entry, provider, and build output.

`entry`#

Project-relative TypeScript handler entry.

Type: string
Required/default: Optional; default ./src/index.ts.
Allowed values or constraints: —
Scope: all project commands
Precedence: pulse.entry in .pulse/config.ts.
Security and safety: Must resolve to an existing file.
Related diagnostics: PULSE_ENTRY_NOT_FOUND

`provider`#

Selects provider validation, local conformance, and build realization through the provider package toolchain contract.

Type: 'node' | 'fastly' | 'none' | scoped package name | provider configuration
Required/default: Optional; default node.
Allowed values or constraints: node, fastly, none, another bare host id, or an exact scoped package name
Scope: compile/build/dev/test
Precedence: Bare host ids resolve to @pulse-compute/provider-<id>; scoped package names are loaded exactly from the project.
Security and safety: Package loading is explicit and limited to the selected package ./toolchain export; there is no scanning or fallback discovery.
Related diagnostics: PULSE_PROVIDER_PACKAGE_NOT_FOUND, PULSE_PROVIDER_TOOLCHAIN_LOAD_FAILED, PULSE_PROVIDER_TOOLCHAIN_INVALID, PULSE_PROVIDER_UNSUPPORTED, PULSE_PROVIDER_COMPILE_ONLY, PULSE_TEST_PROVIDER_REQUIRED, PULSE_DEV_PROVIDER_UNSUPPORTED

`outDir`#

Project-relative artifact output directory.

Type: string
Required/default: Optional; default ./dist.
Allowed values or constraints: —
Scope: compile/build
Precedence: --out overrides this field for the current command.
Security and safety: Must remain a real child of the project root; absolute, parent-traversal, and symbolic-link traversal outside the project root is rejected.
Related diagnostics: PULSE_BUILD_OUT_UNSAFE

`reporting`#

Resolved synchronous logging threshold after the flat profile override is applied.

Type: 'off' | 'error' | 'warn' | 'info' | 'debug'
Required/default: Optional; default info.
Allowed values or constraints: off, error, warn, info, debug
Scope: compile/build/dev/test
Precedence: Selected-profile reporting, then pulse.reporting, then info.
Security and safety: Known request-owned secret values are redacted before provider emission.
Related diagnostics: PULSE_REPORTING_LEVEL_UNSUPPORTED (family fallback; reference root)

Cryptographic requirements#

Declare exact algorithms for the global or selected profile and resolve one target realization without fallback. This surface is part of the synchronized 1.0.0-beta.6 package set.

`pulse.crypto`#

Declares the complete global algorithm set. Array entries are canonical algorithm names; object entries may pin one exact known realization.

Type: readonly PulseCryptoAlgorithm[] | Readonly<Partial<Record<PulseCryptoAlgorithm, { readonly realization?: PulseCryptoRealization }>>>
Required/default: Optional; default implicit no-crypto declaration.
Allowed values or constraints: HS256, ES256, RS256, SHA-256, HMAC-SHA256; exact pins runtime-builtin, guest-source:pulse-hmac-as, guest-linked:pulse-es256-rustcrypto-p256, and guest-linked:pulse-rs256-bearssl-i31
Scope: global crypto requirement default
Precedence: Used only when the selected profile omits crypto.
Security and safety: Keys and verification bytes are not configuration values. Target selection is deterministic and never probes or falls back.
Related diagnostics: PULSE_CRYPTO_CONFIG_SHAPE_INVALID (family fallback; reference root), PULSE_CRYPTO_ALGORITHM_DUPLICATE (family fallback; reference root), PULSE_CRYPTO_ALGORITHM_UNKNOWN (family fallback; reference root), PULSE_CRYPTO_REALIZATION_UNKNOWN (family fallback; reference root)

`<profile>.crypto`#

Replaces the complete global crypto declaration for the selected profile. Arrays and objects never merge with pulse.crypto.

Type: readonly PulseCryptoAlgorithm[] | Readonly<Partial<Record<PulseCryptoAlgorithm, { readonly realization?: PulseCryptoRealization }>>>
Required/default: Optional; default inherit pulse.crypto when absent.
Allowed values or constraints: [] and {} explicitly select no crypto; otherwise HS256, ES256, RS256, SHA-256, HMAC-SHA256
Scope: selected profile
Precedence: Selected-profile declaration replaces pulse.crypto; absence inherits it.
Security and safety: Every declared algorithm must resolve for the selected target before lowering. A failed exact realization cannot select another backend.
Related diagnostics: PULSE_CRYPTO_CONFIG_REQUIRED (family fallback; reference root), PULSE_CRYPTO_REALIZATION_PIN_INVALID (family fallback; reference root), PULSE_CRYPTO_REALIZATION_UNAVAILABLE (family fallback; reference root)

JSON schema policy#

Configure bounded schema-body policy. Conventional projects declare registry identity only through pulse.schema.

`schemas`#

Sets schema body limits and content-type policy. Schema identities come from the module selected by pulse.schema.

Type: PulseSchemaConfig
Required/default: Optional; default {}.
Allowed values or constraints: —
Scope: compile/dev/test/build
Precedence: Configuration value.
Security and safety: Structured bodies are bounded before decoding.
Related diagnostics: PULSE_SCHEMA_COMPILE_FAILED

`schemas.contentTypePolicy`#

Controls whether a JSON content type is mandatory.

Type: 'accept-json-or-missing' | 'require-json'
Required/default: Optional; default accept-json-or-missing.
Allowed values or constraints: accept-json-or-missing, require-json
Scope: request and fetched-body schema decode
Precedence: Configuration value.
Security and safety: No special handling.
Related diagnostics: PULSE_SCHEMA_CONTENT_TYPE_POLICY_INVALID (family fallback; reference root), PULSE_SCHEMA_DECODE

`schemas.maxBytes`#

Maximum UTF-8 bytes for schema decoding and encoding. Request transport and dev.maxBodyBytes may impose separate limits.

Type: positive safe integer
Required/default: Optional; default 65_536.
Allowed values or constraints: —
Scope: structured schema text
Precedence: Configuration value.
Security and safety: Raise deliberately; this is a memory and request-amplification boundary.
Related diagnostics: PULSE_SCHEMA_BODY_LIMIT_INVALID (family fallback; reference root), PULSE_BODY_TOO_LARGE

Local development#

Configure the foreground local server and local-only provider inputs.

`dev`#

Development listener and local fixture inputs.

Type: object
Required/default: Optional; default {}.
Allowed values or constraints: —
Scope: pulse dev and local conformance
Precedence: Configuration value.
Security and safety: No special handling.
Related diagnostics: None specific.

`dev.host`#

Listener host.

Type: string
Required/default: Optional; default 127.0.0.1.
Allowed values or constraints: —
Scope: pulse dev
Precedence: --host overrides this field.
Security and safety: Binding a non-loopback address exposes the local development server.
Related diagnostics: PULSE_DEV_HOST_INVALID (family fallback; reference root)

`dev.port`#

Listener port.

Type: integer
Required/default: Optional; default 8787.
Allowed values or constraints: 0–65535; 0 requests an ephemeral port
Scope: pulse dev
Precedence: --port overrides this field.
Security and safety: No special handling.
Related diagnostics: PULSE_DEV_PORT_INVALID (family fallback; reference root)

`dev.watch`#

Watches the entry and schema dependency graph.

Type: boolean
Required/default: Optional; default true.
Allowed values or constraints: —
Scope: pulse dev
Precedence: --watch or --no-watch overrides this field.
Security and safety: Configuration-file changes still require a restart.
Related diagnostics: None specific.

`dev.maxBodyBytes`#

Maximum request body accepted by the local development server.

Type: positive safe integer
Required/default: Optional; default 65_536.
Allowed values or constraints: —
Scope: incoming local requests
Precedence: Configuration value.
Security and safety: Raise deliberately; this is a memory and request-amplification boundary.
Related diagnostics: PULSE_DEV_BODY_LIMIT_INVALID (family fallback; reference root), PULSE_REQUEST_BODY_TOO_LARGE

`dev.networkFetch`#

Allows unmatched local fetches to use the network.

Type: boolean
Required/default: Optional; default selected provider default.
Allowed values or constraints: —
Scope: local fetch realization
Precedence: This explicit field overrides the selected provider local default.
Security and safety: Keep disabled for deterministic or untrusted test inputs.
Related diagnostics: PULSE_FETCH_IMPLEMENTATION_UNAVAILABLE, PULSE_FETCH_NETWORK

`dev.config`#

Local configuration-store values.

Type: Readonly<Record<string, string>>
Required/default: Optional; default {}.
Allowed values or constraints: —
Scope: local config capability
Precedence: Configuration value.
Security and safety: Development input only; it does not configure deployed provider stores.
Related diagnostics: None specific.

`dev.secrets`#

Local secret-store values.

Type: Readonly<Record<string, string>>
Required/default: Optional; default {}.
Allowed values or constraints: —
Scope: local secret capability
Precedence: Configuration value.
Security and safety: Raw values are omitted from project JSON, diagnostics, and runtime error details; do not commit real production secrets.
Related diagnostics: None specific.

`dev.kv`#

Local KV stores keyed by configured logical store name.

Type: Readonly<Record<string, Readonly<Record<string, unknown>>>>
Required/default: Optional; default {}.
Allowed values or constraints: —
Scope: local KV capability
Precedence: Configuration value.
Security and safety: Development input only; it is not deployed.
Related diagnostics: None specific.

`dev.fetches`#

Deterministic fetch fixtures resolved before optional live network fetch.

Type: Readonly<Record<string, unknown>>
Required/default: Optional; default {}.
Allowed values or constraints: —
Scope: local fetch capability
Precedence: Configuration value.
Security and safety: Prefer fixtures for deterministic tests and offline development.
Related diagnostics: None specific.

Node provider options#

Provider-owned Node profile configuration.

`node.bodyTransform`#

Opt-in finite request text chunks. Requires generatedOutput and maxDurationMs; incompatible with bodyForwarding. Input 65536 bytes, output 262144 bytes, at most 4 times delivered input bytes. Strict UTF-8, one reader/writer, EOF required before output.close().

Type: boolean
Required/default: Optional; default omitted.
Allowed values or constraints: —
Scope: Experimental Node UTF-8 transforms
Precedence: Configuration value.
Security and safety: No special handling.
Related diagnostics: None specific.

`node.generatedOutput`#

Opt-in finite UTF-8 output. Requires node.maxDurationMs. Each write is at most 16384 bytes; at most 64 writes and 1048576 bytes total. Use STR-03B for exact-candidate installed qualification.

Type: boolean
Required/default: Optional; default omitted.
Allowed values or constraints: —
Scope: Experimental Node generated output
Precedence: Configuration value.
Security and safety: No special handling.
Related diagnostics: None specific.

`node.bodyForwarding`#

Opt-in single-use incoming POST forwarding. maxBytes is a positive safe integer limiting each transfer direction; requires node.maxDurationMs. Pulse emits chunks up to 16384 bytes and retains at most 65536 bytes per pump. Native uses exact Wasm execution and excludes structured request reads in the same application.

Type: { maxBytes: number }
Required/default: Optional; default omitted.
Allowed values or constraints: —
Scope: Node incoming forwarding
Precedence: Configuration value.
Security and safety: No special handling.
Related diagnostics: None specific.

`node.maxDurationMs`#

One provider-owned monotonic budget shared by request effects and continuations; expiry does not prove rollback of dispatched writes.

Type: integer
Required/default: Optional; default omitted.
Allowed values or constraints: 1–30000
Scope: HTTP request execution
Precedence: Configuration value.
Security and safety: No special handling.
Related diagnostics: None specific.

`node.bindings.s3`#

Maps literal logical names to fixed HTTPS endpoint, bucket, region, accessKeyIdSecret, secretAccessKeySecret, optional sessionTokenSecret, maxTextBytes (1–2097152, default 32768) and timeoutMs (1–30000, default 10000).

Type: Readonly<Record<string, S3Binding>>
Required/default: Optional; default {}.
Allowed values or constraints: —
Scope: Node Native and JavaScript S3
Precedence: Configuration value.
Security and safety: Only named credential references are configuration. Runtime keys cannot override authority.
Related diagnostics: None specific.

Fastly provider options#

Options passed to fastly(...) from @pulse-compute/provider-fastly.

`fastly.maxWasmBytes`#

Facade option projected to build.maxWasmBytes. Conventional profiles configure fastly.build.maxWasmBytes.

Type: integer
Required/default: Optional; default 4194304 (4 MiB).
Allowed values or constraints: positive safe integer
Scope: fastly() facade
Precedence: Configuration value.
Security and safety: No special handling.
Related diagnostics: None specific.

`fastly.build.maxWasmBytes`#

Inclusive byte budget checked for newly compiled and reused artifacts. Raising it does not increase runtime memory or change Fastly service limits. The fastly() facade accepts maxWasmBytes.

Type: integer
Required/default: Optional; default 4194304 (4 MiB).
Allowed values or constraints: positive safe integer
Scope: Native final Wasm artifact
Precedence: Configuration value.
Security and safety: No special handling.
Related diagnostics: None specific.

`fastly.maxDurationMs`#

One provider-owned monotonic budget through buffered response handoff; expiry attempts 504 before headers commit and never asserts rollback of dispatched writes. No CPU preemption or post-handoff delivery guarantee.

Type: integer
Required/default: Optional; default omitted.
Allowed values or constraints: 1–30000
Scope: HTTP request execution
Precedence: Configuration value.
Security and safety: No special handling.
Related diagnostics: None specific.

`fastly.bindings.s3`#

Maps logical names to fixed HTTPS endpoint, bucket, region, named static backend, accessKeyIdSecret, secretAccessKeySecret, optional sessionTokenSecret, maxTextBytes (1–2097152, default 32768) and timeoutMs (1–30000, default 10000).

Type: Readonly<Record<string, S3Binding & { backend: string }>>
Required/default: Optional; default {}.
Allowed values or constraints: —
Scope: Fastly Native S3
Precedence: Configuration value.
Security and safety: Credentials resolve through the configured Secret Store at execution. Dynamic backend authority and guest endpoint overrides are forbidden.
Related diagnostics: None specific.

`fastly.configStore`#

Fastly Config Store resource name.

Type: string
Required/default: Optional; default pulse_config.
Allowed values or constraints: —
Scope: Fastly config capability
Precedence: Configuration value.
Security and safety: No special handling.
Related diagnostics: None specific.

`fastly.secretStore`#

Fastly Secret Store resource name.

Type: string
Required/default: Optional; default pulse_secrets.
Allowed values or constraints: —
Scope: Fastly secret capability
Precedence: Configuration value.
Security and safety: The name is build metadata; secret values are never embedded by this option.
Related diagnostics: None specific.

`fastly.kv`#

Maps logical ctx.kv names to Fastly KV Store resource names.

Type: Readonly<Record<string, string>>
Required/default: Optional; default {}.
Allowed values or constraints: —
Scope: Fastly KV capability
Precedence: Configuration value.
Security and safety: No special handling.
Related diagnostics: PULSE_FASTLY_KV_BINDINGS_INVALID

`fastly.backends`#

Maps static absolute origin URLs to named Fastly backends.

Type: Readonly<Record<string, string>>
Required/default: Optional; default {}.
Allowed values or constraints: —
Scope: Fastly fetch capability
Precedence: Configuration value.
Security and safety: Prefer explicit backends over dynamic origin authority.
Related diagnostics: PULSE_FASTLY_BACKEND_BINDINGS_INVALID, PULSE_FASTLY_BACKEND_REQUIRED

`fastly.dynamicBackends`#

Allows undeclared outbound origins to use dynamic backends.

Type: boolean
Required/default: Optional; default false.
Allowed values or constraints: —
Scope: Fastly fetch capability
Precedence: Configuration value.
Security and safety: Opt in deliberately because it broadens outbound authority.
Related diagnostics: PULSE_FASTLY_BACKEND_REQUIRED

`fastly.grip`#

Provider-owned bindings used by package-owned GRIP compatibility and canonical broadcast effects.

Type: object
Required/default: Optional; default omitted.
Allowed values or constraints: —
Scope: Fastly GRIP capability
Precedence: Configuration value.
Security and safety: No special handling.
Related diagnostics: None specific.

`fastly.grip.fanoutBackend`#

Named Fastly Fanout backend.

Type: string
Required/default: Optional; default omitted.
Allowed values or constraints: —
Scope: GRIP hold
Precedence: Configuration value.
Security and safety: No special handling.
Related diagnostics: PULSE_FASTLY_GRIP_FANOUT_BACKEND_REQUIRED

`fastly.grip.publishEndpoint`#

Provider-owned absolute publish/control endpoint; distinct from public gateway and ingress URLs.

Type: string
Required/default: Optional; default omitted.
Allowed values or constraints: —
Scope: GRIP broadcast
Precedence: Configuration value.
Security and safety: No special handling.
Related diagnostics: PULSE_FASTLY_GRIP_PUBLISH_BINDING_REQUIRED

`fastly.grip.publishUrl`#

Absolute publish endpoint URL.

Type: string
Required/default: Optional; default omitted.
Allowed values or constraints: —
Scope: GRIP publish
Precedence: Configuration value.
Security and safety: No special handling.
Related diagnostics: PULSE_FASTLY_GRIP_PUBLISH_BINDING_REQUIRED

`fastly.grip.publishBackend`#

Named backend for the provider publish endpoint.

Type: string
Required/default: Optional; default omitted.
Allowed values or constraints: —
Scope: GRIP broadcast/publish
Precedence: Configuration value.
Security and safety: No special handling.
Related diagnostics: PULSE_FASTLY_GRIP_PUBLISH_BINDING_REQUIRED

`fastly.grip.authentication`#

Authentication metadata containing references only; no credential value is accepted here.

Type: object
Required/default: Optional; default omitted.
Allowed values or constraints: —
Scope: GRIP broadcast authentication
Precedence: Configuration value.
Security and safety: Store the value in Fastly Secret Store and configure only secretRef.
Related diagnostics: None specific.

`fastly.grip.authentication.scheme`#

Provider authentication scheme.

Type: 'bearer'
Required/default: Optional; default bearer.
Allowed values or constraints: —
Scope: GRIP broadcast authentication
Precedence: Configuration value.
Security and safety: No special handling.
Related diagnostics: PULSE_FASTLY_NATIVE_GRIP_AUTH_SCHEME_UNSUPPORTED (family fallback; reference root)

`fastly.grip.authentication.secretRef`#

Named Fastly Secret Store key used for the bearer token.

Type: string
Required/default: Optional; default omitted.
Allowed values or constraints: —
Scope: GRIP broadcast authentication
Precedence: Configuration value.
Security and safety: The secret value is resolved only at request execution and is redacted from traces.
Related diagnostics: PULSE_FASTLY_NATIVE_GRIP_SECRET_REFERENCE_MISSING (family fallback; reference root)

`fastly.grip.directHold`#

Enables the direct host-owned hold response realization.

Type: boolean
Required/default: Optional; default true.
Allowed values or constraints: —
Scope: GRIP hold
Precedence: Configuration value.
Security and safety: No special handling.
Related diagnostics: None specific.

`fastly.name`#

Generated Fastly package name.

Type: string
Required/default: Optional; default pulse-app.
Allowed values or constraints: —
Scope: Fastly package metadata
Precedence: Configuration value.
Security and safety: No special handling.
Related diagnostics: None specific.

`fastly.description`#

Generated Fastly package description.

Type: string
Required/default: Optional; default Pulse application.
Allowed values or constraints: —
Scope: Fastly package metadata
Precedence: Configuration value.
Security and safety: No special handling.
Related diagnostics: None specific.

`fastly.authors`#

Generated Fastly package authors.

Type: readonly string[]
Required/default: Optional; default [].
Allowed values or constraints: —
Scope: Fastly package metadata
Precedence: Configuration value.
Security and safety: No special handling.
Related diagnostics: None specific.

`fastly.local`#

Local-only behavior; it does not alter the deployed target.

Type: object
Required/default: Optional; default {}.
Allowed values or constraints: —
Scope: local Fastly conformance
Precedence: Configuration value.
Security and safety: No special handling.
Related diagnostics: None specific.

`fastly.local.networkFetch`#

Allows unmatched local Fastly fetches to use the network.

Type: boolean
Required/default: Optional; default false.
Allowed values or constraints: —
Scope: local Fastly fetch realization
Precedence: dev.networkFetch overrides this value when explicitly set.
Security and safety: Keep disabled for deterministic tests and offline development.
Related diagnostics: None specific.

Fastly profile example#

local: {
  host: 'fastly',
  target: 'native',
  fastly: {
    bindings: {
      configStore: 'pulse_config',
      secretStore: 'pulse_secrets',
      kv: { sessions: 'sessions' },
      backends: { 'https://api.example.com': 'api_backend' },
      dynamicBackends: false,
      grip: {
        fanoutBackend: 'fanout',
        publishUrl: 'https://publisher.example.com/publish',
        publishBackend: 'publisher',
        directHold: true,
      },
    },
    build: { name: 'pulse-app', authors: ['Team'] },
    local: { networkFetch: false },
  },
}

Deployment resource names configure provider bindings; local dev.config, dev.secrets, dev.kv, and dev.fetches values never create or populate deployed resources.

Safety invariants#

Output directories must remain real descendants of the project root.
Structured request and schema bodies are bounded before decoding.
Live local network fetch is explicit for Fastly and can be disabled for Node.
Raw secret values are redacted from public JSON, diagnostics, and runtime error detail.
Provider SDK objects and provider-specific namespaces never enter canonical handler scope.
none is compile-only; it cannot execute pulse dev or pulse test.

Project configuration reference#

Conventional .pulse/config.ts#

Project and provider selection#

entry#

provider#

outDir#

reporting#

Cryptographic requirements#

pulse.crypto#

<profile>.crypto#

JSON schema policy#

schemas#

schemas.contentTypePolicy#

schemas.maxBytes#

Local development#

dev#

dev.host#

dev.port#

dev.watch#

dev.maxBodyBytes#

dev.networkFetch#

dev.config#

dev.secrets#

dev.kv#

dev.fetches#

Node provider options#

node.bodyTransform#

node.generatedOutput#

node.bodyForwarding#

node.maxDurationMs#

node.bindings.s3#

Fastly provider options#

fastly.maxWasmBytes#

fastly.build.maxWasmBytes#

fastly.maxDurationMs#

fastly.bindings.s3#

fastly.configStore#

fastly.secretStore#

fastly.kv#

fastly.backends#

fastly.dynamicBackends#

fastly.grip#

fastly.grip.fanoutBackend#

fastly.grip.publishEndpoint#

fastly.grip.publishUrl#

fastly.grip.publishBackend#

fastly.grip.authentication#

fastly.grip.authentication.scheme#

fastly.grip.authentication.secretRef#

fastly.grip.directHold#

fastly.name#

fastly.description#

fastly.authors#

fastly.local#

fastly.local.networkFetch#