@forgezero/runtime 0.1.6 → 0.1.7

package/README.md

@@ -1,155 +1,645 @@
+<!--
+  GENERATED FILE — do not edit.
+
+  Change scripts/generate-guides.ts or its typed sources, run `bun run guides`,
+  and commit the generator and rendered files together.
+-->
+
 # @forgezero/runtime
 
-**The machinery behind a request handler.** Background jobs that never overlap
-themselves, keyed queues, a transactional outbox, a hash-chained audit trail,
-templated mail, encrypted backups, schema validation, and money that is never a
-floating-point number.
+The machinery behind a request handler — jobs, queues, an outbox, a hash-chained audit trail, mail, backups, schema validation and exact money. 44 public modules, each imported on its own.
+
+## Global package root and supported runtimes
+
+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. The global base/root import is @forgezero/runtime. Every public import or command is listed below; the documentation inventory is checked in both directions against package.json exports.
 
-Thirty-four public modules. Each is its own entry point, so you install one package and
-your bundler includes only what you imported.
+```text
+import * as root from '@forgezero/runtime';
+```
+
+## Commands
 
-```bash
+bun add @forgezero/runtime — Install runtime contracts; import the required subpath so unused capabilities stay out of the bundle.
+
+```text
 bun add @forgezero/runtime
 ```
 
-```ts
+## @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.
+
+```text
+import * as api from '@forgezero/runtime/query';
+```
+
+## @forgezero/runtime/jobs
+
+Background work that never overlaps itself, advances a cursor only on success, and can be paused and inspected.
+
+```text
+import * as api from '@forgezero/runtime/jobs';
+```
+
+## @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.
+
+```text
+import * as api from '@forgezero/runtime/queue';
+```
+
+## @forgezero/runtime/outbox
+
+Write the event with the record, deliver it after, in order per key with backoff and a dead-letter queue.
+
+```text
+import * as api from '@forgezero/runtime/outbox';
+```
+
+## @forgezero/runtime/audit
+
+Append-only records chained by hash, with a verifier that names the first altered entry.
+
+```text
+import * as api from '@forgezero/runtime/audit';
+```
+
+## @forgezero/runtime/backup
+
+Encrypted, chunked, verified snapshots to object storage — and the restore that reads them back.
+
+```text
+import * as api from '@forgezero/runtime/backup';
+```
+
+## @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.
+
+```text
+import * as api from '@forgezero/runtime/notify';
+```
+
+## @forgezero/runtime/notify/templates
+
+The six transactional messages ForgeZero sends.
+
+```text
+import * as api from '@forgezero/runtime/notify/templates';
+```
+
+## @forgezero/runtime/calendar
+
+Billing periods computed from an anchor, working days, holidays and due dates.
+
+```text
+import * as api from '@forgezero/runtime/calendar';
+```
+
+## @forgezero/runtime/compliance
+
+Screening as a decision record — tiers, rules and lists, failing closed when a list is unreachable.
+
+```text
+import * as api from '@forgezero/runtime/compliance';
+```
+
+## @forgezero/runtime/totp
+
+RFC 6238 TOTP on the existing HMAC — base32, an asymmetric window, and replay left to the caller.
+
+```text
+import * as api from '@forgezero/runtime/totp';
+```
+
+## @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.
+
+```text
+import * as api from '@forgezero/runtime/passkey';
+```
+
+## @forgezero/runtime/phrase
+
+BIP-39 recovery phrases, and the salted verifier that proves one without being able to reconstruct it.
+
+```text
+import * as api from '@forgezero/runtime/phrase';
+```
+
+## @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.
+
+```text
+import * as api from '@forgezero/runtime/snp';
+```
+
+## @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.
+
+```text
+import * as api from '@forgezero/runtime/importers';
+```
+
+## @forgezero/runtime/openssh
+
+OpenSSH wire encoding, so a derived ed25519 key becomes a line that pastes into authorized_keys.
+
+```text
+import * as api from '@forgezero/runtime/openssh';
+```
+
+## @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.
+
+```text
+import * as api from '@forgezero/runtime/ssh-cert';
+```
+
+## @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.
+
+```text
+import * as api from '@forgezero/runtime/slip10';
+```
+
+## @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.
+
+```text
+import * as api from '@forgezero/runtime/identity';
+```
+
+## @forgezero/runtime/schema
+
+Validate against JSON Schema, restrict what a caller may declare, and describe a schema as a form.
+
+```text
+import * as api from '@forgezero/runtime/schema';
+```
+
+## @forgezero/runtime/schema/typebox
+
+The TypeBox validator behind that interface.
+
+```text
+import * as api from '@forgezero/runtime/schema/typebox';
+```
+
+## @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.
+
+```text
+import * as api from '@forgezero/runtime/finance/discounts';
+```
+
+## @forgezero/runtime/finance/money
+
+Exact amounts in minor units with the asset attached, so two currencies cannot be added.
+
+```text
+import * as api from '@forgezero/runtime/finance/money';
+```
+
+## @forgezero/runtime/finance/venues
+
+Trading venues, market types and symbols as data — spot, margin and futures behind one order model.
+
+```text
+import * as api from '@forgezero/runtime/finance/venues';
+```
+
+## @forgezero/runtime/finance/ledger
+
+Double-entry postings and derived balances. A hold is a posting, not a lock — the queue does the ordering.
+
+```text
+import * as api from '@forgezero/runtime/finance/ledger';
+```
+
+## @forgezero/runtime/finance/commission
+
+Profit net of flows, a high-water mark, the tier split and the referral share of our income.
+
+```text
+import * as api from '@forgezero/runtime/finance/commission';
+```
+
+## @forgezero/runtime/finance/rates
+
+What an asset is worth in USD, and how old that answer is. A peg never ages; a quote always does.
+
+```text
+import * as api from '@forgezero/runtime/finance/rates';
+```
+
+## @forgezero/runtime/finance/transfers
+
+Deposits and withdrawals as ordered pipelines, with screening reserved at position zero.
+
+```text
+import * as api from '@forgezero/runtime/finance/transfers';
+```
+
+## @forgezero/runtime/finance/chain
+
+Which chains exist, their confirmation depth by value band, assets and explorers — as data an admin edits.
+
+```text
+import * as api from '@forgezero/runtime/finance/chain';
+```
+
+## @forgezero/runtime/finance/custody
+
+Derive CREATE2 deposit addresses and EIP-712 custody digests — arithmetic over a seed and a salt, needing no credential and no node.
+
+```text
+import * as api from '@forgezero/runtime/finance/custody';
+```
+
+## @forgezero/runtime/finance/derive
+
+Declare a field ForgeZero generates rather than the tenant supplying: BIP-44 path arithmetic, and the choice of who is capable of generating the key.
+
+```text
+import * as api from '@forgezero/runtime/finance/derive';
+```
+
+## @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.
+
+```text
+import * as api from '@forgezero/runtime/finance/tax';
+```
+
+## @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.
+
+```text
+import * as api from '@forgezero/runtime/finance/storage';
+```
+
+## @forgezero/runtime/realtime
+
+Provider-neutral realtime audience, shard, event and delivery contracts.
+
+```text
+import * as api from '@forgezero/runtime/realtime';
+```
+
+## @forgezero/runtime/passkey-hybrid
+
+Versioned WebAuthn PRF plus ML-DSA companion proof construction and verification.
+
+```text
+import * as api from '@forgezero/runtime/passkey-hybrid';
+```
+
+## @forgezero/runtime/otpauth
+
+Parse and render otpauth URIs without binding enrolment to a UI framework.
+
+```text
+import * as api from '@forgezero/runtime/otpauth';
+```
+
+## @forgezero/runtime/pipeline
+
+Typed ordered application-pipeline execution with explicit evidence.
+
+```text
+import * as api from '@forgezero/runtime/pipeline';
+```
+
+## @forgezero/runtime/finance/chain-addresses
+
+Chain-address derivation records and validation independent of a node provider.
+
+```text
+import * as api from '@forgezero/runtime/finance/chain-addresses';
+```
+
+## @forgezero/runtime/finance/chain-deposits
+
+Provider-neutral deposit observation, confirmation and credit transitions.
+
+```text
+import * as api from '@forgezero/runtime/finance/chain-deposits';
+```
+
+## @forgezero/runtime/finance/chain-withdrawals
+
+Provider-neutral withdrawal approval, broadcast and finality transitions.
+
+```text
+import * as api from '@forgezero/runtime/finance/chain-withdrawals';
+```
+
+## @forgezero/runtime/finance/chain-reconcile
+
+Deterministic reconciliation between chain observations and durable transfer state.
+
+```text
+import * as api from '@forgezero/runtime/finance/chain-reconcile';
+```
+
+## @forgezero/runtime/finance/market
+
+Market order, fill and quote contracts independent of any exchange adapter.
+
+```text
+import * as api from '@forgezero/runtime/finance/market';
+```
+
+## @forgezero/runtime/custody-share
+
+Threshold-share parsing, validation and reconstruction.
+
+```text
+import * as api from '@forgezero/runtime/custody-share';
+```
+
+## @forgezero/runtime/custody-crypto
+
+Hybrid ML-KEM-768 plus X25519 custody-share sealing and opening.
+
+```text
+import * as api from '@forgezero/runtime/custody-crypto';
+```
+
+## 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.
+
+```text
+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' });
+```
+
+## 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.
+
+```text
+bun add @forgezero/runtime
+
 import { parseAmount } from '@forgezero/runtime/finance/money';
 import { createScheduler } from '@forgezero/runtime/jobs';
 
-// There is no root export. `import from '@forgezero/runtime'` is meant to fail
-// rather than resolve to whichever module happened to be listed first.
+// This throws. It is supposed to.
+// import { anything } from '@forgezero/runtime';
 ```
 
 ## What is in it
 
-| | |
-|---|---|
-| **Spine** | `query` `jobs` `queue` `outbox` |
-| **Record** | `audit` `backup` `compliance` `calendar` |
-| **Identity** | `identity` `totp` `notify` `notify/templates` `schema` `schema/typebox` |
-| **Finance** | `finance/money` `finance/storage` `finance/ledger` `finance/commission` `finance/rates` `finance/transfers` `finance/tax` `finance/chain` `finance/custody` `finance/derive` `finance/venues` `finance/binance` |
+Four groups. The service spine is what a process needs to keep working after the response is sent; the record keeps evidence; the finance modules are the ones that must never be approximated. Nothing here knows what your product does — a tenant binds its own business rules to these, it does not fork them.
+
+```text
+SPINE      jobs        scheduled work submitted through the common queue
+           queue       awaited result; parallel keys, sequential within one
+           outbox      business-owned durability, drained through handlers
+
+RECORD     audit       append-only, hash-chained, names the first altered row
+           backup      encrypted, chunked, verified snapshots + the restore
+           compliance  screening as a decision record, failing closed
+           calendar    billing periods, working days, holidays, due dates
+
+IDENTITY   identity    hybrid Ed25519 + ML-DSA-65 request signing
+           totp        RFC 6238, asymmetric window, replay rejected
+           notify      named templates to text and HTML, escaped per part
+           schema      JSON Schema validation, restricted and describable
+
+FINANCE    money       minor units with the asset attached
+           storage      the same amount, exact AND sortable in a database
+           ledger      double-entry postings and derived balances
+           commission  profit net of flows, high-water mark, referral split
+           rates       what an asset is worth, and how old that answer is
+           transfers   deposits and withdrawals as ordered pipelines
+           tax         who may tax a sale, and who accounts for it
+           chain       chains, assets, confirmation depth by value band
+           custody     CREATE2 deposit addresses and EIP-712 digests
+           derive      declare a key ForgeZero generates, not the tenant
+           venues      trading venues, market types and symbols as data
+           binance     Binance behind the venue adapter
+```
 
-None of it knows what your product does. You bind your own rules to these; you
-do not fork them.
+## Optional peers — install only what your subpath needs
 
-## Typed function queries
+Nothing third-party is bundled. Vendoring a crypto library means a fix for it never reaches you until this package is republished, so the imports stay real and the dependency stays yours. Most subpaths need nothing; four of them do, and the failure is a plain module-not-found rather than a silently wrong result.
 
-`query` binds typed input/output codecs to an ordinary function and any context
-you choose. It has no database or ForgeZero realm dependency. Inputs may decode
-wire values; outputs are checked strictly so a wrong handler result cannot be
-coerced into looking correct.
+```text
+# most subpaths: nothing to add
 
-```ts
-import { defineQuery, implementQuery } from '@forgezero/runtime/query';
-import { typeboxQueryCodec, T } from '@forgezero/runtime/schema/typebox';
+# finance/custody  — CREATE2 and EIP-712 digests
+bun add @noble/hashes
 
-const contract = defineQuery({
-  name: 'invoice.by-reference',
-  input: typeboxQueryCodec(T.Object({ reference: T.String() })),
-  output: typeboxQueryCodec(T.Object({ total: T.String() }))
-});
+# identity         — hybrid post-quantum signing
+bun add @noble/curves @noble/post-quantum
 
-const findInvoice = implementQuery(contract, async (services: MyServices, input, { signal }) =>
-  services.invoices.find(input.reference, { signal })
-);
+# schema/typebox   — only if you validate with TypeBox
+bun add @sinclair/typebox
 ```
 
-## One reusable async queue
+## 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.
+
+```text
+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.
 
-`queue` is deliberately memory-only: it accepts a function, returns that
-function's value through a Promise, runs one key sequentially, and runs
-different keys in parallel. Persistence and cluster ownership remain in the
-business layer that knows what a pending request means; ForgeZero uses an
-ArangoDB unique claim, while another caller may use any database or no database.
+rangeBounds(parseAmount('10', 'USD'), null);   // { gte: 10 }
+```
 
-```ts
-import { createQueue } from '@forgezero/runtime/queue';
+## The contracts ship with it
 
-// Default admission is 60% of reported logical CPUs (with one reserved).
-// Use `width` for an exact ceiling, or an explicit dynamic resource policy:
-const queue = createQueue({ resources: { percent: 60, reserve: 1, max: 32 } });
-const task = queue.run('tenant-a:wallet-7', transfer, amount, destination);
-const receipt = await task.result;
+The Solidity behind `finance/custody` is in the package rather than in a repository you have to go find. `finance/custody` computes the counterfactual address; `DepositFactory` is what makes that address real on first sweep, and `ColdVault` is the M-of-N EIP-712 approval the digests are built for. Address arithmetic without the contract that honours it is half an answer.
 
-queue.pauseKey('tenant-a:wallet-7');
-queue.resumeKey('tenant-a:wallet-7');
-queue.stopKey('tenant-a:wallet-7'); // running finishes; pending is rejected
-queue.startKey('tenant-a:wallet-7');
-queue.cancel(task.id);               // pending task only
-await queue.stop(30_000);            // close intake and drain all work
+```text
+node_modules/@forgezero/runtime/contracts/src/
+  DepositProxy.sol      lazily deployed at first sweep — no key, no gas per address
+  DepositFactory.sol    CREATE2, salt opaque to the contract
+  ColdVault.sol         M-of-N, signatures ordered by ascending signer
+  SafeTransferLib.sol   tokens that do not return a bool
 ```
 
-Different async keys overlap immediately. CPU-heavy JavaScript does not become
-multi-core merely by entering a queue: put that handler in Bun/standard Workers
-and await the Worker result from the queue.
+## Jobs — background work that never overlaps
 
-Jobs accept intervals down to seconds or a local wall-clock schedule with an
-IANA timezone and weekday filter. `overlap: 'wait'` (the default) schedules the
-next run after completion; `overlap: 'skip'` keeps clock cadence and drops a tick
-when the same key is still busy. Same-key overlap is never allowed.
+The lock and the cursor store are interfaces, so this runs against a database, Redis, or nothing at all in a test.
 
-```ts
-defineJob({
-  key: 'tenant:acme:invoice',
-  label: 'Monthly invoice preparation',
-  schedule: { timezone: 'Asia/Kolkata', time: '00:00:15', weekdays: [1] },
-  overlap: 'skip',
-  run: async ({ signal }) => generateInvoices({ signal })
+```text
+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.
+
+```text
+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();
 ```
 
-## Three things worth knowing before you use it
+## A lease, not a mutex
 
-**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. `finance/storage` writes the same amount twice — the
-authoritative string, and a lossy double used for `ORDER BY` only. One ETH is
-10^18 minor units and a signed 64-bit column overflows around nine ETH, which is
-why the exact value is never the sortable one.
+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.
 
-```ts
-const fee = mulRate(parseAmount('1250.00', 'USD'), '0.015', 'down');
-formatAmount(fee);   // '18.75' — never 18.749999999
-toStored(fee);       // { units: '1875', value: '18.75', asset: 'USD', sort: 18.75 }
+```text
+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.
+
+```text
+cursorJob({
+  key: 'scan-deposits',
+  label: 'Scan deposits',
+  every: '15s',
+  store: cursors,
+  from: '0',
+  fetch: (cursor) => fetchBlocks(cursor),
+  process: (transfer) => credit(transfer)   // keyed, so a retry is free
+});
 ```
 
-**A scheduler, never `setInterval`.** An interval fires whether or not the last
-run finished, so work slower than its period runs twice over the same data. The
-next run is scheduled after the current one completes. The lock is a lease with
-a fence, not a mutex — a process that dies does not block its job for ever.
+## Stop waits
 
-**The cursor advances only on a complete batch.** Fetch, process every item,
-then write the cursor — never per item, never before. Item three of ten throwing
-retries the whole batch from the same position, which means `process` must be
-idempotent, and idempotent retries beat records nobody ever looks at again.
+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.
 
-## Optional peers
+```text
+await scheduler.stop();       // clears timers, aborts, awaits in-flight
+scheduler.pause();            // stop scheduling, let in-flight finish
+await scheduler.runNow('scan-deposits');
+```
+
+## Status somebody can read during an incident
 
-Nothing third-party is bundled — vendoring a crypto library means a fix for it
-never reaches you until this package republishes. Most subpaths need nothing:
+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.
 
-```bash
-bun add @noble/hashes                      # finance/custody
-bun add @noble/curves @noble/post-quantum  # identity
-bun add @sinclair/typebox                  # schema/typebox
+```text
+scheduler.status();
+// [{ key: 'scan-deposits', state: 'idle', runs: 412,
+//    lastDurationMs: 840, lastResult: { processed: 17, batches: 2 },
+//    consecutiveFailures: 0, skippedLocked: 0 }]
 ```
 
-## The Solidity ships with it
+## Schema — validation you can also render
 
-`finance/custody` computes counterfactual CREATE2 deposit addresses; the
-contracts that make those addresses real are in the tarball, not in a repository
-you have to go find.
+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.
 
+```text
+import { validate, describeForm } from '@forgezero/runtime/schema';
+
+// only if you validate with TypeBox
+bun add @sinclair/typebox
 ```
-node_modules/@forgezero/runtime/contracts/src/
-  DepositProxy.sol     deployed lazily at first sweep — no key, no gas per address
-  DepositFactory.sol   CREATE2, salt opaque to the contract
-  ColdVault.sol        M-of-N EIP-712, signatures ordered by ascending signer
+
+## 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.
+
+```text
+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.
+
+```text
+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.
+
+```text
+typebox.restrict(schema)
+
+  $ref · $id · $defs      refused
+  depth > 4               refused
+  more than 100 fields    refused
+  larger than 64 KiB      refused
+  additionalProperties    must be false
 ```
 
-Full documentation: **https://www.forgezero.net/docs/runtime**
+## writeOnly is the vault boundary
 
-## Licence
+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.
+
+```text
+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.
+
+```text
+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;
+}
+```
 
-MIT. Part of [ForgeZero](https://www.forgezero.net) — secrets, attested compute and
-deploys — and usable entirely on its own, with no ForgeZero account.
+Full rendered documentation: https://www.forgezero.net/docs/runtime

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@forgezero/runtime",
-  "version": "0.1.6",
+  "version": "0.1.7",
 	"type": "module",
   "publishConfig": {
     "access": "public",
@@ -191,7 +191,7 @@
 		"prepublishOnly": "bun run check && bun run build"
 	},
 	"dependencies": {
-		"@forgezero/access": "^0.1.0"
+		"@forgezero/access": "^0.1.3"
 	},
 	"peerDependencies": {
 		"@noble/ciphers": "^2.2.0",