Application runtime

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

Install

Portable runtime primitives for queries, jobs, events, schemas and finance. 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.

bun add @forgezero/runtime

Keep frontend feedback tied to the current account

Use the same headless controllers in any frontend. Subscribe from your framework, reset on account changes and dispose when the view is destroyed. A failed mutation remains unknown unless the server explicitly rejected it.

import {
  AsyncController,
  NotificationCenter,
} from '@forgezero/runtime/client';

const feedback = new NotificationCenter();
const load = new AsyncController<string[]>();
const unsubscribe = load.subscribe(state => {
  if (state.error) feedback.error(state.error);
});
await load.run('read', async signal => {
  signal.throwIfAborted();
  return ['First item'];
}, () => ({ message: 'Could not load items.' }));

// On account change, abort old work and clear account-owned feedback.
load.reset();
feedback.syncOwner(1);
// On view teardown:
unsubscribe();
load.dispose();
feedback.dispose();

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' });

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);

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 unknownInput: unknown = { userKey: 'user-1', roles: ['reader'] };
const user: User = parse(User, unknownInput);
const codec = typeboxQueryCodec(User);

Choose an entry point

Import the capability your application needs. Each package ships TypeScript declarations. Backend-only entries must stay out of browser bundles.

| Import or command | Use it for | Runtime | |---|---|---| | @forgezero/runtime/client | Framework-neutral frontend controllers for asynchronous ownership, notifications, loading and transient drafts; no DOM, storage or UI dependency. | Portable | | @forgezero/runtime/bootstrap-inventory | Reviewed generation-one host, guest, image-attestation and immutable bundle intent contracts. Desired inventory never proves runtime readiness. | Portable | | @forgezero/runtime/metal-resource-evidence | Bounded native bootstrap guest resource challenges and signed read-only inspection receipts. Nominal resources must be observed independently before readiness; this protocol never provisions a guest. | Portable | | @forgezero/runtime/guest-enrolment | Closed native guest enrollment requests and realm-bound identity responses for the API and Agent, without Project or deployment-wide Vault authority. | Portable | | @forgezero/runtime/agent-observation | Signed Agent host-evidence schemas for OS, version, runtime support and usable resource measurements; observations never substitute for nominal resource reservations. | Portable | | @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 | | @forgezero/runtime/jobs | Background work that never overlaps itself, advances a cursor only on success, and can be paused and inspected. | Portable | | @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 | | @forgezero/runtime/outbox | Write the event with the record, deliver it after, in order per key with backoff and a dead-letter queue. | Portable | | @forgezero/runtime/audit | Append-only records chained by hash, with a verifier that names the first altered entry. | Portable | | @forgezero/runtime/backup | Encrypted, chunked, verified snapshots to object storage — and the restore that reads them back. | Portable | | @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 | | @forgezero/runtime/notify/templates | The six transactional messages ForgeZero sends. | Portable | | @forgezero/runtime/calendar | Billing periods computed from an anchor, working days, holidays and due dates. | Portable | | @forgezero/runtime/totp | RFC 6238 TOTP on the existing HMAC — base32, an asymmetric window, and replay left to the caller. | Portable | | @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 | | @forgezero/runtime/phrase | BIP-39 recovery phrases, and the salted verifier that proves one without being able to reconstruct it. | Portable | | @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 | | @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 | | @forgezero/runtime/openssh | OpenSSH wire encoding, so a derived ed25519 key becomes a line that pastes into authorized_keys. | Portable | | @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 | | @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 | | @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 | | @forgezero/runtime/vault-runtime | Provider-neutral algorithms for non-exportable Vault runtime records: passwords, DEK/KEK operations, HMAC/JWS, Ed25519/secp256k1 and Ethereum/Solana address encoding. | Portable | | @forgezero/runtime/managed-vault-socket | Closed alias-only Unix-socket request and response schemas shared by the managed Vault SDK and the Agent; applications never send remote Vault coordinates. | Portable | | @forgezero/runtime/lifecycle | Framework-neutral blue/green drain coordination with exact release fencing and separately proved HTTP, WebSocket, durable-job and schedule counters. | Portable | | @forgezero/runtime/schema | Validate against JSON Schema, restrict what a caller may declare, and describe a schema as a form. | Portable | | @forgezero/runtime/schema/typebox | The TypeBox validator behind that interface. | Portable | | @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 | | @forgezero/runtime/finance/money | Exact amounts in minor units with the asset attached, so two currencies cannot be added. | Portable | | @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 | | @forgezero/runtime/finance/units | Exact provider-neutral unit coordinates, integer atoms and reviewed rational conversions for sales and inventory without floating-point quantities. | Portable | | @forgezero/runtime/finance/pricing | Deterministic exact line pricing that snapshots unit quantities, ordered adjustments and inclusive or exclusive tax without selecting a promotion or touching inventory. | Portable | | @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 | | @forgezero/runtime/realtime | Provider-neutral realtime audience, shard, event and delivery contracts. | Portable | | @forgezero/runtime/operation | Revisioned surface, operation-state and bounded redacted operation-log contracts. | Portable | | @forgezero/runtime/passkey-hybrid | Versioned WebAuthn PRF plus ML-DSA companion proof construction and verification. | Portable | | @forgezero/runtime/otpauth | Parse and render otpauth URIs without binding enrolment to a UI framework. | Portable | | @forgezero/runtime/pipeline | Typed ordered application-pipeline execution with explicit evidence. | Portable | | @forgezero/runtime/custody-share | Threshold-share parsing, validation and reconstruction. | Portable | | @forgezero/runtime/custody-crypto | Hybrid ML-KEM-768 plus X25519 custody-share sealing and opening. | Portable |

Related packages

Add only the packages needed by your application.

| Package | Purpose | Guide | |---|---|---| | @forgezero/vault | Exact Deployment binding reads through a managed Agent or signed API credential. | Read guide | | @forgezero/access | Typed route, principal, factor, RBAC and request-pipeline contracts. | Read guide | | @forgezero/providers | Typed external providers with priority, health and classified fallback. | Read guide | | @forgezero/agent | Operator CLI and managed-node agent for bootstrap, deploy and lifecycle. | Read guide |

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