@pulse-compute/entities#

@pulse-compute/entities provides bounded, statically declared, schema-bound operations through the first-party JSON-RPC adapter.

npm install @pulse-compute/entities@1.0.0-beta.6

Declare an entity router#

import { EntityRouter, jsonRpc } from '@pulse-compute/entities'

const rpc = new EntityRouter({
  adapter: jsonRpc({ namedParamsOnly: true }),
})

rpc.on('customer.lookup', {
  input: 'tools.CustomerLookupInput',
  output: 'tools.CustomerLookupOutput',
  metadata: {
    title: 'Look up customer',
    description: 'Returns one customer from the governed directory backend.',
  },
}, lookupCustomer)

export default function handler(ctx: unknown) {
  return rpc.handle(ctx as never)
}

input and output are literal schema IDs declared by the selected Pulse project, or null. A null input passes undefined to the handler; a null output requires undefined and becomes JSON null. Metadata must be bounded, static JSON. Handlers must be resolvable named references and may use the same governed ctx effects as ordinary managed handlers.

The compiler recognizes a deliberately narrow static form: one module-level router, an inline first-party adapter declaration, standalone module-level registrations, and one terminal request binding. It rejects aliases, dynamic names, computed schema IDs, conditional registration, chained registration, and multiple request-body owners.

JSON-RPC behavior#

The first adapter accepts JSON-RPC 2.0 request objects and named object params. It does not accept batches or positional params. It selects an entity before schema decoding, invokes the handler once, validates output, and emits stable JSON-RPC failures without application exception details.

acceptEmptyObjectForNoInput: true additionally permits {} for an operation whose input is null. namedParamsOnly can only be true in this contract.

JavaScript workflow and inspection#

The Entities tools example defaults to the Node JavaScript profile. From that example directory, use the ordinary lifecycle:

pulse doctor
pulse inspect
pulse test
pulse dev
pulse build

The two harness cases exercise the no-input operation and a schema-bound lookup with a plain-text fetch fixture. Harness fixtures apply to pulse test; live lookup requests need a configured development fixture or backend. Stop the dev server before continuing to the build.

pulse inspect reports the entity plan, deterministic catalog, schema linkage, redacted handler effects, and target evidence. A successful build writes:

• entities-catalog.json: protocol-neutral discovery metadata;
• entities-inspection.json: declarations, handler identities/effects, and

eligibility/measured-execution evidence.

The cli-entities-installed-workflow acceptance gate packs the current candidate, installs example 10 outside the checkout, and runs doctor, inspect, test, dev startup/request/shutdown, build and artifact inspection in all four profiles. It checks installed package bytes before/after and matches Native test/build artifact hashes. This is candidate-package evidence; it does not retroactively change previously published packages. Fastly test/dev evidence uses its local fixture runtime, separately from external Viceroy and deployed acceptance.

Both artifacts are static and checkout-independent. They intentionally omit request/runtime values, request IDs, raw payloads, resolved secrets, and provider objects. Consumers such as a tools facade should project discovery from the catalog and invoke a governed adapter boundary; they should not gain a direct handler or runtime-registry API.

Target status#

The source-checkout task entities-orchestration-demo separately exercises the tools facade and package-owned Native artifact. The entities-node-native-workflow and fastly-entities-native-workflow gates separately verify that ordinary tests execute the same guest bytes emitted by build. Fastly builds write bin/main.wasm and src/main.as.ts. Select host: 'fastly', target: 'native' and configure the required Fastly backend/store bindings in the profile.

Fastly pulse test and pulse dev execute the provider artifact against its fixture ABI; development fetches require fixtures. Set PULSE_VICEROY_BIN when running the Fastly workflow gate to replay the emitted Wasm with the explicit local engine and local backend/store configuration. Local Viceroy replay is separate from live Fastly deployment evidence; no deployment is claimed.

Native remains provider-dependent, and every target keeps automatic fallback disabled. The complete matrix is in Provider and target compatibility.

Native Entities projects support closed typed schemas, including optional fields, nested objects, arrays and nullable values. Their generated decoder enforces the profile's schemas.maxBytes; the adapter separately bounds the envelope, params and output. A provider may reject an oversized request before JSON-RPC handling.

Dynamic JSON (OpenObject, JsonObject, JsonValue, ScalarRecord) and schemas with JSON admission options currently require JavaScript for Entities. Native builds reject reachable schemas they cannot preserve with PULSE_ENTITIES_TARGET_INELIGIBLE. Catalog eligibility and inspection report this restriction for entity input/output declarations. Unused schema declarations do not disqualify an entity. Native also checks schemas used by managed fetch projections when generating the application.

Diagnostics#

These codes are package-owned entries in the synchronized Beta diagnostic catalog.

Malformed envelopes can additionally produce bounded scanner codes such as PULSE_ENTITIES_JSON_MALFORMED, PULSE_ENTITIES_JSON_TOO_DEEP, PULSE_ENTITIES_ENVELOPE_TOO_LARGE, and PULSE_ENTITIES_PAYLOAD_TOO_LARGE. Clients receive only the stable JSON-RPC mapping, while provider observability records a redacted failure category.

Related material#

• Entity engine, adapters, and facades
• Canonical API
• Entities lowering maintainer reference
• Executable Entities tools example