create-flowdular 0.2.4 → 0.2.5

package/agent-template/.ai/skills/business-agent-design/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: business-agent-design
+description: >-
+  Ship a module-owned business agent with defineAgent, an exact tool ceiling,
+  tenant provider binding, retained revisions, and tests. Use for business
+  automation delivered by a module, not for sandbox coding specialists.
+roles:
+  - agentic-engineer
+  - backend-engineer
+  - module-executor
+when: A module should provide a ready business agent that tenants can configure and run.
+---
+
+# Design a module-owned business agent
+
+`defineAgent()` describes a business agent shipped by a module. It is the same
+kind of business agent that appears in `agents.core`, but its behavior is owned
+by module source. It is not a sandbox specialist, coding role, `.ai` skill, or
+permission grant. Read `docs/adr/0007-module-owned-agents.md` and the approved
+module spec before editing.
+
+If a required tool is missing, pause this phase and hand it off as a separate
+`agent-tool-design` task. A business agent can use only registered tools.
+
+## Ownership split
+
+The module owns:
+
+- the stable module id and agent key;
+- name, description, instructions, and positive definition revision;
+- the maximum exact tool allowlist;
+- maximum steps, timeout, temperature, and output-token limits.
+
+The tenant owns a separate binding in `agents.core`:
+
+- provider connection and model;
+- active or paused state;
+- an enabled-tool subset that can narrow the module allowlist;
+- optimistic binding revision and the resulting executable revision.
+
+Never put provider ids, model ids, credentials, tenant ids, or tenant-specific
+instructions in module source. The Agents UI presents module behavior as
+read-only and lets an authorized tenant manager configure only the binding.
+
+## Define and register
+
+Declare `agents.core` in both `spec/module.yaml` and `module.json` dependencies,
+and add `"@flowdular/sdk/modules/agents": "workspace:*"` to `package.json`. Keep the
+import server-only.
+
+```ts
+// src/agent/agents.ts
+import { defineAgent } from '@flowdular/sdk/modules/agents/server';
+
+export const catalogCurator = defineAgent({
+	moduleId: 'catalog.core',
+	key: 'catalog-curator',
+	definitionRevision: 1,
+	name: 'Catalog curator',
+	description: 'Reviews and normalizes catalog records.',
+	instructions:
+		'Review the requested catalog records. Use only the tools available to you.',
+	allowedTools: ['catalog.item.create', 'catalog.item.list'],
+	limits: {
+		maxSteps: 8,
+		timeoutMs: 120_000,
+		temperature: 0.2,
+		maxOutputTokens: 4_096,
+	},
+});
+
+export const catalogBusinessAgents = [catalogCurator] as const;
+```
+
+```ts
+// src/platform.ts, during createServerComposition
+context.agentDefinitions.register(catalogBusinessAgents);
+```
+
+Registration happens during composition. The platform seals
+`agentDefinitions` before any module `start()` hook. A malformed definition,
+duplicate id, wildcard tool, registration after sealing, code downgrade, or
+same-revision content drift fails boot. Do not catch and hide these errors.
+
+`defineAgent()` derives the opaque id
+`module-agent:<moduleId>:<key>`, validates the fields, sorts the exact tool ids,
+and freezes the result. Callers do not construct or parse the derived id.
+
+## Authority is an intersection
+
+For a module-owned agent, the tools visible to a run are exactly:
+
+```text
+code allowedTools
+  intersect tenant binding enabledTools
+  intersect invocation toolGrants
+  intersect registered tools allowed by the actor's saved ceiling
+  intersect registered tools allowed by the actor's live permissions
+```
+
+Every id is exact. An omitted grant means no tools. `*`, prefixes, and implicit
+all-tools behavior are invalid. Every tool independently declares its
+`requiredPermissions`; instructions and skills never grant authority. A scope
+revoked after enqueue is rechecked before the tool body runs. The model never
+receives `PlatformCapabilityRegistry` or direct service, repository, database,
+shell, filesystem, or credential access.
+
+The module allowlist is a permanent ceiling for that definition revision. The
+tenant may reduce it, and each caller may reduce it again. A caller cannot
+broaden it. Keep the list to the smallest surface needed for the stated job.
+
+Mutating tools also follow the durable idempotency contract in
+`agent-tool-design`. Do not add a write tool to a business agent until the tool
+has its target-side ledger, transaction, replay test, and
+`idempotencyProtection: 'target-ledger'` declaration.
+
+## Revisions and workflows
+
+Increase `definitionRevision` whenever any executable module-owned content
+changes: instructions, display copy, allowed tools, or limits. Never reuse a
+revision with different content and never decrement it.
+
+Binding a provider or model, changing enabled tools, or reconciling a higher
+module definition creates a new immutable tenant executable revision. Runs and
+published workflows pin that executable revision, not the code definition or
+mutable binding revision. Old retained revisions and audit evidence survive an
+upgrade or module removal. A removed module-owned agent becomes unavailable for
+new work.
+
+An unconfigured module agent remains visible but cannot run or be published in
+a workflow. Do not choose a provider or model automatically to make setup look
+complete.
+
+## Spec and files
+
+The approved spec states:
+
+- the business outcome and refusal conditions;
+- each exact tool and required permission;
+- that tenant binding cannot broaden the module ceiling;
+- unavailable, unconfigured, revision, and module-removal behavior where
+  relevant.
+
+Typical files are:
+
+- `src/agent/agents.ts` for definitions;
+- `src/agent/tools.ts` for module tools;
+- `src/platform.ts` for both registry calls;
+- `tests/business-agents.test.ts` and `tests/agent-tools.test.ts`;
+- `spec/module.yaml`, `module.json`, and `package.json` for dependencies and
+  the coordinated version bump.
+
+## Tests
+
+The business module proves:
+
+1. The definition has the expected derived id, ownership, revision, limits,
+   and exact sorted tool ceiling, and is frozen.
+2. Every allowed tool is registered by the module or a declared dependency.
+
+The shared `agents.core` integration suite proves:
+
+1. A tenant binding can reduce tools but cannot add one outside the code
+   ceiling.
+2. A run without an invocation grant or required live scope never calls the
+   tool body and records a denial.
+3. Two tenants can bind different providers, models, and tool subsets without
+   seeing each other's binding or runs.
+4. A higher definition revision retains the old executable revision; a
+   downgrade and same-revision drift refuse startup.
+5. Module absence blocks new runs while retained run and workflow evidence
+   remains readable.
+
+Use the module's isolated test provider for persistence tests. The end-to-end access intersection
+belongs in `modules/agents/tests`, while a business module proves its own
+definition and tool behavior locally. Do not edit `agents.core` merely to
+duplicate its platform contract tests. Run the module tests, typecheck, spec
+and module validation, then `pnpm verify` before delivery.
+
+## Refuse
+
+- Treating a sandbox coding specialist as a business agent definition.
+- Letting a tenant edit module-owned instructions or the code tool ceiling.
+- Wildcard tools, tenant ids in model input, or authority derived from prompts.
+- Code-pinned provider connections, models, credentials, or secrets.
+- Registration outside `createServerComposition` or after registry sealing.
+- A write tool without target-side durable idempotency.
+- Reusing a definition revision after changing executable content.

package/agent-template/.ai/skills/cli-extension/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: cli-extension
+description: >-
+  Add a module-owned CLI command through commands.json and defineCliExtension,
+  with the namespace, risk, approval, and dry-run rules the runner enforces.
+roles:
+  - backend-engineer
+  - module-executor
+  - reviewer
+when: A module needs an operator command (status, export, grant, verify) reachable as pnpm flowdular <namespace> <action>.
+---
+
+# Add a module CLI command
+
+Examples to copy: `modules/agents/src/cli/{commands.json,index.ts}` (read plus a `localOnly` verifier) and `modules/auth/src/cli/{commands.json,index.ts}` (`process` with dry run, `destructive` with confirmation). Small template: `.ai/examples/customer-cli-extension`.
+
+## 1. Declare the capability
+
+`module.json`: add `"cli"` to `capabilities` and
+
+```json
+"cli": { "catalog": "src/cli/commands.json", "entry": "src/cli/index.ts" }
+```
+
+`packages/contracts/schemas/module.schema.json` requires the `cli` block when the capability is present and the capability when the block is present. The spec `capabilities` list gets `cli` too.
+
+## 2. Catalog: `src/cli/commands.json`
+
+```json
+{
+	"protocolVersion": 1,
+	"moduleId": "inventory.core",
+	"commands": [
+		{
+			"path": ["inventory", "export"],
+			"capability": {
+				"id": "inventory.export",
+				"version": 1,
+				"summary": "Export tenant-scoped stock locations to a workspace path.",
+				"risk": "workspace-write",
+				"requiresApprovedSpec": true,
+				"supportsDryRun": true
+			}
+		}
+	]
+}
+```
+
+Rules enforced by `packages/cli/src/extensions.ts` (`validateCliCatalog`, `loadCliExtensions`):
+
+- `moduleId` equals `module.json` `id`; the module must be enabled in `flowdular.json`, otherwise its commands do not load.
+- `path` has at least two segments matching `^[a-z][a-z0-9-]*$`; the first segment equals the first segment of the module id (`inventory` for `inventory.core`) and is not a reserved group (`help`, `doctor`, `capability`, `spec`, `blueprint`, `module`, `setup`).
+- `capability.id` starts with `<namespace>.`, is unique across all enabled modules, `version` is an integer >= 1, `summary` 1 to 240 characters.
+- `risk` is one of `read`, `workspace-write`, `process`, `external`, `destructive`. A `destructive` capability with `localOnly: true` must also set `confirmation` (`^[a-z][a-z0-9-]{2,63}$`) and `supportsDryRun: true` (schema `allOf` in `cli-extension.schema.json`).
+
+## 3. Implementation: `src/cli/index.ts`
+
+```ts
+import { defineCliExtension } from '@flowdular/sdk/cli-protocol';
+
+export const cliExtension = defineCliExtension({
+	protocolVersion: 1,
+	moduleId: 'inventory.core',
+	commands: [
+		{
+			path: ['inventory', 'export'],
+			capability: {
+				id: 'inventory.export',
+				version: 1,
+				summary: 'Export tenant-scoped stock locations to a workspace path.',
+				risk: 'workspace-write' as const,
+				requiresApprovedSpec: true,
+				supportsDryRun: true,
+			},
+			execute: async (context) => ({
+				data: {
+					applied: context.apply,
+					target: context.arguments[0] ?? 'json',
+				},
+				evidence: ['modules/inventory/spec/module.yaml'],
+				warnings: context.apply ? [] : ['Dry run only.'],
+			}),
+		},
+	],
+});
+
+export default cliExtension;
+```
+
+`execute(context: { workspaceRoot, moduleRoot, apply, flags: ReadonlyMap<string, string | boolean>, arguments: readonly string[] })` returns `{ data, evidence?, warnings? }` (`packages/cli-protocol/src/index.ts`). The loader (`loadCliCommand`) imports the entry only when the command runs, accepts a `default` or `cliExtension` export, and refuses when `path` or the whole `capability` object differs from the catalog (`commandKey` compares the JSON). Keep both files metadata-identical, down to the summary text. Declare `@flowdular/sdk/cli-protocol` in `package.json`. Read module data through the module's own runtime (`xRuntimeOptionsFromEnvironment(process.env, context.workspaceRoot)` then the service), as `modules/agents/src/cli/index.ts` does; never through another module's database.
+
+## 4. What the runner does with the descriptor (`packages/cli/src/runner.ts`, `runExtensionCommand`)
+
+- `risk: 'external'`: refused with `APPROVAL_VERIFIER_REQUIRED`. `risk: 'destructive'` without `localOnly`: the same.
+- `localOnly: true`: refused with `LOCAL_ONLY_CAPABILITY` unless `FD_ENV` or `NODE_ENV` is `development` or `test` (unset counts as development).
+- `requiresApprovedSpec: true`: needs `--spec <path>` to a schema-valid spec with `status: approved`, otherwise `APPROVED_SPEC_REQUIRED`, `SPEC_VALIDATION_FAILED` or `SPEC_NOT_APPROVED`.
+- `destructive` with `--apply`: needs `--confirm <confirmation>` (`CONFIRMATION_REQUIRED`).
+- Non-read without `supportsDryRun` and without `--apply`: `EXPLICIT_APPLY_REQUIRED`. Non-read with dry run support and no `--apply` runs with `apply: false` and appends the warning `Dry run only. No writes were authorized.`
+- Invocation: `pnpm flowdular inventory export --apply` or `pnpm flowdular capability run inventory.export --apply`; `arguments` are the positionals after the path (or after `capability run <id>`); flags are `--name value`, `--name=value`, or `--flag` (`packages/cli/src/arguments.ts`). `pnpm flowdular capability list` and `describe <id>` show the descriptor; `pnpm flowdular help` lists module paths.
+
+## 5. Tests
+
+`packages/cli/tests/extensions.test.ts` shows the style: call `validateCliCatalog(catalog, manifest)` with a good catalog and with a path that claims a reserved group, assert the error text. In the module, test `execute` directly with a hand-built context (`apply: false` returns the dry-run shape, `apply: true` writes inside `context.workspaceRoot` only). Then `pnpm flowdular module validate --json` and `pnpm flowdular help` (the new path appears once the module is enabled).
+
+## 6. Landing
+
+Sandbox sessions strip `cli` from other modules' manifests and do not run module commands; the CLI parts of a module are exercised after eject or at the repository root. Both paths end with `pnpm verify` and a PR; `.ai/policies/capabilities.yaml` lists module capabilities, add yours.
+
+## Pitfalls
+
+- A `summary` edited in one file only: `CLI implementation for "inventory export" does not match its catalog.`
+- Two enabled modules claiming the same `path` or capability id: `CLI command collision`.
+- `risk: 'read'` commands run without `--apply`; anything that writes must not be `read`.
+- Commands run in the developer's process with the full environment; never print secrets in `data`.

package/agent-template/.ai/skills/core-extend/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: core-extend
+description: >-
+  Change a platform package (contracts, kernel, server, client, ui, cli,
+  sandbox, coding-agent) without breaking the modules and generated files that
+  depend on it.
+roles:
+  - module-executor
+  - reviewer
+when: A change is needed under packages/**, platform/**, or the schemas in packages/contracts, and no module-level change can deliver it.
+---
+
+# Extend the platform core
+
+This work runs at the repository root; a sandbox session cannot do it (the session workspace holds one module plus read-only `reference/` copies). When a sandbox role needs a core change, it stops with `HANDOFF: none - <the exact core change>` and this skill picks it up.
+
+## 1. Dependency direction
+
+`packages/contracts` (types and JSON schemas, no runtime) -> `packages/kernel` (registry, ACL, settings) -> `packages/server`, `packages/client`, `packages/ui` -> modules -> `platform` (composition) and `packages/cli`, `packages/sandbox`, `packages/coding-agent`, `packages/harness`, `packages/ai-provider`. A lower layer never imports a higher one. `platform/octane.config.ts` imports `@flowdular/sdk/modules/auth/server` and the generated `modules.server.ts`; nothing else in `packages/` may import a module. `@flowdular/sdk/modules/auth/server` is effectively part of the server contract: `PlatformServerContext` and `PlatformServerComposition` live in `modules/auth/src/server/composition.ts`.
+
+## 2. Surfaces every module and every agent sees
+
+Keep these stable or migrate every consumer in the same change. `packages/sandbox/src/server/reference.ts` copies them into every session, so agents code against them:
+
+- `packages/server/src/index.ts`: `defineEndpoint`, `HttpProblem`, `jsonResponse`, `problemResponse`, `readJsonObject`, `requiredString`, `optionalString`, `requiredInteger`, types `EndpointIdentity`, `EndpointExecutionContext`.
+- `packages/client/src/contributions.ts`: `ModuleClientContext`, `ModuleClientContribution`, `WORKSPACE_SLOTS`, `NavigationGroup`, `createClientContributionRegistry`. `packages/client/src/state.ts`.
+- `packages/contracts/src/index.ts` and `packages/contracts/schemas/*.json`.
+- `packages/ui/src/index.ts`, `packages/ui/src/components/*.tsrx`, `packages/ui/src/styles/components.css`.
+- `modules/auth/src/{index.ts,acl/scopes.ts,domain/types.ts,server/index.ts,services/auth-service.ts}`.
+- `AGENTS.md`, `docs/design-system.md`, and `.ai/skills/**` (copied to `reference/skills/`).
+
+## 3. Checklists by change type
+
+Schema change (`packages/contracts/schemas/*.schema.json`):
+
+1. Edit the schema and the matching type in `packages/contracts/src/index.ts`.
+2. Update `packages/cli/src/module-scaffold.ts` so a fresh module satisfies the schema, and its test `packages/cli/tests/module-scaffold.test.ts`.
+3. Update every `modules/*/module.json` or `modules/*/spec/module.yaml` the change affects, and the `.ai/blueprints/*/required-files.yaml`, `spec-requirements.yaml` and the business manager prompt when keys change.
+4. `pnpm validate` (spec, blueprint, module validation) and `pnpm test`.
+
+Server or auth contract (`packages/server`, `modules/auth/src/server/composition.ts`): change the type, then every `src/platform.ts` and `src/api/endpoints.ts` under `modules/`, then `packages/cli/src/module-sync.ts` if the generated composition shape changes, then `platform/octane.config.ts`. Adding a hook to `PlatformServerComposition` (for example an optional `agentTools`) must stay optional so existing modules compile.
+
+Client or UI primitive: add the component to `packages/ui/src/components/`, export it from `packages/ui/src/index.ts`, add its classes to `packages/ui/src/styles/components.css` with tokens only, document props and classes in `docs/design-system.md`, and delete the module-local promotion candidate it replaces. An icon is one path in `ICON_PATHS` (`packages/ui/src/icons/Icon.tsrx`), 24x24 stroke geometry.
+
+CLI: commands are dispatched in `packages/cli/src/runner.ts`; a new core capability is a descriptor in `packages/cli/src/capabilities.ts` (`id`, `version`, `summary`, `risk`, `requiresApprovedSpec`, `supportsDryRun`); flags are parsed by `packages/cli/src/arguments.ts` (`--name value` or `--name=value`, `--flag`); `reservedGroups` in `packages/cli/src/extensions.ts` protects core groups from module namespaces; `pnpm flowdular help` output lists the commands. Tests in `packages/cli/tests`. Update `.ai/policies/capabilities.yaml` and `README.md`.
+
+Sandbox and coding agent: gate ids live in `packages/sandbox/src/server/gates.ts` (`GateId`, `GATE_DEFINITIONS`) and must match the `gates:` front matter of `.ai/agents/sandbox/*.md`; role defaults in `packages/coding-agent/src/roles/defaults.ts` are regenerated from those files (sync script in `.ai/README.md`), never hand-edited; the instruction contract is `packages/coding-agent/src/roles/contract.ts`. Reference copies for sessions: `packages/sandbox/src/server/reference.ts` `REFERENCE_SOURCES`.
+
+Module and blueprint discovery: `packages/cli/src/validation.ts` `findNamedFiles` walks the workspace for `module.json`, `module.yaml` and `blueprint.json`, skipping `node_modules`, `dist` and tool state directories; check its skip list before adding a new discoverable file type.
+
+## 3b. Worked example: how the optional composition members landed
+
+The agent-tool hook, capability registry and module settings show the shape of a safe contract change (`modules/auth/src/server/composition.ts`, `packages/kernel/src/{capability-registry,tool-registry,module-settings}.ts`, `platform/octane.config.ts`):
+
+```ts
+export interface PlatformServerContext {
+	readonly environment: NodeJS.ProcessEnv;
+	readonly workspaceRoot: string;
+	readonly auth: AuthRuntime;
+	readonly settings: ModuleSettingsRuntime; // live, tenant-scoped reads
+	readonly agentTools: PlatformToolRegistry; // register(tools), list()
+	readonly agentDefinitions: PlatformAgentRegistry; // register(definitions), list()
+	readonly capabilities: PlatformCapabilityRegistry; // register(id, service), get(id), has(id)
+}
+
+export interface PlatformServerComposition {
+	readonly routes: readonly ServerRoute[];
+	readonly settings?: ModuleSettingsDeclaration; // declared by the platform after composing
+	readonly prepare?: () => void | Promise<void>; // read-only checks before HMR activation
+	readonly start?: () => void; // called after every module composed
+	readonly stop?: () => void | Promise<void>; // drains background work before disposal
+	readonly dispose?: () => void | Promise<void>; // releases owned resources
+}
+```
+
+New context members are required (every module receives them; nobody has to read them), new composition members are optional (existing modules compile unchanged). The platform composes modules in dependency order, binds each `agentDefinitions` registrar to that module id, declares every `settings`, seals the definitions, runs every `prepare`, retires the old generation, and then calls every `start`. Retirement completes every `stop` before any `dispose`, so background work cannot outlive a repository it uses. The generic registries live in `@flowdular/sdk/kernel` so `modules/auth` does not import the harness or a provider module. `agentTools` carries model-visible tool identities; `agentDefinitions` carries immutable module-owned business agent behavior; `capabilities` carries typed public services between modules, with the provider owning the service type and the consumer declaring the module dependency and handling absence from `get`.
+
+## 4. Generated and composed files
+
+`platform/src/generated/modules.server.ts` and `modules.client.ts` are written by `pnpm flowdular module sync --apply` (also run by `pnpm dev` and `pnpm build`). `flowdular.json` `modules.enabled` and `platform/package.json` dependencies are written by `module enable --apply`. Never edit them by hand; change the generator and regenerate. `packages/ui/src/brand/mark.ts` is generated by `node packages/ui/scripts/gen-mark.mjs`.
+
+## 5. Verification
+
+```bash
+pnpm verify        # typecheck, test, validate, format:check
+pnpm build         # cli build and smoke, module sync --apply, platform build
+```
+
+Run the affected package alone while iterating: `pnpm --filter @flowdular/<pkg> test`. A change to `packages/ui` or `packages/client` also needs `pnpm --filter @flowdular/platform typecheck` and a look at the shell in `pnpm dev`.
+
+After implementation and these checks, switch to `auto-review` as a separate
+read-only phase before declaring completion. Fix findings in an implementation
+phase, rerun affected checks, and repeat the review.
+
+## 6. Do not build on dead code
+
+`RegisteredModule.navigation` in `packages/contracts` is declared by modules but never read at run time (the shell reads `ModuleClientContribution.navigation`). `validateTaskPacket` and `packages/harness/schemas/task-packet.schema.json` have no runtime caller. Module translations load through `ModuleClientContribution.translations` and the shared client i18n registry; do not introduce a second loader. Extend the live path or remove the dead one in its own change; do not add a third variant.
+
+## Pitfalls
+
+- A new required key in `module.schema.json` breaks every module manifest and the scaffold at once; ship it optional first.
+- Changing an error code string (`UNAUTHENTICATED`, `FORBIDDEN`, `CSRF_REJECTED`) breaks module tests that assert it.
+- `packages/ui/src/index.ts` imports fonts and `styles/index.css` at module top; a test that imports `@flowdular/sdk/ui` needs a DOM environment.
+- Prettier uses tabs and `@tsrx/prettier-plugin`; run `pnpm format` before `format:check`.

package/agent-template/.ai/skills/database-adapter/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: database-adapter
+description: >-
+  Build a Flowdular module repository on the asynchronous @flowdular/sdk/database
+  contract: PostgreSQL everywhere, embedded PGlite for local and test runs,
+  provider leases, forced row-level security, migrations, and tenant isolation
+  tests.
+roles:
+  - backend-engineer
+  - module-executor
+  - reviewer
+when: A module needs a repository on the shared database provider, a new table, a cross-tenant read, or a migration.
+---
+
+# Use the database adapter contract
+
+Read `docs/database-adapters.md`, `packages/database/src/contracts.ts`, and the
+converted `modules/profile` repository before editing. This skill is for coding
+agents. It is unrelated to tenant-defined Procedures in `agents.core`.
+For a driver adapter, first-run setup, adapter switch, or delivery matrix, also
+read [references/first-run-and-matrix.md](references/first-run-and-matrix.md).
+
+## 1. Keep three layers separate
+
+1. The business repository port is database-agnostic. Domain types, services,
+   errors, and callers never import a driver or branch on a dialect.
+2. The module owns persistence for every dialect it declares: explicit queries,
+   row mapping, error normalization, migrations, and contract tests.
+3. Platform composition owns driver adapters and `DatabaseProvider`: paths,
+   credentials, pools, TLS, timeouts, and disposal. A module never receives a
+   DSN and never creates a production pool.
+
+`DatabaseProvider.acquire({ namespace, purpose })` returns a lease. The module
+uses `lease.database` and releases only that lease. `DatabaseHandle` exposes
+async operations, open `adapterId` and `dialectId`, capabilities, transactions,
+and schema introspection. A callback-scoped transaction expires on return.
+
+The platform runs on PostgreSQL. A deployment points at a server; a
+workstation, a preview and a test suite get the same PostgreSQL embedded in the
+process through PGlite, so there is nothing to install and no second dialect to
+keep in step. Modules write PostgreSQL and only PostgreSQL. The contract still
+carries an open `dialectId` and capability negotiation so a future driver can
+join, but never add a core exhaustive switch that must be edited for each one.
+
+## 2. Make the whole repository chain asynchronous
+
+Changing only the driver is not a conversion. Update every method in the chain:
+
+1. `src/services/repository.ts` returns `Promise<T>` or `Promise<void>`.
+2. The database repository awaits every `query`, `execute`, transaction, and
+   migration call.
+3. Services await repository methods. Preserve validation and domain error
+   codes at this boundary.
+4. Endpoints, agent tools, capabilities, background jobs, and tests await the
+   service.
+5. Remove synchronous assumptions such as returning a write input before the
+   database confirms it.
+
+Search every caller of the repository interface before changing it. A missed
+caller can compile through an inferred promise and then serialize the wrong
+value into an API response.
+
+## 3. Acquire one provider lease per module runtime
+
+`createServerComposition` remains synchronous. Pass `context.databases` into
+the module runtime. The runtime owns one shared initialization promise that
+acquires the lease and runs migrations lazily before the first repository
+operation. Concurrent first requests await that same promise.
+
+Use the module id as the namespace. Acquire `purpose: 'migration'`, run
+`runDatabaseMigrations`, and release that lease before acquiring
+`purpose: 'runtime'`; the application role never owns DDL. Preview uses
+`purpose: 'preview'` and isolated tests use `purpose: 'test'`. A read that must
+cross tenants takes `purpose: 'background'`, a read-only role with no blanket
+table grant. Follow `modules/profile/src/server/runtime.ts` for the exact
+sequence. `prepare()` stays read-only and never acquires a lease. `dispose()`
+awaits started initialization and releases every lease once.
+
+## 4. Write explicit SQL
+
+Repositories own their SQL. There is no translation layer and no placeholder
+rewriting.
+
+- Parameters are `$1`, `$2`, and so on, in the order the statement binds them.
+- Values always go in `DatabaseStatement.parameters`. Never concatenate request
+  data, tenant ids, identifiers, sort directions, or filter values into SQL.
+- Dynamic identifiers and ordering come from a closed code-owned allowlist.
+- `executeScript()` is only for trusted, checked-in migration DDL. Runtime
+  writes use `execute()`.
+- Keep tenant predicates and tenant-first uniqueness in both dialects. Every
+  tenant-owned read and write includes `tenant_id` from the trusted principal.
+
+PostgreSQL tenant-owned tables also use database-enforced isolation:
+
+- enable and force row-level security on the table;
+- define a policy whose `USING` and `WITH CHECK` clauses compare `tenant_id`
+  with `current_setting('coreloom.tenant_id', true)`;
+- run application traffic under a role that is neither a superuser nor granted
+  `BYPASSRLS`;
+- use a separate migration role for DDL or policy ownership when required.
+
+The adapter sets `coreloom.tenant_id` with parameterized `set_config(..., true)`
+after `BEGIN` on the pinned connection. Never use an unpinned root query.
+Explicit tenant predicates remain required as defense in depth.
+
+PostgreSQL returns `BIGINT` as a string. Normalize every integer column on the
+way out of a row through a local `integer()` helper. A comparison such as
+`enabled === 1` silently fails without it, and a count read raw compares against
+a string. Only widen timestamps and sequences to `BIGINT`; leave flags, counters
+and version columns `INTEGER`.
+
+Normalize driver-specific unique, foreign-key, serialization, and timeout
+failures into the module's stable service error codes. `DatabaseError` covers
+contract misuse and lifecycle errors; raw driver error classes are deliberately
+not a public module contract.
+
+## 5. Transactions and concurrency
+
+Use the transaction argument for every operation inside a transaction callback.
+Calling the root handle from that callback is rejected, and retaining the
+transaction after the callback is `TRANSACTION_CONTEXT_MISUSE`.
+
+PostgreSQL may run root operations concurrently, while a transaction is pinned
+to one pooled client. Do not depend on physical connection identity or pool
+order. State transitions that must be atomic belong in one transaction with an
+affected-row or version check. A public repository method called from inside
+another method's transaction opens a second transaction and is rejected; give it
+a private in-transaction variant that takes the transaction instead.
+
+Pass `AbortSignal` and a bounded `timeoutMs` from long-running jobs. Read
+`database.capabilities` before depending on isolation or cancellation. A
+`before-start` cancellation capability does not stop a driver call already in
+progress. Portable tenant-owned repository methods use
+`database.transaction(operation, { tenantId, access, isolation })`, including
+reads. PostgreSQL root query, execute, and schema calls, and PostgreSQL
+transactions without `tenantId`, fail with `TENANT_CONTEXT_REQUIRED`.
+
+## 6. Migrations v2 and schema inspection
+
+Use `DatabaseMigration` and `runDatabaseMigrations` from `@flowdular/sdk/database`.
+Each migration has one immutable id and its PostgreSQL SQL. The ledger is
+`_coreloom_migrations_v2`, keyed by module namespace and migration id; its
+checksum covers that exact SQL.
+
+`inspectExisting(database)` is the only pre-ledger adoption proof. Use
+`database.schema.hasTable`, `hasColumn`, and `hasIndex` with fixed identifiers
+and return:
+
+- `complete` only when every effect of the migration exists;
+- `absent` only when none exists;
+- `partial` for every mixed state, which the runner refuses.
+
+The runner acquires the adapter's migration lock and applies outstanding DDL
+plus ledger rows in one serializable transaction. It refuses a missing dialect,
+checksum drift, duplicate ids, partial adoption, and adapters without
+transactional DDL. Never edit applied migration bytes or bypass a refusal.
+
+`inspectExisting` must pass thunks, not eager promises. Adoption runs inside a
+single-connection transaction, and overlapping queries on that connection break
+it. Check in numbered `.up.sql` source and mirror its bytes in the migration
+constant. A migration-only task uses `migration-authoring` in a separate phase.
+
+## 7. Tests run on a real PostgreSQL
+
+`createTestDatabaseProvider()` from `@flowdular/sdk/database-testing` gives a suite its
+own PostgreSQL in process by default, with the same `coreloom_runtime` and
+`coreloom_background` roles and the same forced row-level security a deployment
+enforces. There is no server to start and no second dialect to keep green, so
+the isolation assertions run on every turn rather than behind an environment
+flag. CI selects server PostgreSQL with `FD_TEST_DATABASE_ADAPTER=postgresql`
+and the three test role URLs; missing credentials fail instead of falling back.
+
+Starting the engine costs roughly half a second. Open one per test file and
+truncate between cases instead of paying it per test.
+
+Cover CRUD, commit and rollback, tenant isolation and uniqueness, stable error
+normalization, and concurrent version conflicts. Migration tests cover empty
+apply, safe adoption, refusals, and a clean second start.
+
+With two tenants, prove that each can see and mutate only its own rows, that a
+read or write without tenant context fails with `TENANT_CONTEXT_REQUIRED`, and
+that `WITH CHECK` blocks inserting another tenant id. Where a module polls
+across tenants, prove that the background role reads exactly the routing columns
+and is refused everything else, including writes.
+
+## Refuse
+
+- A DSN, password, pool, or `pg` dependency inside a module.
+- A module that opens its own database file or connection.
+- A closed core switch over known adapter ids.
+- Root-handle work inside a transaction callback or a transaction that escapes.
+- Cross-module database access. Use the owner's typed capability or API.
+- A tenant table without enabled and forced row-level security, a tenant policy,
+  or tests under a role that cannot bypass it.
+- A cross-tenant read on the runtime role, or a background role granted whole
+  rows instead of the columns its poll needs.
+- Tests that mock away SQL, migration, concurrency, or tenant predicates.
+
+## Verification
+
+Run the module typecheck and tests, the `@flowdular/sdk/database` contract tests when
+the adapter changes, `pnpm flowdular module validate --json`, and `pnpm verify`
+before landing. An adapter change also needs a shutdown test proving that active
+work drains before pool disposal.