@flowdular/sdk 0.1.0

package/.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/.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.

package/.ai/skills/database-adapter/references/first-run-and-matrix.md

@@ -0,0 +1,105 @@
+# Adapter setup and delivery matrix
+
+Read this reference when adding a driver adapter, exposing database setup, or
+preparing an adapter-backed module for eject or a pull request.
+
+## Adapter descriptor
+
+A platform adapter descriptor owns the complete first-run contract:
+
+- an open `adapterId` and `dialectId`;
+- a machine-readable configuration schema;
+- UI hints such as labels, descriptions, groups, order, and input kind;
+- an explicit list of secret fields;
+- configuration validation without opening module databases;
+- a connectivity probe with bounded time and sanitized errors;
+- optional provisioning for infrastructure the adapter actually owns;
+- connection creation that returns the shared adapter contract;
+- advertised database capabilities.
+
+The registry is open. Core code resolves a descriptor by id and negotiates its
+capabilities rather than switching over known adapter ids, so an adapter package
+can join without changing module business ports or the setup screen.
+
+Configuration UI is generated by the platform from descriptor metadata. A
+module never implements database setup UI and never asks for a DSN.
+
+## First run
+
+The embedded PostgreSQL is the zero-configuration local default: PGlite runs in
+process, so a workstation starts with nothing installed and still exercises the
+same forced row-level security a deployment enforces. Its data root comes from
+the platform provider, not from each module.
+
+Before selecting another adapter, setup:
+
+1. validates descriptor configuration and required secrets;
+2. probes the target with a strict timeout and no secret echo;
+3. lists every enabled database-owning module;
+4. verifies that each module declares an implementation for the target
+   `dialectId` and that the adapter supplies its required capabilities;
+5. refuses activation with the exact incompatible modules and capabilities;
+6. provisions only after explicit operator confirmation when provisioning
+   changes external state;
+7. runs migrations through a migration lease before runtime leases are served;
+8. verifies readiness under the non-bypass runtime role.
+
+Secret values live in environment-backed or encrypted platform secret storage.
+`flowdular.json`, module manifests, setup responses, logs, audit metadata, run
+snapshots, and pull request descriptions contain only secret references or
+redacted presence state.
+
+## Switching an adapter with existing data
+
+Changing an adapter id never points modules at an empty database and never
+copies storage files. The only supported switch is an explicit operation:
+
+1. stop writes and acquire an export snapshot;
+2. export through module-owned portable records, preserving ids and versions;
+3. provision and migrate the target;
+4. import in dependency-safe batches under tenant context;
+5. verify counts, checksums, referential expectations, and module invariants;
+6. probe reads and writes through the target runtime role;
+7. activate the target only after verification succeeds;
+8. retain the source for rollback until the operator closes the window.
+
+A failed import or verification leaves the source active. There is no silent
+fallback to another database, because that would split writes.
+
+## Module declarations
+
+Each database-owning module declares:
+
+- supported open dialect ids;
+- the required capability set, such as transactions, transactional DDL,
+  schema introspection, returning values, or an isolation level;
+- its module-owned persistence implementation and migrations;
+- one adapter-neutral repository behavior suite.
+
+The platform compatibility check consumes these declarations before first run,
+adapter change, sandbox eject, and deployment validation.
+
+## Delivery matrix
+
+Every turn runs against a real PostgreSQL, because the embedded one starts in
+process. The sandbox and the test suites use `createTestDatabaseProvider()` from
+`@flowdular/sdk/database-testing`, which brings the `coreloom_runtime` and
+`coreloom_background` roles and forced row-level security with it.
+
+A target run covers tenant A and B fixtures, operations without tenant context,
+forged cross-tenant inserts, direct row-security bypass probes, concurrent
+writes, and cleanup. Where a module polls across tenants, it also proves the
+background role reads only the routing columns.
+
+Before eject or a pull request the matrix additionally runs the same suite
+against a server PostgreSQL when one is configured, using a unique schema and a
+role that holds neither `SUPERUSER` nor `BYPASSRLS`. Test credentials are
+short-lived and never enter the transcript. If that target is unavailable the
+session may continue editing, and delivery states the exact missing target.
+
+Server selection is explicit: `FD_TEST_DATABASE_ADAPTER=postgresql`,
+`FD_TEST_POSTGRES_URL` (migrator), `FD_TEST_POSTGRES_RUNTIME_URL` and
+`FD_TEST_POSTGRES_BACKGROUND_URL`. All three URLs are required. Missing or
+unreachable configuration never falls back to PGlite. `.github/workflows/ci.yml`
+runs this matrix, including auth and agents. Keep role separation intact in
+fixtures: even the migration owner must supply tenant context for tenant data.

package/.ai/skills/migration-authoring/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: migration-authoring
+description: >-
+  Add an immutable PostgreSQL module migration through @flowdular/sdk/database, with
+  the namespaced v2 ledger, safe schema adoption, forced row-level security, and
+  tenant isolation tests.
+roles:
+  - backend-engineer
+  - module-executor
+  - reviewer
+when: A module needs a new table, column, index, or constraint.
+---
+
+# Author a database migration
+
+An adapter conversion is a separate phase using `database-adapter`. For this phase, read
+`packages/database/src/migrations.ts` and the converted `modules/profile`
+migration as the reference. Flowdular has a migration runner. Do not add
+constructor-owned `DatabaseSync.exec()` guards around it.
+
+## 1. Source layout and compatibility
+
+Migration SQL is checked in and immutable after release:
+
+- `migrations/NNNN_<module>_<name>.up.sql` holds the PostgreSQL source and is
+  byte-exact. Never move, renumber or reformat a released file.
+- `src/services/migration.ts` mirrors every `.up.sql` file as a literal and
+  exports `databaseMigrations: readonly DatabaseMigration[]`, one entry per
+  file. No code translates or rewrites SQL.
+- `.down.sql` documents a reverse operation. Flowdular never executes it.
+
+## 2. What the v2 runner guarantees
+
+`runDatabaseMigrations(database, namespace, databaseMigrations)` uses the
+namespaced `_coreloom_migrations_v2` ledger. A row records namespace, migration
+id, dialect id, checksum, and applied time. The checksum covers the selected
+dialect's exact SQL.
+
+Before applying outstanding work, the runner checks every existing ledger row.
+It refuses checksum drift, a missing script, duplicate ids, a wrong ledger
+dialect, partial adoption, and adapters without transactional DDL. It opens one
+serializable transaction, takes a transaction advisory lock, and commits DDL
+plus ledger rows together. Dry run writes nothing.
+
+The runner selects scripts by the provider's open `dialectId`. Do not add a core
+switch over known dialects. A new driver advertises capabilities and a module
+opts into it by supplying reviewed SQL and tests.
+
+## 3. Explicit adoption proof
+
+Every migration that may predate v2 defines `inspectExisting(database)`. Use
+adapter-owned, capability-checked schema introspection such as `hasTable`,
+`hasColumn`, and `hasIndex` with fixed identifiers.
+
+Return `complete` only when every table, column, index, constraint, data effect,
+and security policy exists. Return `absent` only when none exists. Return
+`partial` for every mixed state. If an adapter cannot inspect a required object,
+extend its introspection capability or supply a narrow module-owned inspection.
+Never guess `complete` and never parse another dialect's catalog directly in
+shared code.
+
+## 4. SQL rules shared by dialects
+
+- Tenant tables carry `tenant_id TEXT NOT NULL`.
+- Tenant uniqueness and lookup indexes start with `tenant_id`; ordered indexes
+  end with `id` for stable results.
+- IDs are text UUIDs generated by the service. Times are integer milliseconds.
+- Money is integer minor units plus a currency code, never floating point.
+- Enums and ranges have database check constraints.
+- Cross-module foreign keys do not exist. Use the owner's capability or API.
+- Additive changes are the default. Destructive or locking changes need an
+  operator-approved rollout, compatibility window, and rollback plan.
+
+Write PostgreSQL directly: its types, conflict syntax, indexes and policies.
+Never rewrite placeholders or DDL text.
+
+## 5. PostgreSQL row-level security
+
+Every PostgreSQL tenant table includes:
+
+```sql
+ALTER TABLE inventory_locations ENABLE ROW LEVEL SECURITY;
+ALTER TABLE inventory_locations FORCE ROW LEVEL SECURITY;
+CREATE POLICY inventory_locations_tenant_policy ON inventory_locations
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));
+```
+
+The runtime role is not a superuser and has no `BYPASSRLS`. DDL and policy
+ownership use `purpose: 'migration'`. Runtime repository calls use
+`database.transaction(operation, { tenantId, access })`; the adapter sets
+transaction-local `coreloom.tenant_id` on the pinned connection. Queries still
+include `WHERE tenant_id = ...` as defense in depth.
+
+## 6. Add one migration
+
+Scaffold instead of writing from memory:
+
+```bash
+pnpm flowdular migration new <name> --module <id>          # dry run
+pnpm flowdular migration new <name> --module <id> --apply  # writes both files
+```
+
+The scaffold emits the `.up.sql` and `.down.sql` pair with the tenant table, its
+index, and the `ENABLE` + `FORCE` + policy block already correct. Replace the
+placeholder columns with the real schema; keep the row-security block unless the
+table is not tenant owned.
+
+1. Never renumber released files. The scaffold picks the next id.
+2. Mirror every `.up.sql` byte for byte and append one `DatabaseMigration` with
+   the same id.
+3. Add exact `inspectExisting` logic with `migrationObjectState` and
+   `postgresTenantTableState` from `@flowdular/sdk/database`. Pass thunks, never
+   ready promises: adoption runs inside a transaction pinned to one connection,
+   and eager promises issue overlapping queries on it.
+4. Extend repository SQL, row mapping, service validation, endpoint, client,
+   approved spec scenario, and all three module versions.
+
+### Column types that bite
+
+PostgreSQL returns `BIGINT` as a string. Normalize every integer read in the
+repository through a local `integer()` helper; a raw value concatenates where it
+should add, and `enabled === 1` is false against `'1'`.
+
+Widen timestamps, durations and sequences to `BIGINT`. Leave boolean flags,
+counters and version columns `INTEGER`, or every comparison against them has to
+be normalized too.
+
+Money is integer minor units in `BIGINT` plus a currency code.
+
+Never test against a workspace database. `createTestDatabaseProvider()` from
+`@flowdular/sdk/database-testing` gives the suite its own PGlite by default or an
+isolated PostgreSQL schema in server CI. Tenant fixture reads and writes still
+need transaction-local tenant context, including on the migration connection.
+
+## 7. Tests and gates
+
+`pnpm flowdular migration verify` checks the ledger and every module's migration
+set: a missing script, a tenant table without forced row security, and a policy
+lost to a table rebuild.
+
+The migration suite proves byte parity and id order, empty apply, complete
+adoption without row loss, partial refusal, checksum refusal before later SQL,
+dry run without writes, and a clean second start.
+
+Every gate runs against a real PostgreSQL, because the embedded one starts in
+process. Cover tenant A and B isolation, a forged tenant `WITH CHECK` refusal, a
+missing-context `TENANT_CONTEXT_REQUIRED` test, and direct row-security bypass
+probes under a role that holds neither `SUPERUSER` nor `BYPASSRLS`. Where the
+module polls across tenants, prove the background role reads only the routing
+columns.
+
+## Refuse
+
+- Editing, moving, reordering, or removing released migration bytes.
+- A PostgreSQL tenant table without enabled and forced RLS plus both policy
+  clauses.
+- A runtime role with superuser or `BYPASSRLS`.
+- DDL through a runtime lease or request data through `executeScript()`.
+- Automatic SQL translation or a closed core switch over known dialects.
+- Forcing past checksum or partial-adoption refusal.
+- A production-support claim based on a fake driver alone.
+
+## Verification
+
+Run the module typecheck and tests, module validation,
+`pnpm flowdular migration verify`, and `pnpm verify`.