API_SURFACE.md

@async/db API Surface Ledger

This file is the generated review ledger for semantic API contract features. It is current-state contract documentation, not a changelog or tutorial.

Async DB Package Exports

Contract: @async/db.package

Config

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
config.env	env.var and env.secret config references for runtime values and redacted secrets	public	stable	active		docs
config.git	git.remotes and git.mirror config for Git-backed content resources	beta	preview	active		docs
config.profiles	profile/profiles named config policy bundles for reviewable startup profiles	public	stable	active		docs

Exports

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
export.client	@async/db/client tiny HTTP client, REST and GraphQL calls, batching, and cache helpers	public	stable	active		docs
export.config	@async/db/config defineConfig, env helpers, and profile config authoring	public	stable	active		docs
export.git	@async/db/git GitHub remote and Git file source helpers for Git-backed resources	beta	preview	active		docs
export.hono	@async/db/hono optional Hono integration without required Hono dependency	beta	preview	active		docs
export.json	@async/db/json compatibility exports for @async/json store helpers, state utilities, versioning, recovery, and encryption	public	stable	active		docs
export.kv	@async/db/kv optional generic KV store adapter boundary	beta	preview	active		docs
export.postgres	@async/db/postgres optional Postgres JSONB envelope storage and existing table mapping	beta	preview	active		docs
export.postgres.compat	@async/db/postgres/compat low-level Postgres driver adapters and legacy bridges	beta	preview	active		docs
export.redis	@async/db/redis optional Redis-like KV adapter and RedisJSON store adapter boundary	beta	preview	active		docs
export.root	@async/db root runtime, schema, server, sync, operations, eventResource, and helpers	public	stable	active		docs
export.schema	@async/db/schema authoring helpers: collection, document, field, derived fields, and files	public	stable	active		docs
export.sqlite	@async/db/sqlite optional SQLite store, Git mirror, and existing table mapping	beta	preview	active		docs
export.sqlite.compat	@async/db/sqlite/compat low-level SQLite driver adapters and legacy bridges	beta	preview	active		docs
export.vite	@async/db/vite optional Vite integration and browser cache options	beta	preview	active		docs

Async DB CLI

Contract: @async/db.cli

Diagnostics

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
cli.doctor	async-db doctor and check report schema/data drift, production readiness, and usage findings	public	stable	active		docs

Generate

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
cli.generate.hono	async-db generate hono creates a Hono and SQLite starter from the current contract	beta	preview	active		docs

Inspection

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
cli.integrate	async-db integrate inspects SQLite and Postgres apps and generates dry-run importers	beta	preview	active		docs
cli.usage	async-db usage scan emits production-oriented source usage manifests	beta	preview	active		docs

Lifecycle

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
cli.lifecycle	async-db promote, status, reseed, backup, and restore manage local lifecycle state	beta	preview	active		docs

Operations

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
cli.operations	async-db operations builds operation registries, refs, and operation contracts	public	stable	active		docs

Project

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
cli.init	async-db init scaffolds data-first, schema-first, source-file, and content templates with Node or Deno workflows	public	stable	active		docs
cli.sync	async-db sync loads sources, validates schema, writes generated metadata/types, and refreshes runtime state	public	stable	active		docs
cli.types	async-db types generates TypeScript declarations with watch and explicit output support	public	stable	active		docs

Runtime

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
cli.runtime-write	async-db create writes one record through the package runtime path	public	stable	active		docs

Schema

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
cli.schema	async-db schema prints, infers, validates, manifests, bundles, unbundles, and migrates schemas	public	stable	active		docs

Server

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
cli.serve	async-db serve starts the local writable development API and viewer	public	dev-only	active		docs

Viewer

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
cli.viewer	async-db viewer manifest renders viewer manifest contracts	public	generated	active		docs

Async DB Runtime And Integration APIs

Contract: @async/db.runtime

Client

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
runtime.http-client	createDbClient direct REST/GraphQL calls, automatic batching, dedupe, and cache options	public	stable	active		docs

Content

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
runtime.content-mdx	files() content resources with MDX component inventory and allow-list diagnostics	beta	preview	active		docs
runtime.git-sources	Git-backed JSON, JSONC, Markdown, and MDX resources sync through mirrors with Git control APIs	beta	preview	active		docs

Integrations

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
runtime.optional-stores	SQLite, Postgres, KV, and Redis-like store adapter helper boundaries remain optional	beta	preview	active		docs
runtime.postgres-integration	Postgres inspection, primary-key identity metadata, JSONB envelope storage, existing table mapping, and compat adapters	beta	preview	active		docs
runtime.sqlite-integration	SQLite inspection, primary-key identity metadata, Async DB-owned SQLite storage, existing table mapping, and compat adapters	beta	preview	active		docs

Lifecycle

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
runtime.lifecycle-file	db.lifecycle.jsonc machine-managed promotion facts merged into config.lifecycle	beta	preview	active		docs

Migration

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
runtime.schema-migration	review-first schema declaration migration reports and generated output plans	beta	preview	active		docs

Observability

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
runtime.audit-trail	resource audit trails for successful runtime writes with optional value capture	beta	preview	active		docs

Operations

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
runtime.operations	operation manifests, registered handlers, refs, hashing, and readiness checks	public	stable	active		docs

Runtime

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
runtime.database	openDb, Db, resource-property proxies, db._ controls, collection/document APIs, identity keys, append-only resources, eventResource helper, lifecycle, close, and ETag preconditions	public	stable	active		docs
runtime.lifecycle	createDbRuntime, reloadDb, watchDbSources, and createDbRequestHandler for custom local servers	public	stable	active		docs

Schema

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
runtime.schema-authoring	trusted local schema helpers including collection identity, log metadata, document, field.bytes, files, and derived fields	public	stable	active		docs
runtime.schema-loading	loadDbSchema, validators, computed field resolvers, metadata-only loading, and schema locator support	public	stable	active		docs

Storage

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
runtime.json-store	JSON store helpers use @async/json engine boundaries for identity keys, append-only policy, bytes validation, advisory locks, atomic writes, versioning, crash recovery, encryption, and sidecar state	public	stable	active		docs

Testing

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
runtime.memory-fs	createMemoryFs for tests and programmatic schema/runtime loading	public	stable	active		docs

Async DB HTTP Surface

Contract: @async/db.http

Auth

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
http.authorization	server.authorize(context) gates REST, viewer, schema, manifest, GraphQL, Falcor, events, health, and operations	beta	preview	active		docs

Discovery

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
http.root-discovery	GET / root discovery returns HTML or JSON links by request headers	public	dev-only	active		docs

Falcor

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
http.falcor	Falcor-compatible record routes where enabled	beta	preview	active		docs

Graphql

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
http.graphql	Dependency-free GraphQL subset supports queries, mutations, compound key inputs, aliases, variables, batching, and introspection	public	stable	active		docs

Health

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
http.health	GET /health reports uptime, schema, diagnostics, and state-dir writability	beta	preview	active		docs

Operations

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
http.operations	Registered operation execution and client-safe operation ref routes	public	stable	active		docs

Rest

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
http.rest-batching	REST batching preserves per-item result shape and errors	public	stable	active		docs
http.rest-resources	REST resources under /db support single-id routes, compound __key routes, JSON reads/writes, ETag, If-Match, If-None-Match, and bulk route behavior	public	stable	active		docs

Viewer

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
http.viewer	Built-in local viewer, server-sent events, manifest routes, and exposure settings	public	dev-only	active		docs

Async DB Generated Contracts

Contract: @async/db.generated

Inspection

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
generated.integration-report	integrate inspect db.integrationReport artifacts for SQLite/Postgres adoption	beta	generated	active		docs
generated.usage	usage scan db.usageManifest source-scan artifact	beta	generated	active		docs

Internal

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
generated.state-internal	.db/state and store-private metadata are internal generated runtime output	internal	internal	active		docs

Migration

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
generated.schema-migration-report	schema migrate inspect db.schemaMigrationReport artifacts	beta	generated	active		docs

Operations

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
generated.operations	operations.build outputs, server operation registry, and client-safe refs/contracts	public	generated	active		docs

Schema

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
generated.schema	.db/schema.generated.json and schemaOutFile/outputs.schemaManifest generated identity, log, bytes, schema, REST, and GraphQL metadata	public	generated	active		docs

Types

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
generated.types	.db/types/index.d.ts and types.commitOutFile generated TypeScript declarations with resource proxies and identity key maps	public	generated	active		docs

Viewer

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
generated.viewer-manifest	viewerManifestOutFile and outputs.viewerManifest viewer contracts with identity and field metadata	public	generated	active		docs

Async DB Config Surface

Contract: @async/db.config

Config

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
config.lifecycle	db.lifecycle.jsonc merged lifecycle config and production doctor findings	beta	preview	active		docs
config.mock	mock delay and error behavior with production skips and doctor reporting	public	stable	active		docs
config.operations	operations registry, refs, contract output, source directory, accept-ref policy, and strict readiness	public	stable	active		docs
config.outputs	outputs generated locations for state, types, manifests, operations, and starters	public	stable	active		docs
config.protocols	rest, graphql, and falcor protocol exposure and request/response toggles	public	stable	active		docs
config.schema	schema validation, inference, unknown-field policy, and behavior toggles	public	stable	active		docs
config.server	server host, port, base path, exposure, trace, watcher, viewer, events, authorize, and local behavior	public	stable	active		docs
config.stores	stores, JSON durability, resource identity/log schemas, bytes fields, sources, routes, defaults, seed, audit, and UI metadata	beta	preview	active		docs
config.types	types generation options including output paths, committed copy, comments, readonly properties, and runtime helpers	public	stable	active		docs

Async DB Internal Boundaries

Contract: @async/db.boundary

Execution

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
boundary.trusted-local-code	.schema.js, db.config.js, source readers, and manifest hooks are trusted local code and not sandboxed public APIs	internal	internal	active		docs

Generated

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
boundary.generated-state	.db state, hashes, and store-private metadata are internal and not app import surfaces	internal	internal	active		docs

Source

Feature	Title	Release	Stability	Lifecycle	Replacement	Docs
boundary.features-internal	src/features modules are internal unless re-exported and declared	internal	internal	active		docs
boundary.protocol-internals	src/rest, src/graphql, and src/web helper modules are internal while route behavior is public	internal	internal	active		docs
boundary.tests-scripts-examples	test helpers, scripts, and example internals are private unless documented as runnable hooks	internal	internal	active		docs

Supported Surfaces

Contract	Hash	Features
@async/db.boundary	sha256:d15e9a2f8062afd31a383024b68f09a99544a8093733c239c385204e8a00275c	boundary.features-internal, boundary.generated-state, boundary.protocol-internals, boundary.tests-scripts-examples, boundary.trusted-local-code
@async/db.cli	sha256:58832a8d2bf2b682a914de1a1f38a4ec65071d8e89dbdb3e546dc75d3ea44b15	cli.doctor, cli.generate.hono, cli.init, cli.integrate, cli.lifecycle, cli.operations, cli.runtime-write, cli.schema, cli.serve, cli.sync, cli.types, cli.usage, cli.viewer
@async/db.config	sha256:b5d6553f8fbe3409bfcb2e52f44c6fccdc7e7aa2e0fb3da8bebe56a1860fe440	config.lifecycle, config.mock, config.operations, config.outputs, config.protocols, config.schema, config.server, config.stores, config.types
@async/db.generated	sha256:015f1b90667f6527b41870a7f9487af6a10f074ce990ede07cd7acde2a289f9a	generated.integration-report, generated.operations, generated.schema, generated.schema-migration-report, generated.state-internal, generated.types, generated.usage, generated.viewer-manifest
@async/db.http	sha256:192b1b35fdaa7ff929fcf299721310166c5b90d7922abb19141fa936cf60fc01	http.authorization, http.falcor, http.graphql, http.health, http.operations, http.rest-batching, http.rest-resources, http.root-discovery, http.viewer
@async/db.package	sha256:c55338a292cd136e1c1516d5e42711372e4ac61bab4f8622dca16ca66b5e671d	config.git, export.client, export.config, export.git, export.hono, export.json, export.kv, export.postgres, export.postgres.compat, export.redis, export.root, export.schema, export.sqlite, export.sqlite.compat, export.vite
@async/db.runtime	sha256:408c1e1e67d77b5adde387dd5b699ff87765e5ceac80f342d68aa16a47323467	runtime.audit-trail, runtime.content-mdx, runtime.database, runtime.git-sources, runtime.http-client, runtime.json-store, runtime.lifecycle, runtime.lifecycle-file, runtime.memory-fs, runtime.operations, runtime.optional-stores, runtime.postgres-integration, runtime.schema-authoring, runtime.schema-loading, runtime.schema-migration, runtime.sqlite-integration