@forgezero/runtime

v0.1.17

Published

11 hours ago

The machinery a service needs behind its request handlers: jobs, keyed queues, a transactional outbox, a hash-chained audit trail, templated mail, encrypted backups and schema validation.

0High
0Medium
0Low

axxra

jobs scheduler queue outbox audit hash-chain backup notifications json-schema validation calendar billing-period working-days

Platform runtime

The machinery behind a request handler — jobs, queues, an outbox, a hash-chained audit trail, mail, backups, schema validation and exact money. 30 public modules, each imported on its own.

Package overview

Anyone running a service, for the work that happens outside a request. Separate from access because a Cloudflare Worker wants the request pipeline and cannot run a backup job. Supported runtimes: bun, node. Package root: @forgezero/runtime. Consumer documentation is curated with each module's explicit public flag; the complete internal/export inventory remains in the typed SSOT and declaration files.

bun add @forgezero/runtime

ForgeZero package family

The five packages are installation boundaries. Choose a package by who installs it; choose a subpath by the capability used in that file.

| package | short description | runtimes | documentation | |---|---|---|---| | @forgezero/vault | Scoped secret access with Agent, API-key and systemd-credential sources. | bun, node, workers, deno | Open | | @forgezero/access | Typed route, principal, factor, RBAC and request-pipeline contracts. | bun, node, workers, deno | Open | | @forgezero/providers | Typed external providers with priority, health and classified fallback. | bun, node, workers, deno | Open | | @forgezero/runtime | Portable runtime primitives for queries, jobs, events, schemas and finance. | bun, node | Open | | @forgezero/agent | Operator CLI and managed-node agent for bootstrap, deploy and lifecycle. | bun, node | Open |

@forgezero/runtime supported imports and commands

These are supported consumer entry points, not every internal module shipped for ForgeZero managed installation. Each row links to its task-oriented usage.

| public entry | short description | runtime | details | |---|---|---|---| | @forgezero/runtime/query | Provider-neutral typed function contracts: decode untrusted input, run with caller-supplied services or storage, and strictly validate the result without coupling business logic to ForgeZero or ArangoDB. | portable | Reference + usage | | @forgezero/runtime/jobs | Background work that never overlaps itself, advances a cursor only on success, and can be paused and inspected. | portable | Reference + usage | | @forgezero/runtime/queue | Memory-only keyed work queue — awaited results, parallel across keys and strictly sequential within one; clustered callers atomically claim ownership in their own business store before submitting. | portable | Reference + usage | | @forgezero/runtime/outbox | Write the event with the record, deliver it after, in order per key with backoff and a dead-letter queue. | portable | Reference + usage | | @forgezero/runtime/audit | Append-only records chained by hash, with a verifier that names the first altered entry. | portable | Reference + usage | | @forgezero/runtime/backup | Encrypted, chunked, verified snapshots to object storage — and the restore that reads them back. | portable | Reference + usage | | @forgezero/runtime/notify | Render a named template to text and HTML, escaped per part, refusing to send with a blank where a value should be. | portable | Reference + usage | | @forgezero/runtime/notify/templates | The six transactional messages ForgeZero sends. | portable | Reference + usage | | @forgezero/runtime/calendar | Billing periods computed from an anchor, working days, holidays and due dates. | portable | Reference + usage | | @forgezero/runtime/totp | RFC 6238 TOTP on the existing HMAC — base32, an asymmetric window, and replay left to the caller. | portable | Reference + usage | | @forgezero/runtime/passkey | Passkeys for sites that are not us. A vault-held credential is as unphishable as one in a security chip provided the RP ID check never slips — evil-example.com ends with example.com and is a different site. | portable | Reference + usage | | @forgezero/runtime/phrase | BIP-39 recovery phrases, and the salted verifier that proves one without being able to reconstruct it. | portable | Reference + usage | | @forgezero/runtime/snp | Parse an AMD SEV-SNP attestation report at the firmware ABI offsets, and compare a TCB component by component so a microcode bump cannot mask a firmware downgrade. | portable | Reference + usage | | @forgezero/runtime/importers | Read secrets out of a .env, a CSV, or a Bitwarden or 1Password export — skipping what cannot be understood rather than guessing, and never putting a value in an error. | portable | Reference + usage | | @forgezero/runtime/openssh | OpenSSH wire encoding, so a derived ed25519 key becomes a line that pastes into authorized_keys. | portable | Reference + usage | | @forgezero/runtime/ssh-cert | OpenSSH certificates, so access expires instead of having to be hunted down. Takes a signing FUNCTION rather than a secret key, which is what lets the CA live in a vault that never hands it out. | portable | Reference + usage | | @forgezero/runtime/slip10 | SLIP-0010 derivation for ed25519, hardened-only — BIP-32 does not work on this curve and produces halves that do not correspond. | portable | Reference + usage | | @forgezero/runtime/identity | Hybrid Ed25519 + ML-DSA-65 request signing. One canonical string, so the compute agent that signs inside a guest and the API that verifies cannot drift — which two implementations of it certainly would. | portable | Reference + usage | | @forgezero/runtime/schema | Validate against JSON Schema, restrict what a caller may declare, and describe a schema as a form. | portable | Reference + usage | | @forgezero/runtime/schema/typebox | The TypeBox validator behind that interface. | portable | Reference + usage | | @forgezero/runtime/finance/discounts | Promotions as arithmetic over integer minor units. They never stack — one winner — and a percentage rounds down, because rounding a discount up gives away a unit of currency per invoice forever. | portable | Reference + usage | | @forgezero/runtime/finance/money | Exact amounts in minor units with the asset attached, so two currencies cannot be added. | portable | Reference + usage | | @forgezero/runtime/finance/tax | Which jurisdiction may tax a sale, who accounts for it, and the three ways to be zero that report differently. Rates are data. | portable | Reference + usage | | @forgezero/runtime/finance/storage | Write an amount so it is both exact and sortable: an authoritative string, and a number that is only an index. | portable | Reference + usage | | @forgezero/runtime/realtime | Provider-neutral realtime audience, shard, event and delivery contracts. | portable | Reference + usage | | @forgezero/runtime/passkey-hybrid | Versioned WebAuthn PRF plus ML-DSA companion proof construction and verification. | portable | Reference + usage | | @forgezero/runtime/otpauth | Parse and render otpauth URIs without binding enrolment to a UI framework. | portable | Reference + usage | | @forgezero/runtime/pipeline | Typed ordered application-pipeline execution with explicit evidence. | portable | Reference + usage | | @forgezero/runtime/custody-share | Threshold-share parsing, validation and reconstruction. | portable | Reference + usage | | @forgezero/runtime/custody-crypto | Hybrid ML-KEM-768 plus X25519 custody-share sealing and opening. | portable | Reference + usage |

Commands

bun add @forgezero/runtime — Install runtime contracts; import the required subpath so unused capabilities stay out of the bundle.

bun add @forgezero/runtime

@forgezero/runtime/query

Provider-neutral typed function contracts: decode untrusted input, run with caller-supplied services or storage, and strictly validate the result without coupling business logic to ForgeZero or ArangoDB. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  QueryContractError,
} from '@forgezero/runtime/query';

@forgezero/runtime/query — Define and implement a typed query

Decode untrusted input and validate output around injected storage/services rather than embedding a database query in the route adapter.

import {
  defineQuery,
  implementQuery,
} from '@forgezero/runtime/query';
import {
  T,
  type Static,
  typeboxQueryCodec,
} from '@forgezero/runtime/schema/typebox';

const OrderKey = T.Object({ orderKey: T.String({ minLength: 1 }) });
const Order = T.Object({ orderKey: T.String(), total: T.String() });
type OrderRow = Static<typeof Order>;
type Stores = { orders: { find(key: string): Promise<OrderRow | null> } };
declare const stores: Stores;

const findOrder = defineQuery({
  name: 'orders.find',
  input: typeboxQueryCodec(OrderKey),
  output: typeboxQueryCodec(T.Union([Order, T.Null()]))
});
export const runFindOrder = implementQuery(findOrder,
  (context: Stores, input) => context.orders.find(input.orderKey)
);

const order = await runFindOrder.execute(stores, { orderKey: 'ord_123' });

@forgezero/runtime/jobs

Background work that never overlaps itself, advances a cursor only on success, and can be paused and inspected. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  JobFenceLostError,
} from '@forgezero/runtime/jobs';

@forgezero/runtime/jobs — Use this entry point

This minimal executable use imports one concrete value from this exact entry point without a wildcard or package-root detour. Keep the value or values the application actually needs; the full named inventory remains directly above it.

import {
  JobFenceLostError,
} from '@forgezero/runtime/jobs';

export const selectedCapability = JobFenceLostError;

@forgezero/runtime/queue

Memory-only keyed work queue — awaited results, parallel across keys and strictly sequential within one; clustered callers atomically claim ownership in their own business store before submitting. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  QueueKeyStoppedError,
} from '@forgezero/runtime/queue';

@forgezero/runtime/queue — Use this entry point

import {
  QueueKeyStoppedError,
} from '@forgezero/runtime/queue';

export const selectedCapability = QueueKeyStoppedError;

@forgezero/runtime/outbox

Write the event with the record, deliver it after, in order per key with backoff and a dead-letter queue. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  DEFAULT_POLICY,
} from '@forgezero/runtime/outbox';

@forgezero/runtime/outbox — Use this entry point

import {
  DEFAULT_POLICY,
} from '@forgezero/runtime/outbox';

export const selectedCapability = DEFAULT_POLICY;

@forgezero/runtime/audit

Append-only records chained by hash, with a verifier that names the first altered entry. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  AuditChainError,
} from '@forgezero/runtime/audit';

@forgezero/runtime/audit — Use this entry point

import {
  AuditChainError,
} from '@forgezero/runtime/audit';

export const selectedCapability = AuditChainError;

@forgezero/runtime/backup

Encrypted, chunked, verified snapshots to object storage — and the restore that reads them back. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  BackupError,
} from '@forgezero/runtime/backup';

@forgezero/runtime/backup — Use this entry point

import {
  BackupError,
} from '@forgezero/runtime/backup';

export const selectedCapability = BackupError;

@forgezero/runtime/notify

Render a named template to text and HTML, escaped per part, refusing to send with a blank where a value should be. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  CHANNELS,
} from '@forgezero/runtime/notify';

@forgezero/runtime/notify — Use this entry point

import {
  CHANNELS,
} from '@forgezero/runtime/notify';

export const selectedCapability = CHANNELS;

@forgezero/runtime/notify/templates

The six transactional messages ForgeZero sends. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  TEMPLATES,
} from '@forgezero/runtime/notify/templates';

@forgezero/runtime/notify/templates — Use this entry point

import {
  TEMPLATES,
} from '@forgezero/runtime/notify/templates';

export const selectedCapability = TEMPLATES;

@forgezero/runtime/calendar

Billing periods computed from an anchor, working days, holidays and due dates. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  CalendarError,
} from '@forgezero/runtime/calendar';

@forgezero/runtime/calendar — Use this entry point

import {
  CalendarError,
} from '@forgezero/runtime/calendar';

export const selectedCapability = CalendarError;

@forgezero/runtime/totp

RFC 6238 TOTP on the existing HMAC — base32, an asymmetric window, and replay left to the caller. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  DEFAULT_DIGITS,
} from '@forgezero/runtime/totp';

@forgezero/runtime/totp — Use this entry point

import {
  DEFAULT_DIGITS,
} from '@forgezero/runtime/totp';

export const selectedCapability = DEFAULT_DIGITS;

@forgezero/runtime/passkey

Passkeys for sites that are not us. A vault-held credential is as unphishable as one in a security chip provided the RP ID check never slips — evil-example.com ends with example.com and is a different site. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  FLAG_BE,
} from '@forgezero/runtime/passkey';

@forgezero/runtime/passkey — Use this entry point

import {
  FLAG_BE,
} from '@forgezero/runtime/passkey';

export const selectedCapability = FLAG_BE;

@forgezero/runtime/phrase

BIP-39 recovery phrases, and the salted verifier that proves one without being able to reconstruct it. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  PHRASE_SALT_BYTES,
} from '@forgezero/runtime/phrase';

@forgezero/runtime/phrase — Use this entry point

import {
  PHRASE_SALT_BYTES,
} from '@forgezero/runtime/phrase';

export const selectedCapability = PHRASE_SALT_BYTES;

@forgezero/runtime/snp

Parse an AMD SEV-SNP attestation report at the firmware ABI offsets, and compare a TCB component by component so a microcode bump cannot mask a firmware downgrade. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  REPORT_BYTES,
} from '@forgezero/runtime/snp';

@forgezero/runtime/snp — Use this entry point

import {
  REPORT_BYTES,
} from '@forgezero/runtime/snp';

export const selectedCapability = REPORT_BYTES;

@forgezero/runtime/importers

Read secrets out of a .env, a CSV, or a Bitwarden or 1Password export — skipping what cannot be understood rather than guessing, and never putting a value in an error. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  IMPORT_FORMATS,
} from '@forgezero/runtime/importers';

@forgezero/runtime/importers — Use this entry point

import {
  IMPORT_FORMATS,
} from '@forgezero/runtime/importers';

export const selectedCapability = IMPORT_FORMATS;

@forgezero/runtime/openssh

OpenSSH wire encoding, so a derived ed25519 key becomes a line that pastes into authorized_keys. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  OpenSshError,
} from '@forgezero/runtime/openssh';

@forgezero/runtime/openssh — Use this entry point

import {
  OpenSshError,
} from '@forgezero/runtime/openssh';

export const selectedCapability = OpenSshError;

@forgezero/runtime/ssh-cert

OpenSSH certificates, so access expires instead of having to be hunted down. Takes a signing FUNCTION rather than a secret key, which is what lets the CA live in a vault that never hands it out. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  CERT_TYPE_HOST,
} from '@forgezero/runtime/ssh-cert';

@forgezero/runtime/ssh-cert — Use this entry point

import {
  CERT_TYPE_HOST,
} from '@forgezero/runtime/ssh-cert';

export const selectedCapability = CERT_TYPE_HOST;

@forgezero/runtime/slip10

SLIP-0010 derivation for ed25519, hardened-only — BIP-32 does not work on this curve and produces halves that do not correspond. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  HARDENED_OFFSET,
} from '@forgezero/runtime/slip10';

@forgezero/runtime/slip10 — Use this entry point

import {
  HARDENED_OFFSET,
} from '@forgezero/runtime/slip10';

export const selectedCapability = HARDENED_OFFSET;

@forgezero/runtime/identity

Hybrid Ed25519 + ML-DSA-65 request signing. One canonical string, so the compute agent that signs inside a guest and the API that verifies cannot drift — which two implementations of it certainly would. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  CLOCK_SKEW_SECONDS,
} from '@forgezero/runtime/identity';

@forgezero/runtime/identity — Use this entry point

import {
  CLOCK_SKEW_SECONDS,
} from '@forgezero/runtime/identity';

export const selectedCapability = CLOCK_SKEW_SECONDS;

@forgezero/runtime/schema

Validate against JSON Schema, restrict what a caller may declare, and describe a schema as a form. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  DEFAULT_RESTRICTIONS,
} from '@forgezero/runtime/schema';

@forgezero/runtime/schema — Restrict an untrusted JSON Schema before storing it

Tenant-supplied schemas are data, not executable code. Restriction rejects references, remote identifiers, unsupported keywords, excessive depth/size, and arrays without a bounded maxItems. Form metadata is derived from the accepted schema; write-only fields remain identifiable for secret handling.

import {
  restrictJsonSchema,
  describeJsonSchema,
  writeOnlyPaths,
} from '@forgezero/runtime/schema';

const schema = restrictJsonSchema({
  type: 'object', additionalProperties: false,
  properties: {
    recipients: { type: 'array', maxItems: 100, items: { type: 'string' } },
    apiKey: { type: 'string', title: 'API key', writeOnly: true }
  },
  required: ['apiKey']
});
const fields = describeJsonSchema(schema);
const secretFields = writeOnlyPaths(fields);

@forgezero/runtime/schema/typebox

The TypeBox validator behind that interface. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  T,
} from '@forgezero/runtime/schema/typebox';

@forgezero/runtime/schema/typebox — One TypeBox shape for runtime validation and static types

TypeBox is an optional peer. Its schema is JSON Schema, so the same restriction and form layer applies. The query codec validates both untrusted input and returned output; malformed values fail instead of being coerced.

import {
  T,
  type Static,
  parse,
  typeboxQueryCodec,
} from '@forgezero/runtime/schema/typebox';

const User = T.Object({
  userKey: T.String({ minLength: 1 }),
  roles: T.Array(T.String(), { maxItems: 32 })
}, { additionalProperties: false });
type User = Static<typeof User>;
const user: User = parse(User, unknownInput);
const codec = typeboxQueryCodec(User);

@forgezero/runtime/finance/discounts

Promotions as arithmetic over integer minor units. They never stack — one winner — and a percentage rounds down, because rounding a discount up gives away a unit of currency per invoice forever. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  DiscountError,
} from '@forgezero/runtime/finance/discounts';

@forgezero/runtime/finance/discounts — Use this entry point

import {
  DiscountError,
} from '@forgezero/runtime/finance/discounts';

export const selectedCapability = DiscountError;

@forgezero/runtime/finance/money

Exact amounts in minor units with the asset attached, so two currencies cannot be added. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  ASSETS,
} from '@forgezero/runtime/finance/money';

@forgezero/runtime/finance/money — Use this entry point

import {
  ASSETS,
} from '@forgezero/runtime/finance/money';

export const selectedCapability = ASSETS;

@forgezero/runtime/finance/tax

Which jurisdiction may tax a sale, who accounts for it, and the three ways to be zero that report differently. Rates are data. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  TREATMENTS,
} from '@forgezero/runtime/finance/tax';

@forgezero/runtime/finance/tax — Use this entry point

import {
  TREATMENTS,
} from '@forgezero/runtime/finance/tax';

export const selectedCapability = TREATMENTS;

@forgezero/runtime/finance/storage

Write an amount so it is both exact and sortable: an authoritative string, and a number that is only an index. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  SORT_FIELD,
} from '@forgezero/runtime/finance/storage';

@forgezero/runtime/finance/storage — Use this entry point

import {
  SORT_FIELD,
} from '@forgezero/runtime/finance/storage';

export const selectedCapability = SORT_FIELD;

@forgezero/runtime/realtime

Provider-neutral realtime audience, shard, event and delivery contracts. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  REALTIME_MAX_BATCH_BYTES,
} from '@forgezero/runtime/realtime';

@forgezero/runtime/realtime — Use this entry point

import {
  REALTIME_MAX_BATCH_BYTES,
} from '@forgezero/runtime/realtime';

export const selectedCapability = REALTIME_MAX_BATCH_BYTES;

@forgezero/runtime/passkey-hybrid

Versioned WebAuthn PRF plus ML-DSA companion proof construction and verification. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  PASSKEY_HYBRID_SUITE,
} from '@forgezero/runtime/passkey-hybrid';

@forgezero/runtime/passkey-hybrid — Use this entry point

import {
  PASSKEY_HYBRID_SUITE,
} from '@forgezero/runtime/passkey-hybrid';

export const selectedCapability = PASSKEY_HYBRID_SUITE;

@forgezero/runtime/otpauth

Parse and render otpauth URIs without binding enrolment to a UI framework. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  formatOtpAuth,
} from '@forgezero/runtime/otpauth';

@forgezero/runtime/otpauth — Use this entry point

import {
  formatOtpAuth,
} from '@forgezero/runtime/otpauth';

export const selectedCapability = formatOtpAuth;

@forgezero/runtime/pipeline

Typed ordered application-pipeline execution with explicit evidence. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  GIT_PROVIDERS,
} from '@forgezero/runtime/pipeline';

@forgezero/runtime/pipeline — Use this entry point

import {
  GIT_PROVIDERS,
} from '@forgezero/runtime/pipeline';

export const selectedCapability = GIT_PROVIDERS;

@forgezero/runtime/custody-share

Threshold-share parsing, validation and reconstruction. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  PROBE_BYTES,
} from '@forgezero/runtime/custody-share';

@forgezero/runtime/custody-share — Use this entry point

import {
  PROBE_BYTES,
} from '@forgezero/runtime/custody-share';

export const selectedCapability = PROBE_BYTES;

@forgezero/runtime/custody-crypto

Hybrid ML-KEM-768 plus X25519 custody-share sealing and opening. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.

import {
  deriveKey,
} from '@forgezero/runtime/custody-crypto';

@forgezero/runtime/custody-crypto — Use this entry point

import {
  deriveKey,
} from '@forgezero/runtime/custody-crypto';

export const selectedCapability = deriveKey;

1. Install, then import a subpath

There is no root export, and that is deliberate. import from "@forgezero/runtime" is meant to fail rather than resolve to whichever module happened to be listed first — a bare import that silently works is how a project ends up depending on the whole package to use one function. Every module is its own entry point, so a bundler includes what you imported and nothing else.

bun add @forgezero/runtime

import {
  parseAmount,
} from '@forgezero/runtime/finance/money';
import {
  createScheduler,
} from '@forgezero/runtime/jobs';

// This throws. It is supposed to.
// import { anything } from '@forgezero/runtime';

What is in it

Four groups. The service spine keeps work ordered after a response; record modules preserve evidence and recovery; identity modules provide portable security primitives; finance modules provide exact USD and multi-currency representation without importing a trading product.

SPINE      jobs        fenced scheduled work
           queue       parallel keys, sequential within one key
           outbox      transactional intent, bounded draining

RECORD     audit       append-only hash-chain verification
           backup      encrypted snapshots and verified restore
           calendar    periods, working days and due dates

IDENTITY   identity    hybrid Ed25519 + ML-DSA-65 signing
           passkey     WebAuthn and recovery primitives
           totp        bounded RFC 6238 verification
           notify      escaped named notification templates
           schema      restricted validation and form descriptors

FINANCE    money       exact minor-unit strings with currency and scale
           storage     exact authority plus coarse indexed projection
           discounts   bounded price adjustments
           tax         jurisdiction and accounting decisions

Optional peers — install only what your subpath needs

Nothing third-party is bundled. Vendoring a crypto library means a fix cannot reach you until this package republishes, so optional peer imports remain explicit. Most subpaths need nothing.

# identity and hybrid passkeys
bun add @noble/curves @noble/post-quantum

# schema/typebox — only if you validate with TypeBox
bun add @sinclair/typebox

Money is never a number

An amount is minor units as a bigint with its asset attached, so two currencies cannot be added by accident and a rounding mode is always stated. A database needs a second thing the bigint cannot give it — an ORDER BY that works — so finance/storage writes both: the authoritative string, and a lossy double used for sorting and range filters only. One ETH is 10^18 minor units and a signed 64-bit column overflows at about nine ETH, which is why the exact value is never the sortable one.

import {
  parseAmount,
  mulRate,
  formatAmount,
} from '@forgezero/runtime/finance/money';
import {
  toStored,
  rangeBounds,
} from '@forgezero/runtime/finance/storage';

const fee = mulRate(parseAmount('1250.00', 'USD'), '0.015', 'down');
formatAmount(fee);                    // '18.75' — never 18.749999999

const row = toStored(fee);
// { units: '1875', value: '18.75', asset: 'USD', sort: 18.75 }
//   units → what you pay out.  sort → what you ORDER BY.

rangeBounds(parseAmount('10', 'USD'), null);   // { gte: 10 }

Jobs — background work that never overlaps

The lock and the cursor store are interfaces, so this runs against a database, Redis, or nothing at all in a test.

import {
  createScheduler,
  defineJob,
  cursorJob,
} from '@forgezero/runtime/jobs';

Never setInterval

An interval fires whether or not the previous run finished, so work that takes longer than its period ends up running twice over the same data. The next run is scheduled after the current one completes, which makes the overlap impossible rather than unlikely.

const scheduler = createScheduler({
  jobs: [
    defineJob({ key: 'reap-sessions', label: 'Reap sessions', every: '5m', run: reap }),
    defineJob({ key: 'probe-providers', label: 'Probe providers', every: '30s', run: probe })
  ],
  lock: storeLock(lockStore)
});

scheduler.start();

A lease, not a mutex

A process that dies holding a mutex blocks its job for ever, and somebody clears it by hand at three in the morning. A lease expires on its own. The fence number rises each time the lock is granted, so a run that stalled past its lease and woke up finds its fence stale and stops before writing.

const lease = await lock.acquire('scan', 60_000);   // undefined if held
await lock.renew('scan', lease.fence, 60_000);      // false once superseded

The cursor advances only on a complete batch

Fetch a batch, process every item, then write the cursor — never per item and never before. If item three of ten throws, the whole batch is retried from the same position. That means process must be idempotent, and idempotent retries are strictly better than the alternative, which is records nobody ever looks at again.

cursorJob({
  key: 'rotate-provider-credentials',
  label: 'Rotate provider credentials',
  every: '1m',
  store: cursors,
  from: '0',
  fetch: (cursor) => dueRotations(cursor),
  process: (record) => rotateOnce(record)   // keyed and idempotent
});

Stop waits

Returning from stop() before in-flight work settles is how a deploy leaves a record half-written and the next boot finds state nothing explains. Timers are cleared, the abort signal fires so long runs can cut themselves short, and then it awaits what is still running.

await scheduler.stop();       // clears timers, aborts, awaits in-flight
scheduler.pause();            // stop scheduling, let in-flight finish
await scheduler.runNow('rotate-provider-credentials');

Status somebody can read during an incident

Last run, duration, result, error and consecutive failures per job. Without it a job that has been failing for a week looks exactly like a job that has been succeeding.

scheduler.status();
// [{ key: 'rotate-provider-credentials', state: 'idle', runs: 412,
//    lastDurationMs: 840, lastResult: { processed: 17, batches: 2 },
//    consecutiveFailures: 0, skippedLocked: 0 }]

Schema — validation you can also render

TypeBox is a peer dependency and optional. A project on Zod pulls none of it, because the interface is what the other packages depend on.

import {
  validate,
  describeForm,
} from '@forgezero/runtime/schema';

// only if you validate with TypeBox
bun add @sinclair/typebox

2. Validate

Query strings are entirely strings, so values are converted before checking — otherwise ?port=587 fails a schema expecting a number on a perfectly well-formed request.

import {
  typebox,
  T,
} from '@forgezero/runtime/schema/typebox';

const Config = T.Object(
  { host: T.String(), port: T.Integer() },
  { additionalProperties: false }
);

typebox.validate(Config, { host: 'mail', port: '587' });
// { ok: true, value: { host: 'mail', port: 587 } }

3. Render a form from it

describeForm turns a schema into flat, framework-agnostic fields. This is what lets an admin screen render provider credentials and security factors with no per-feature UI code.

typebox.describeForm(Config);
// [{ path: 'host', label: 'Host', kind: 'string', required: true }, ...]

The restrictions are a security boundary

A schema authored in your own source is trusted. One submitted by a tenant is not, and these limits are the only thing between the two. $ref would let a schema point validation at a document you do not control; unbounded depth is a denial-of-service; and an object accepting unknown properties is one that lets an unvalidated field ride into an envelope.

typebox.restrict(schema)

  $ref · $id · $defs      refused
  depth > 4               refused
  more than 100 fields    refused
  larger than 64 KiB      refused
  additionalProperties    must be false

writeOnly is the vault boundary

A field marked writeOnly is never returned to a browser. readableFields strips them at any depth, and writeOnlyPaths lists exactly what must be routed to secret storage instead.

const fields = typebox.describeForm(schema);

readableFields(fields);   // safe to serialise
writeOnlyPaths(fields);   // ['apiKey', 'nested.secret']

Adding another validator

Implement four functions. toJsonSchema is what keeps the ecosystem from fragmenting: stored config, the admin UI and the wire all speak JSON Schema, so a Zod project and a TypeBox project produce identical documents and either can read the other.

interface SchemaValidator<S> {
  name: string;
  validate(schema: S, value: unknown): ValidationResult;
  describeForm(schema: S): FormField[];
  toJsonSchema(schema: S): Record<string, unknown>;
  restrict(schema: S, limits?: Restrictions): S;
}

Full rendered documentation: https://www.forgezero.net/docs/runtime