refactor(global): one vocabulary on the wire, in the ledger and in the code

.github/pull_request_template.md

@@ -4,6 +4,6 @@
 
 ## Checklist
 
-- [ ] The PR title is a conventional commit with a workspace scope, such as `feat(inference): ...`. It becomes the squash commit and the changelog entry.
+- [ ] The PR title is a conventional commit with a workspace scope, such as `feat(reasoning): ...`. It becomes the squash commit and the changelog entry.
 - [ ] `pnpm check` passes locally, with every file at 100% coverage.
 - [ ] I've signed the Contributor License Agreement (the CLA bot asks on your first PR).

.oxlintrc.json

@@ -106,7 +106,7 @@
   },
   "overrides": [
     {
-      "files": ["packages/workflow-engine/src/program-pool/**", "primitives/computation/measure/**"],
+      "files": ["packages/workflow-engine/src/program-pool/**", "capabilities/computation/measure/**"],
       "rules": {
         "no-restricted-imports": "off"
       }

CLAUDE.md

@@ -8,14 +8,14 @@
 - `packages/api`: the API (`@beonauto/api`), a Hono app that answers every request, with problem documents, the `Origin` and `Host` checks, authentication and the operation routes
 - `packages/identity`: API keys, the local-mode rule and the key command (`@beonauto/identity`)
 - `packages/*`: the server's libraries (`@beonauto/*`), including the ledger
-- `primitives/*`: runtime adapters and planned capabilities. `inference` implements reasoning functions, `orchestration` implements workflows and `computation` implements computation functions. Interaction, prediction, recall (in `recollection`) and Dream currently have design notes only.
+- `capabilities/*`: the runtime adapters of the brain's capabilities. `reasoning` implements reasoning functions, `interaction` interaction functions, `computation` computation functions, `recall` recall functions and `coordination` workflows; `prediction` has a design note only.
 - `TODO.md`: setup work that is still outstanding
 
 Use the vocabulary in [Brain terminology](docs/concepts/terminology.md) in product text and domain code. A brain reasons, interacts, predicts, recalls and computes. Workflows coordinate those functions. The five function categories are Reasoning, Interaction, Prediction, Recall and Computation, in that order; coordination is a capability, not a sixth function type. A reasoning function has a prompt. A workflow or function definition is reusable; a run executes it against particular inputs.
 
-The product is not live and has no stored data, so nothing keeps an old name beside a new one: no alias, no mapping, no anchor for an old heading and no test that an old name or an old record still works. Brain terminology is the one vocabulary. The API's wire names today, `primitive` with the values `inference`, `computation`, `recollection` and `orchestration`, `spec` and `execution`, are what the code says until they are renamed in one pass. The workflow engine's run-log formats are internal replay formats and follow their own rule, which its README sets out under [State formats](packages/workflow-engine/README.md#state-formats). `Primitive` is the contract a capability package implements for the runtime, and is named for what it is.
+The product is not live and has no stored data, so nothing keeps an old name beside a new one: no alias, no mapping, no anchor for an old heading and no test that an old name or an old record still works, and a local database made before a rename is deleted. Brain terminology is the one vocabulary, on the wire, in the ledger, in the package names and in the code: a definition has a `type`, `reasoning`, `interaction`, `computation`, `recall` or `workflow`, and a run has a `run_id`; a record whose own `type` names it, such as a ledger event, carries `definition_type`. The workflow engine's run-log formats are internal replay formats and follow their own rule, which its README sets out under [State formats](packages/workflow-engine/README.md#state-formats). `Capability` is the contract a capability package implements for the runtime, and is named for what it is.
 
-Domain code names a definition for its resource: `WorkflowDefinition`, and `ReasoningFunctionDefinition`, `InteractionFunctionDefinition`, `PredictionFunctionDefinition`, `RecallFunctionDefinition` or `ComputationFunctionDefinition` once that function type is implemented. The function kinds are `reason`, `interact`, `predict`, `recall` and `compute`; a workflow is not one of them. A parsed source document is a `...DefinitionDocument`, and a factory of a runtime adapter is `make...Adapter`. Apart from the wire names and the packages named after them, **inference** names model execution and provider terms, **orchestration** the coordination machinery, **agent** an actual actor, such as an external coding agent, and **memory** the retention of information.
+Domain code names a definition for its resource: `WorkflowDefinition`, and `ReasoningFunctionDefinition`, `InteractionFunctionDefinition`, `PredictionFunctionDefinition`, `RecallFunctionDefinition` or `ComputationFunctionDefinition` once that function type is implemented. A definition's `type` is its one discriminator: `reasoning`, `interaction`, `prediction`, `recall` and `computation` for the five function types, and `workflow`, which is not a function type. A parsed source document is a `...DefinitionDocument`, and a factory of a runtime adapter is `make...Adapter`. **inference** names a model call and its provider's terms, **agent** an actual actor, such as an external coding agent, and **memory** the retention of information.
 
 ## Commands
 
@@ -47,6 +47,6 @@ Run one package's gate with `pnpm turbo run lint typecheck test --filter @beonau
 - Do not write comments. Make the code read like English through names and ordering.
 - Tests live next to the code as `*.test.ts`, test behaviour through the public interface, and prefer injected fakes over mocks.
 - A package with more than about 12 source files groups them one level deep, in folders named after concepts that hold fewer than about 15 files each, with tests beside the code they test. Nothing new goes directly under `src`, and there are no barrel files: a package's entry points are the few paths its `exports` map names (`src/index.ts`, `src/testing/index.ts` and, where its README says why, a subpath) and its commands (the server's `src/main.ts` and `dev.ts`, the identity package's `src/key-command.ts`).
-- Commits are conventional with a scope named after a package or primitive folder (`feat(server): ...`, `docs(inference): ...`); `global`, `deps`, `ci` and `release` are the other scopes.
+- Commits are conventional with a scope named after a package or capability folder (`feat(server): ...`, `docs(reasoning): ...`); `global`, `deps`, `ci` and `release` are the other scopes.
 - `pnpm check` must pass before you finish. Fixing a problem is a change, so rerun it.
 - When something fails, assume your change broke it. What is on `main` passed the same gate.

CONTRIBUTING.md

@@ -45,15 +45,15 @@ The preview opens under `/docs/`. Read [Documentation contributions](docs/contri
 
 ## Commits and pull requests
 
-- **Commits are [conventional](https://www.conventionalcommits.org) with a scope,** for example `feat(inference): render the liquid body against the brain`.
-  - The scope is a package or primitive folder name (`server`, `config`, `ledger`, `inference`, ...), or one of `global`, `deps`, `ci` and `release`.
+- **Commits are [conventional](https://www.conventionalcommits.org) with a scope,** for example `feat(reasoning): render the liquid body against the brain`.
+  - The scope is a package or capability folder name (`server`, `config`, `ledger`, `reasoning`, ...), or one of `global`, `deps`, `ci` and `release`.
   - `pnpm commit` walks you through it, and a git hook checks every message.
 - **The pull request title matters most.** Pull requests are squash-merged, so the title becomes the commit on `main` and the changelog entry. CI checks it too.
 - **CI must pass, then the pull request merges through the merge queue.** CI runs the full `pnpm check`, builds and smoke-tests the container, and audits the workflows. Keep each pull request to one change.
 
 ## Adding a function or workflow adapter
 
-Function and workflow implementations live in `primitives/<name>`. The shared `Primitive` interface is their low-level runtime adapter contract, including custom extension adapters. It is not a product category. Each implemented adapter is a workspace package:
+Function and workflow implementations live in `capabilities/<name>`. The shared `Capability` interface is their low-level runtime adapter contract, including custom extension adapters. It is not a product category. Each implemented adapter is a workspace package:
 
 - `package.json` named `@beonauto/<name>`, with `"exports": { ".": "./src/index.ts" }` and `lint`, `typecheck` and `test` scripts. Copy them from `packages/config`.
 - `README.md` saying what the adapter runs and how it reads and writes the ledger.

TODO.md

@@ -36,8 +36,7 @@ Setup work that couldn't be finished yet, and why.
 
 ## Local databases
 
-- [ ] **Delete every local ledger made before several triggers.** The host keeps one row a trigger now, in a `workflow_subscriptions` keyed by brain, workflow and trigger, and does not migrate the old table, since nothing is live. Delete `packages/server/.data/ledger.db` for `pnpm dev`, or the file `LEDGER_FILE` names, or the PostgreSQL database `DATABASE_URL` names. Kept, such a database fails every round of the host's follower: no trigger starts a run, no listening run is offered an event and no waiting call is answered.
-- [ ] **Delete every local ledger made before an interaction function named the tool it sends through.** A request's record and its delivery facts changed shape, the open requests moved to `open_requests_4` and the conversations the brain reads have a table of their own, and nothing reads the old shape, since nothing is live. Delete `packages/server/.data/ledger.db` for `pnpm dev`, or the file `LEDGER_FILE` names, or the PostgreSQL database `DATABASE_URL` names. Kept, such a database holds runs that wait on requests no attempt delivers and no listing shows.
+- [ ] **Delete every local ledger made before the one vocabulary.** The streams, event types and fields of definitions, runs and run logs took the product's words, the projections of runs took their next versions, and the host's tables key a run by `run_key` and its reaction backlog by `run_id`, and nothing reads the old names, since nothing is live. Delete `packages/server/.data/ledger.db` for `pnpm dev`, or the file `LEDGER_FILE` names, or the PostgreSQL database `DATABASE_URL` names. Kept, such a database shows no definition and reads its run logs as runs; the host's tables, made with `CREATE TABLE IF NOT EXISTS`, keep their old `run_id` columns, so the server starts and then every read and write of the host's run tables fails and no workflow run can be recorded, and the due, timer and deferred-start sweeps die on every pass.
 
 ## Tests
 

primitives/computation/README.md → capabilities/computation/README.md

@@ -1,22 +1,22 @@
 # @beonauto/computation
 
-The implementation of computation functions. A computation function is a program in jq with schemas for its input and output; a run applies the program to its input and answers with exactly one output, the same for the same input on every host of the same image, within bounds on its work, the values it builds, its time and its memory. Its API identifier and package name are `computation`. [Decision 0005](../../docs/decisions/0005-computation-functions.md) says why it exists and how it is bounded.
+The implementation of computation functions. A computation function is a program in jq with schemas for its input and output; a run applies the program to its input and answers with exactly one output, the same for the same input on every host of the same image, within bounds on its work, the values it builds, its time and its memory. [Decision 0005](../../docs/decisions/0005-computation-functions.md) says why it exists and how it is bounded.
 
 User documentation is [Computation function format](../../docs/reference/computation-format.md), published at [on.auto/docs](https://on.auto/docs/): the document, the dialect, the number rules, the endings and the bounds. Update it alongside behaviour changes.
 
 ## The document
 
-`parseComputationDocument(source)` reads a document with the shared reader of [`@beonauto/specs/document`](../../packages/specs/README.md#reading-function-documents) and gives a `ComputationFunctionDefinitionDocument`: an optional `description`, the `language`, `jq`, the compiled `input.schema` and `output.schema` when the document has them, the `program` and the line it starts on. The front matter's keys are `description`, `language`, `input.schema` and `output.schema`; every other key, `model`, `config`, `tools`, `output.format` and `input.default` among them, is an issue at its line, and the message for empty front matter names `the language`. A schema is compiled with the reader's compiler and validates values nested at most 512 levels.
+`parseComputationDocument(source)` reads a document with the shared reader of [`@beonauto/definitions/document`](../../packages/definitions/README.md#reading-function-documents) and gives a `ComputationFunctionDefinitionDocument`: an optional `description`, the `language`, `jq`, the compiled `input.schema` and `output.schema` when the document has them, the `program` and the line it starts on. The front matter's keys are `description`, `language`, `input.schema` and `output.schema`; every other key, `model`, `config`, `tools`, `output.format` and `input.default` among them, is an issue at its line, and the message for empty front matter names `the language`. A schema is compiled with the reader's compiler and validates values nested at most 512 levels.
 
 The program is compiled with the evaluator of [`@beonauto/workflow-engine/dsl`](../../packages/workflow-engine/README.md#programs) and the dialect of `src/document/program-dialect.ts`, which refuses, each with its reason, `now`, `env`, `$ENV`, `input`, `inputs`, `input_filename`, `input_line_number`, `$__loc__`, `builtins`, `localtime`, `strflocaltime`, `debug`, `stderr`, `halt`, `halt_error`, `label` and `break`, and binds no variable, so every `$name` the program does not bind is refused too. The evaluator's issues carry spans into the body, which become lines of the document: `Line 4: The program nests more than 128 levels deep`. Parsing checks everything a run can be refused for without its input.
 
 ## A run
 
-`makeComputationFunctionAdapter({ pool, deadlineMs })` makes the primitive for `makeSpecOperations`; the server gives it a `ProgramPool` of the engine, with `COMPUTATION_WORKERS` workers. `deadlineMs` is 10,000 unless a test gives less, and is the primitive's `longestExecutionMs`. The primitive reaches nothing outside and changes nothing there, calls no tools, and is stopped when its call is cancelled. An execution:
+`makeComputationFunctionAdapter({ pool, deadlineMs })` makes the capability for `makeDefinitionOperations`; the server gives it a `ProgramPool` of the engine, with `COMPUTATION_WORKERS` workers. `deadlineMs` is 10,000 unless a test gives less, and is the capability's `longestAnyRunMs`. The capability reaches nothing outside and changes nothing there, calls no tools, and is stopped when its call is cancelled. A run:
 
 1. refuses an input nested deeper than 512 levels, and one its input schema refuses, as `invalid_input` with the schema's pointers;
 2. asks the pool to run the program on the input with `computationLimits`, `liftedLimits` of the engine with the work bound, in `exactly one` mode, with the deadline counted from the start of the run and an output of at most `mostOutputBytes`, 1 MiB less 256 bytes for the record;
-3. names the checked worker, `checkedWorker` of `@beonauto/specs/json-schema`, for every run, with the output schema as the request's context or `null` when the definition has none, so every run of computation and recall functions is served by one worker module and the pool never lets go of a warm worker to start another module's (200 jobs at once on 4 permits took 118 to 197 ms on one module, against 3,495 to 5,103 ms alternating between two; see [the engine](../../packages/workflow-engine/README.md#the-workers-of-the-pool-measured)); with a schema, the worker that runs the program also checks the output against the schema, under the run's deadline, and the thread that serves requests never waits on the check: a 1 MiB output against a recursive schema had taken 1,038 ms there;
+3. names the checked worker, `checkedWorker` of `@beonauto/definitions/json-schema`, for every run, with the output schema as the request's context or `null` when the definition has none, so every run of computation and recall functions is served by one worker module and the pool never lets go of a warm worker to start another module's (200 jobs at once on 4 permits took 118 to 197 ms on one module, against 3,495 to 5,103 ms alternating between two; see [the engine](../../packages/workflow-engine/README.md#the-workers-of-the-pool-measured)); with a schema, the worker that runs the program also checks the output against the schema, under the run's deadline, and the thread that serves requests never waits on the check: a 1 MiB output against a recursive schema had taken 1,038 ms there;
 4. turns the outcome into the run's ending (`src/run/run-outcome.ts`):
 
 | Outcome of the pool                                                           | Ending                                                                                                                  |
@@ -64,4 +64,4 @@ The pool keeps a worker between runs, so a run costs its work and the copies of
 
 ## Source
 
-`src/index.ts` is the entry point and `src/testing/index.ts` the entry point of the test support. `src/document` holds the document: its type, the front matter's keys, the dialect and parsing. `src/run` holds a run: its bounds, the input's checks, the call of the pool and the endings. `src/primitive` holds the primitive, whose guide is the public reference page, served to agents as `computation-function`. `src/testing` holds the example and what the tests share.
+`src/index.ts` is the entry point and `src/testing/index.ts` the entry point of the test support. `src/document` holds the document: its type, the front matter's keys, the dialect and parsing. `src/run` holds a run: its bounds, the input's checks, the call of the pool and the endings. `src/capability` holds the capability, whose guide is the public reference page, served to agents as `computation-function`. `src/testing` holds the example and what the tests share.

primitives/computation/measure/burst.ts → capabilities/computation/measure/burst.ts

@@ -1,4 +1,4 @@
-import { checkedWorker } from '@beonauto/specs/json-schema';
+import { checkedWorker } from '@beonauto/definitions/json-schema';
 import { programPool, type ProgramRequest } from '@beonauto/workflow-engine/dsl';
 
 import { computationBounds } from '../src/run/run-bounds.ts';

primitives/computation/measure/example.ts → capabilities/computation/measure/example.ts

@@ -1,4 +1,4 @@
-import { mostInputBytes } from '@beonauto/specs';
+import { mostInputBytes } from '@beonauto/definitions';
 import { jsonBytesOf } from '@beonauto/workflow-engine/dsl';
 import { Result } from 'effect';
 

primitives/computation/measure/runs.ts → capabilities/computation/measure/runs.ts

@@ -1,6 +1,6 @@
 import { setTimeout } from 'node:timers/promises';
 
-import { checkedWorker } from '@beonauto/specs/json-schema';
+import { checkedWorker } from '@beonauto/definitions/json-schema';
 import { idleWorkerMs, programPool, type ProgramPool, type ProgramRequest } from '@beonauto/workflow-engine/dsl';
 
 import { computationDialect } from '../src/document/program-dialect.ts';

primitives/computation/package.json → capabilities/computation/package.json

@@ -15,8 +15,8 @@
     "measure": "node measure.ts"
   },
   "dependencies": {
+    "@beonauto/definitions": "workspace:*",
     "@beonauto/operations": "workspace:*",
-    "@beonauto/specs": "workspace:*",
     "@beonauto/workflow-engine": "workspace:*",
     "effect": "catalog:"
   },