Glossary

Short definitions of the vocabulary this repository uses with a meaning of its own. Each entry names one term, defines it in a sentence, and links to the page that explains it — the glossary is a map, not the territory. The entries are kept in order and checked with blong-dev glossary.

adapter — A component that exposes an external system as a high-level handler API and hides the protocol it speaks. See adapter and the adapter pattern.

API definition — The TypeBox schema or OpenAPI spec a handler derives its contract from, and the source of truth for validation and docs. See API and OpenAPI.

chain — The ordered list of steps a test handler returns, executed in whatever order their data allows. See chain.

checkpoint — A progress point a handler reports to explain the shape a run took, drawn as a note on the semantic-log diagram. See checkpoint.

codec — A handler group an adapter lists in its imports to serialize the messages of a protocol and match its responses. See codec.

deployment granularity — How many processes a suite becomes when it is deployed, chosen by a kustomize profile rather than by the code. See kustomize, the pattern and the rationale.

expected errors — Errors a test declares up front, matched by $meta.expect instead of failing the run. See expected errors.

gateway — The public JSON-RPC and REST surface of a suite, which validates and documents the API and carries little business logic. See gateway.

handler — A single function in a single file, named as a subjectObjectPredicate triple. See naming and the handler pattern.

handler group — The folder of handlers that forms one realmname.foldername namespace inside a layer. See layer and the realm pattern.

handler-test continuum — The model in which handlers and tests share one step execution and differ only by whether assertions run. See the rationale and chain.

injected library function — A helper a handler group shares through the handler proxy, keyed by a name that is not a triple. See the handler pattern.

intent — A positional CLI word that selects the configuration blocks, layers and lifetime of a run. See intents and the rationale.

kukum — The API that scaffolds and introspects realms, suites, layers, handlers and models. See kukum and the kukum pattern.

kustomize — The realm that turns the registry of a loaded suite into a kustomize tree and a BlongDeployment. See kustomize.

layer — A named group of handlers inside a realm, such as adapter, orchestrator or gateway. See layer and the layer pattern.

library realm — A realm every calling process carries its own copy of, such as blong-core and blong-access. See the rationale and realm.

memory file — A markdown note an agent keeps for frictions, todos and decisions, written through blong-dev memory. See memory files.

model system — The browser mechanism that generates Browse, New, Open and Report pages from an IModelSpec. See the model system and schema based UI.

orchestrator — The component that coordinates adapters and defines an API namespace, and the place business logic lives. See orchestrator and the pattern.

prose cross reference — A source comment or doc sentence that carries a title and a reference to the entry holding the reasoning, so the prose stays short and the details are maintained once. See memory and the memory pattern.

RBAC — Role-based access control — roles, capabilities and actions — evaluated over the resource graph. See RBAC and the RBAC pattern.

realm — A business domain boundary that groups layers and can be deployed on its own. See realm and the realm pattern.

resource graph — The generic subject-predicate-object triples behind blong-core, used to relate and query entities. See the resource graph.

retired id — An entry id whose entry was closed, pruned or renumbered; it keeps its number in the Retired ledger, so a stale reference warns with its successor. See retired id.

schema sync — The declarative database management that reconciles tables, constraints and procedures from TypeScript and YAML. See schema sync.

semantic log — Logging that mints an id per record, so the full detail is reached on demand instead of grepped. See semantic log.

session — A long-lived authenticated connection, with refresh tokens and audit. See sessions.

suite — The top-level unit that groups realms and defines the deployment. See suite and the suite pattern.

thenable proxy — A proxy whose property read records a dependency and returns a promise for the result of that step. See chain.

third-party service — A service a suite's adapter implies and its deployment brings — a database, a broker — declared by a descriptor under services/ and dialled by an abstract name through an ExternalName alias; the resolved form is a backingService. See kustomize.

upgrade — The intent that brings a deployed database up to date: it activates the schema sync and production seeds an adapter declares for it — schema.sync and schema.seed in the blong-server db adapter — and exits when done. See intents.

validation — Schema checks the framework derives from the exported Handler type of a handler and runs at the boundary. See the validation pattern.

watch — Hot reload of handlers, codecs, stored procedures and config without dropping connections. See watch.