@hs-x/checkpoint

@hs-x/checkpoint is HS-X's observability primitive layer — how a deployed app records what each capability invocation did (its outcome, duration, and an error fingerprint) without leaking sensitive values. It defines fingerprinting, redaction, exemplar sampling policy, fake/in-memory writers for tests, and the Cloudflare binding writers that persist the data, all against the canonical schemas in @hs-x/types.

You normally do not install this directly. It is a transitive dependency of @hs-x/runtime, which calls it for you when you enable checkpointing in createRuntime(...). A fake-writer surface for tests is published at the @hs-x/checkpoint/test subpath.

# only for standalone tooling against the checkpoint contracts
bun add @hs-x/checkpoint

Recording an invocation

recordCheckpointInvocation(...) (and its Effect form, recordCheckpointInvocationEffect(...)) emits a metric event plus, when the exemplar policy selects it, a redacted exemplar to the configured CheckpointWriter. fingerprintError(...) produces the stable error fingerprint used to group failures; redactCheckpointValue(...) strips sensitive fields before anything is stored. The sampling/budget rules come from createExemplarPolicy(...).

Cloudflare writer

createCloudflareCheckpointWriter() composes the runtime write targets behind the stable CheckpointWriter contract:

• Analytics Engine receives every CheckpointMetricEvent.
• D1 receives sampled or budgeted CheckpointRunExemplar rows in checkpoint_exemplars by default.
• Queue receives metric and exemplar envelopes for async fanout.
• R2 receives error exemplars by default, with optional success exemplar archival.

The D1 table name is configurable but must already exist. The default migration is published at migrations/0001_checkpoint_exemplars.sql and creates:

CREATE TABLE checkpoint_exemplars (
  exemplar_id TEXT PRIMARY KEY,
  account_id TEXT NOT NULL,
  hsx_account_id TEXT NOT NULL,
  project_id TEXT NOT NULL,
  deploy_id TEXT NOT NULL,
  worker_name TEXT NOT NULL,
  capability_id TEXT NOT NULL,
  portal_id TEXT NOT NULL,
  outcome TEXT NOT NULL,
  observed_at TEXT NOT NULL,
  duration_ms REAL NOT NULL,
  fingerprint TEXT,
  value_json TEXT NOT NULL
);

listD1CheckpointExemplars() reads those D1 rows back through the same shared schema with optional project, deploy, outcome, fingerprint, and limit filters.

Part of HS-X

HS-X is a leaveable, type-safe HubSpot app framework on Cloudflare Workers. Deployed apps run in your own Cloudflare account, and the checkpoint data this package writes lands in your own Analytics Engine, D1, and R2, not in HS-X's. Start with the CLI:

npm i -g @hs-x/cli
hs-x init myapp

See @hs-x/cli and the docs at hs-x.dev/docs.

License

Apache-2.0