create-flowdular 0.5.1 → 0.6.0

package/agent-template/.ai/skills/module-new/SKILL.md

@@ -148,7 +148,7 @@ export function createServerComposition(
 
 `PlatformServerContext` also carries `databases: DatabaseProvider`, `settings: ModuleSettingsRuntime`, `agentTools: PlatformToolRegistry`, `agentDefinitions: PlatformAgentRegistry`, and `capabilities: PlatformCapabilityRegistry`. The runtime shares one lazy database initialization, uses separate migration and runtime leases, and releases the runtime lease from `dispose()`; `prepare()` remains read-only. A composition may return module settings, lifecycle hooks, agent registrations, and typed cross-module capabilities as described in the focused skills.
 
-Schema: write PostgreSQL SQL in `migrations/0001_inventory_core.up.sql` and mirror it byte for byte in `databaseMigrations` as `sql: { postgresql: ... }` with an `inspectExisting` built from `postgresTenantTableState(...)`. Tenant tables enable and force row-level security with an `<table>_tenant_policy` whose `USING` and `WITH CHECK` compare `tenant_id` with `current_setting('coreloom.tenant_id', true)`; the runtime role has no superuser or `BYPASSRLS`. Repository operations use `database.transaction(..., { tenantId, access })` and retain explicit tenant predicates. Details in `migration-authoring` and `database-adapter`.
+Schema: write PostgreSQL SQL in `migrations/0001_inventory_core.up.sql` and mirror it byte for byte in `databaseMigrations` as `sql: { postgresql: ... }` with an `inspectExisting` built from `postgresTenantTableState(...)`. Tenant tables enable and force row-level security with an `<table>_tenant_policy` whose `USING` and `WITH CHECK` compare `tenant_id` with `current_setting('flowdular.tenant_id', true)`; the runtime role has no superuser or `BYPASSRLS`. Repository operations use `database.transaction(..., { tenantId, access })` and retain explicit tenant predicates. Details in `migration-authoring` and `database-adapter`.
 
 Errors: `{ error: { code, message } }`; service errors `class XServiceError extends Error { constructor(readonly code: string, message: string, readonly status = 400) }`; a `failure(error)` helper routes them to `jsonResponse(..., error.status)` and everything else to `problemResponse(error, 'The <module> operation failed.')`.
 

package/agent-template/.ai/skills/test-hardening/SKILL.md

@@ -23,7 +23,7 @@ when: A module has few or tautological tests, a bug escaped the suite, or a revi
 
 ## 2. Repositories on an embedded PostgreSQL
 
-`createPgliteTestProvider()` from `@flowdular/sdk/database-testing` runs a real PostgreSQL inside the test process, with the same `coreloom_runtime` and `coreloom_background` roles and the same forced row-level security a deployment enforces. Booting it costs about two seconds, so a suite opens one provider per test file, migrates it once, and truncates the module's tables between cases; `.ai/references/catalog/tests/support/database.ts` is the shape (`createCatalogTestDatabase` hands out a lease per fixture, `closeCatalogTestDatabases` runs in `afterAll`). Build the service on top: `new CatalogService((await createCatalogTestDatabase()).repository)`. A database module also keeps `tests/migrations.test.ts` for SQL byte parity, fresh apply, safe pre-ledger adoption, and a clean second start. A module whose spec has no `database` capability gets a `MemoryXRepository` from the scaffold instead; a module with a database tests the database repository, never a hand-written fake, because the SQL, the ledger and the row-level security are what need testing.
+`createPgliteTestProvider()` from `@flowdular/sdk/database-testing` runs a real PostgreSQL inside the test process, with the same `flowdular_runtime` and `flowdular_background` roles and the same forced row-level security a deployment enforces. Booting it costs about two seconds, so a suite opens one provider per test file, migrates it once, and truncates the module's tables between cases; `.ai/references/catalog/tests/support/database.ts` is the shape (`createCatalogTestDatabase` hands out a lease per fixture, `closeCatalogTestDatabases` runs in `afterAll`). Build the service on top: `new CatalogService((await createCatalogTestDatabase()).repository)`. A database module also keeps `tests/migrations.test.ts` for SQL byte parity, fresh apply, safe pre-ledger adoption, and a clean second start. A module whose spec has no `database` capability gets a `MemoryXRepository` from the scaffold instead; a module with a database tests the database repository, never a hand-written fake, because the SQL, the ledger and the row-level security are what need testing.
 
 ## 3. Route recipe (from `modules/auth/tests/endpoints.test.ts`)
 
@@ -63,7 +63,7 @@ The auth middleware must have set the principal for `endpointIdentityFromContext
 - 403 on a mutation without `x-csrf-token` (`CSRF_REJECTED`) and without `origin` (`ORIGIN_REQUIRED`).
 - 400 with the stable code for each validation bound (`INVALID_INPUT`, module codes such as `INVALID_ITEM_KIND`).
 - 409 for the tenant-scoped uniqueness rule, and success for the same key in another tenant.
-- Tenant isolation: rows created for `tenant-a` are invisible to `list('tenant-b')`. The provider hands the suite the non-bypass `coreloom_runtime` role, so this runs against real forced row-level security; also assert that a call without tenant context fails with `TENANT_CONTEXT_REQUIRED`.
+- Tenant isolation: rows created for `tenant-a` are invisible to `list('tenant-b')`. The provider hands the suite the non-bypass `flowdular_runtime` role, so this runs against real forced row-level security; also assert that a call without tenant context fails with `TENANT_CONTEXT_REQUIRED`.
 - Identity: `moduleDefinition.manifest.id` equals the module id (keeps `module.json` and `src/index.ts` aligned). The scaffold writes this and the isolation case; everything else in this list is yours.
 
 Assert at the observation boundary: status code, `error.code`, returned record fields. Do not assert internal helper names, call order, or SQL text.

package/agent-template/.ai/skills/workflow-development/SKILL.md

@@ -1,14 +1,13 @@
 ---
 name: workflow-development
 description: >-
-  Build, publish, invoke, and test a workflows.core DAG through its typed graph
-  and public execution capability without bypassing agent, action, tenant, or
-  audit boundaries.
+  Author module-owned action templates, or build, publish, invoke, and test a
+  workflows.core DAG through its typed graph and public execution capability.
 roles:
   - agentic-engineer
   - frontend-engineer
   - module-executor
-when: A brief asks for a workflow, pipeline, canvas node, workflow action, or a module feature that starts a workflow.
+when: A brief asks for a workflow, pipeline, canvas node, action-backed workflow template, or a module feature that starts a workflow.
 ---
 
 # Build and integrate an agentic workflow
@@ -18,18 +17,22 @@ pinned agent revisions, deterministic gates, schema validators, registered
 module actions, data mappings, and terminal output. It does not own schedules or
 webhook secrets. Those remain optional concerns of `automations.core`.
 
-Read `docs/adr/0006-agentic-workflows.md`, the approved
-`modules/workflows/spec/module.yaml`, and the contracts in
-`modules/workflows/src/domain/types.ts` before changing a workflow surface.
+At the repository root, read `docs/adr/0006-agentic-workflows.md`, the approved
+`modules/workflows/spec/module.yaml`, and the owning public contracts before
+changing a workflow surface. In the Sandbox, read the approved active-module
+specification and the relevant public contract under `reference/sdk` when it is
+installed. A missing public contract is a core blocker, not a reason to invent
+one or search beyond the session workspace.
 
 ## Pick the correct extension point
 
 - A workflow definition belongs in `workflows.core` and is edited through its
   API or canvas. Do not hardcode a tenant workflow in source.
 - A business operation that a workflow may call is a versioned agent action.
-  Register it through the agents action catalog. If missing, implement it in a
-  separate `agent-tool-design` phase with permission, input, output, timeout,
-  idempotency and audit tests before returning to workflow integration.
+  Register one ordinary `AgentTool` with `context.agentTools`. Optional
+  `workflowTemplate` metadata makes that action a named palette choice through
+  `agents.actions.v2`; it creates no second handler or node kind. Use the
+  authoring recipe below when the action is part of this task.
 - A business module that starts a workflow resolves
   `workflows.execution.v1` from `context.capabilities`. It never imports a
   workflow repository or database.
@@ -39,6 +42,87 @@ Read `docs/adr/0006-agentic-workflows.md`, the approved
 - If the workflow module is absent, the capability registry returns `null`.
   Hide an optional feature or return a clear stable refusal.
 
+## Author a module-owned workflow node template
+
+An action-backed template is module source, not graph source. The business
+manager first records its stable action id, permission, named inputs and
+validation rules, output, effect, replay behavior, and success and refusal
+scenarios in the owning module's specification. In a Sandbox session, the
+operator must approve the hash of that exact spec before implementation. A
+later edit requires renewed approval. If any of these decisions are absent,
+hand the spec delta to `business-manager`; do not infer a field, permission,
+external effect, or idempotency rule from the brief.
+
+Work inside the existing role boundaries:
+
+1. `backend-engineer` owns the tenant-bound service, code-level validator,
+   endpoint or CLI target, and durable target ledger for a mutation. Validation
+   runs before any write and returns a stable bounded refusal. A repeated
+   idempotency key returns its first result; the same key with different input
+   conflicts. Ask backend to supply a missing service rather than writing in
+   `src/services/**` or `src/api/**` from the agentic role.
+2. `agentic-engineer` defines the tool under `src/agent/**`, registers it once
+   from `createServerComposition` in `src/platform.ts`, and adds behavioral
+   tests. `defineApiAgentTool` or `defineCliAgentTool` carries the existing
+   public target. `agents.core` exposes the registered action through
+   `agents.actions.v2`; the business module does not register that capability
+   or access the workflow database.
+3. Give the tool a stable dotted id, positive `contractVersion`, required
+   permission, bounded input and output JSON Schemas, `risk: 'read'` or
+   `'workspace-write'`, `idempotency: 'required'`, cancellation policy, and
+   timeout. A workspace write also needs
+   `idempotencyProtection: 'target-ledger'` backed by the service's real ledger.
+   The handler receives trusted tenant, actor, permission snapshot,
+   idempotency key, and `AbortSignal` from `AgentToolContext`; none comes from
+   graph input. Its output must satisfy its declared schema.
+4. Add static `workflowTemplate: { label, description, effect }` on that same
+   tool. The label is at most 80 characters, the description at most 240, and
+   effect is `local` or `connector-egress`. Metadata contains no code,
+   credential, or tenant value. Invalid or duplicate metadata must fail
+   composition with a safe diagnostic. A workflow-eligible tool without the
+   metadata remains in the generic action editor.
+
+The selected template becomes a normal `action` node with input, success, and
+failure ports. It pins the action id, contract version, schemas, permissions,
+risk, idempotency protection, timeout, cancellation, and effect. Changing any
+of those or the handler's behavior requires a new action identity or contract
+version. The current registry keeps one version per action id, so retain the
+old id and register a distinct id when published graphs must keep running;
+label and description may change without rebinding a published graph.
+
+Graph bindings may never supply a raw secret. `writeOnly` and
+`x-flowdular-secret` apply at every schema depth, including array items and
+alternatives. A marked field cannot carry `default`, `const`, `enum`,
+`example`, or `examples` data. A template requiring
+a raw secret input is ineligible. Accept a nonsecret opaque reference and let
+the owning module resolve a credential from its tenant-bound vault or a
+declared capability. Never put secret values in fixtures, graph definitions,
+events, audit, or error text.
+
+For `connector-egress`, the consumer module declares `connectors.core` and
+`connectors.calls.v1`, uses `caller: 'workflow'`, checks the instance's
+`allowWorkflows` consent, and passes the stable workflow side-effect key to
+the connector. Credentials remain in `connectors.core`. A replay-stable
+output may contain the recorded call id and outcome, not a response body the
+connector replay does not return. Propagate `CALL_OUTCOME_UNKNOWN` as a
+terminal failure when the remote mutation may have happened but no call was
+recorded; never send a second request just to rebuild output. A separate
+provider contract with remote idempotency or readback is required before
+retrying an uncertain mutation.
+
+Prove the module behavior at its public service or action boundary: valid
+input, structural and business validation refusal before mutation, missing
+permission, foreign tenant, same-key replay, different-input conflict,
+cancellation, and recovery around the target commit. Connector actions also
+prove absent consent and `CALL_OUTCOME_UNKNOWN` with a recorded fixture. Run a
+deterministic workflow simulation on invented, reviewed fixtures for success,
+failure, and refusal edges. Assert semantic attempts and edge outcomes, not
+real timestamps; simulation must never invoke the handler, connector, or
+network. Inspect the named template and safe run trail in Sandbox preview,
+then run scoped gates, exact-source `auto-review`, and host eject. The agent
+cannot approve the spec, install code into the running server, or push a
+repository from the Sandbox.
+
 ## Graph contract
 
 Version one is a bounded DAG. The graph contains:
@@ -47,9 +131,11 @@ Version one is a bounded DAG. The graph contains:
 - `agent`: calls one exact immutable agent revision and validates structured
   output.
 - `agent-decision`: produces one schema-valid `pass` or `fail` outcome.
+- `typed-decision`: routes one bounded typed answer through `pass` or `fail`.
 - `gate`: evaluates the versioned allowlisted logic language.
 - `validator`: validates an envelope against a pinned JSON schema.
 - `action`: calls one exact registered action contract version.
+- `human-approval`: waits for an `approvals.core` request to resolve.
 - `merge`: waits for all declared incoming paths.
 - `output`: settles the workflow with a typed result.
 

package/agent-template/.claude/skills/agent-tool-design/SKILL.md

@@ -19,7 +19,7 @@ also ship a ready business agent through `defineAgent()`, read
 ## 1. The contract in code
 
 - Composition: `PlatformServerContext` (`modules/auth/src/server/composition.ts`) carries `agentTools: PlatformToolRegistry` (`register(tools)`, `list()`; `packages/kernel/src/tool-registry.ts`; a duplicate tool id throws at boot), `settings: ModuleSettingsRuntime`, and `capabilities: PlatformCapabilityRegistry` (`register(id, service)`, `get(id)`, `has(id)`; `packages/kernel/src/capability-registry.ts`). `platform/octane.config.ts` creates the registries, passes them to every module's `createServerComposition`, declares each `settings`, owns each `dispose`, then calls each `start`.
-- Ordering is a non-issue: `agents.core` (`modules/agents/src/platform.ts`) passes `tools: () => context.agentTools.list()` into `createAgentRuntime`, and the harness is built lazily in `start()`, which runs after every module has composed. Tools any module registers during its own compose are therefore visible, whatever the module order.
+- Ordering is a non-issue: `agents.core` (`modules/agents/src/platform.ts`) passes `tools: () => context.agentTools.list()` into `createAgentRuntime`, and the harness is built when `agents.core` opens, on its first request, capability call or `startWorker()`, all of which run after every module has composed. Tools any module registers during its own compose are therefore visible, whatever the module order.
 - Helpers: import `defineApiAgentTool` from `@flowdular/sdk/harness/tool-adapters` and the types `AgentTool`, `AgentToolContext` from `@flowdular/sdk/harness/runtime`. Both subpaths are free of the Vercel AI SDK; only the harness root (`@flowdular/sdk/harness`) and `@flowdular/sdk/modules/agents/server` pull it. `defineApiAgentTool` returns a frozen `AgentTool { id, transport: 'api', target, description, requiredPermissions, inputSchema?, execute }`. `defineCliAgentTool({ id, capability: { id, risk }, ... })` wraps a CLI capability and throws at definition time for `external` or `destructive` risk.
 - Skills inside `agents.core` are tenant database records behind `agents.skills.*`, appended to agent instructions. They are unrelated to `.ai/skills/**`, which are files for coding agents.
 - A read tool's output can also become a resolvable `{{ variable }}` for variable-aware fields: the tool's `requiredPermissions` is the variable's scope mask. Register a source on `platformVariableRegistry(context.capabilities)`, require an explicit record binding, and invoke the tool with the trusted tenant, actor permission snapshot, and signal. See the `variables` skill for the complete refusal contract.

package/agent-template/.claude/skills/auth-security-review/SKILL.md

@@ -57,7 +57,7 @@ Recipe in `modules/auth/tests/endpoints.test.ts`: build the runtime with a `Data
 
 - 401 without a cookie or token.
 - 403 with a principal that lacks the permission.
-- Cross-tenant read returns an empty list (service level, on the suite's test provider under the non-bypass `coreloom_runtime` role).
+- Cross-tenant read returns an empty list (service level, on the suite's test provider under the non-bypass `flowdular_runtime` role).
 - Mutation without `x-csrf-token` returns 403 `CSRF_REJECTED`; without `origin` returns 403.
 - Each validation bound returns 400 with its code.
 

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

@@ -88,12 +88,12 @@ 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)`;
+  with `current_setting('flowdular.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)`
+The adapter sets `flowdular.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.
 
@@ -133,7 +133,7 @@ transactions without `tenantId`, fail with `TENANT_CONTEXT_REQUIRED`.
 
 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
+`_flowdular_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
@@ -157,8 +157,8 @@ 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
+own PostgreSQL in process by default, with the same `flowdular_runtime` and
+`flowdular_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`

package/agent-template/.claude/skills/database-adapter/references/first-run-and-matrix.md

@@ -83,8 +83,8 @@ adapter change, sandbox eject, and deployment validation.
 
 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.
+`@flowdular/sdk/database-testing`, which brings the `flowdular_runtime` and
+`flowdular_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

package/agent-template/.claude/skills/deploy-operate/SKILL.md

@@ -48,7 +48,7 @@ Set `FD_TRUST_PROXY` behind a load balancer. `FD_DATABASE_BACKGROUND_URL` gives
 
 ## 3. Migrations at rollout
 
-Migrations are module-owned, numbered, immutable once applied, and verified by checksum against the `_coreloom_migrations_v2` ledger. The commands (`packages/cli/src/runner.ts`):
+Migrations are module-owned, numbered, immutable once applied, and verified by checksum against the `_flowdular_migrations_v2` ledger. The commands (`packages/cli/src/runner.ts`):
 
 ```bash
 pnpm flowdular migration status [--module <id>]      # what the ledger holds

package/agent-template/.claude/skills/migration-authoring/SKILL.md

@@ -26,7 +26,7 @@ Migration SQL is checked in and immutable after release:
 ## 2. What the v2 runner guarantees
 
 `runDatabaseMigrations(database, namespace, databaseMigrations)` uses the
-namespaced `_coreloom_migrations_v2` ledger. A row records namespace, migration
+namespaced `_flowdular_migrations_v2` ledger. A row records namespace, migration
 id, dialect id, checksum, and applied time. The checksum covers the selected
 dialect's exact SQL.
 
@@ -76,14 +76,14 @@ Every PostgreSQL tenant table includes:
 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));
+  USING (tenant_id = current_setting('flowdular.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('flowdular.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
+transaction-local `flowdular.tenant_id` on the pinned connection. Queries still
 include `WHERE tenant_id = ...` as defense in depth.
 
 ## 6. Add one migration

package/agent-template/.claude/skills/module-new/SKILL.md

@@ -142,7 +142,7 @@ export function createServerComposition(
 
 `PlatformServerContext` also carries `databases: DatabaseProvider`, `settings: ModuleSettingsRuntime`, `agentTools: PlatformToolRegistry`, `agentDefinitions: PlatformAgentRegistry`, and `capabilities: PlatformCapabilityRegistry`. The runtime shares one lazy database initialization, uses separate migration and runtime leases, and releases the runtime lease from `dispose()`; `prepare()` remains read-only. A composition may return module settings, lifecycle hooks, agent registrations, and typed cross-module capabilities as described in the focused skills.
 
-Schema: write PostgreSQL SQL in `migrations/0001_inventory_core.up.sql` and mirror it byte for byte in `databaseMigrations` as `sql: { postgresql: ... }` with an `inspectExisting` built from `postgresTenantTableState(...)`. Tenant tables enable and force row-level security with an `<table>_tenant_policy` whose `USING` and `WITH CHECK` compare `tenant_id` with `current_setting('coreloom.tenant_id', true)`; the runtime role has no superuser or `BYPASSRLS`. Repository operations use `database.transaction(..., { tenantId, access })` and retain explicit tenant predicates. Details in `migration-authoring` and `database-adapter`.
+Schema: write PostgreSQL SQL in `migrations/0001_inventory_core.up.sql` and mirror it byte for byte in `databaseMigrations` as `sql: { postgresql: ... }` with an `inspectExisting` built from `postgresTenantTableState(...)`. Tenant tables enable and force row-level security with an `<table>_tenant_policy` whose `USING` and `WITH CHECK` compare `tenant_id` with `current_setting('flowdular.tenant_id', true)`; the runtime role has no superuser or `BYPASSRLS`. Repository operations use `database.transaction(..., { tenantId, access })` and retain explicit tenant predicates. Details in `migration-authoring` and `database-adapter`.
 
 Errors: `{ error: { code, message } }`; service errors `class XServiceError extends Error { constructor(readonly code: string, message: string, readonly status = 400) }`; a `failure(error)` helper routes them to `jsonResponse(..., error.status)` and everything else to `problemResponse(error, 'The <module> operation failed.')`.
 

package/agent-template/.claude/skills/test-hardening/SKILL.md

@@ -15,7 +15,7 @@ description: >-
 
 ## 2. Repositories on an embedded PostgreSQL
 
-`createPgliteTestProvider()` from `@flowdular/sdk/database-testing` runs a real PostgreSQL inside the test process, with the same `coreloom_runtime` and `coreloom_background` roles and the same forced row-level security a deployment enforces. Booting it costs about two seconds, so a suite opens one provider per test file, migrates it once, and truncates the module's tables between cases; `.ai/references/catalog/tests/support/database.ts` is the shape (`createCatalogTestDatabase` hands out a lease per fixture, `closeCatalogTestDatabases` runs in `afterAll`). Build the service on top: `new CatalogService((await createCatalogTestDatabase()).repository)`. A database module also keeps `tests/migrations.test.ts` for SQL byte parity, fresh apply, safe pre-ledger adoption, and a clean second start. A module whose spec has no `database` capability gets a `MemoryXRepository` from the scaffold instead; a module with a database tests the database repository, never a hand-written fake, because the SQL, the ledger and the row-level security are what need testing.
+`createPgliteTestProvider()` from `@flowdular/sdk/database-testing` runs a real PostgreSQL inside the test process, with the same `flowdular_runtime` and `flowdular_background` roles and the same forced row-level security a deployment enforces. Booting it costs about two seconds, so a suite opens one provider per test file, migrates it once, and truncates the module's tables between cases; `.ai/references/catalog/tests/support/database.ts` is the shape (`createCatalogTestDatabase` hands out a lease per fixture, `closeCatalogTestDatabases` runs in `afterAll`). Build the service on top: `new CatalogService((await createCatalogTestDatabase()).repository)`. A database module also keeps `tests/migrations.test.ts` for SQL byte parity, fresh apply, safe pre-ledger adoption, and a clean second start. A module whose spec has no `database` capability gets a `MemoryXRepository` from the scaffold instead; a module with a database tests the database repository, never a hand-written fake, because the SQL, the ledger and the row-level security are what need testing.
 
 ## 3. Route recipe (from `modules/auth/tests/endpoints.test.ts`)
 
@@ -55,7 +55,7 @@ The auth middleware must have set the principal for `endpointIdentityFromContext
 - 403 on a mutation without `x-csrf-token` (`CSRF_REJECTED`) and without `origin` (`ORIGIN_REQUIRED`).
 - 400 with the stable code for each validation bound (`INVALID_INPUT`, module codes such as `INVALID_ITEM_KIND`).
 - 409 for the tenant-scoped uniqueness rule, and success for the same key in another tenant.
-- Tenant isolation: rows created for `tenant-a` are invisible to `list('tenant-b')`. The provider hands the suite the non-bypass `coreloom_runtime` role, so this runs against real forced row-level security; also assert that a call without tenant context fails with `TENANT_CONTEXT_REQUIRED`.
+- Tenant isolation: rows created for `tenant-a` are invisible to `list('tenant-b')`. The provider hands the suite the non-bypass `flowdular_runtime` role, so this runs against real forced row-level security; also assert that a call without tenant context fails with `TENANT_CONTEXT_REQUIRED`.
 - Identity: `moduleDefinition.manifest.id` equals the module id (keeps `module.json` and `src/index.ts` aligned). The scaffold writes this and the isolation case; everything else in this list is yours.
 
 Assert at the observation boundary: status code, `error.code`, returned record fields. Do not assert internal helper names, call order, or SQL text.

package/agent-template/.claude/skills/workflow-development/SKILL.md

@@ -1,9 +1,8 @@
 ---
 name: workflow-development
 description: >-
-  Build, publish, invoke, and test a workflows.core DAG through its typed graph
-  and public execution capability without bypassing agent, action, tenant, or
-  audit boundaries.
+  Author module-owned action templates, or build, publish, invoke, and test a
+  workflows.core DAG through its typed graph and public execution capability.
 ---
 # Build and integrate an agentic workflow
 
@@ -12,18 +11,22 @@ pinned agent revisions, deterministic gates, schema validators, registered
 module actions, data mappings, and terminal output. It does not own schedules or
 webhook secrets. Those remain optional concerns of `automations.core`.
 
-Read `docs/adr/0006-agentic-workflows.md`, the approved
-`modules/workflows/spec/module.yaml`, and the contracts in
-`modules/workflows/src/domain/types.ts` before changing a workflow surface.
+At the repository root, read `docs/adr/0006-agentic-workflows.md`, the approved
+`modules/workflows/spec/module.yaml`, and the owning public contracts before
+changing a workflow surface. In the Sandbox, read the approved active-module
+specification and the relevant public contract under `reference/sdk` when it is
+installed. A missing public contract is a core blocker, not a reason to invent
+one or search beyond the session workspace.
 
 ## Pick the correct extension point
 
 - A workflow definition belongs in `workflows.core` and is edited through its
   API or canvas. Do not hardcode a tenant workflow in source.
 - A business operation that a workflow may call is a versioned agent action.
-  Register it through the agents action catalog. If missing, implement it in a
-  separate `agent-tool-design` phase with permission, input, output, timeout,
-  idempotency and audit tests before returning to workflow integration.
+  Register one ordinary `AgentTool` with `context.agentTools`. Optional
+  `workflowTemplate` metadata makes that action a named palette choice through
+  `agents.actions.v2`; it creates no second handler or node kind. Use the
+  authoring recipe below when the action is part of this task.
 - A business module that starts a workflow resolves
   `workflows.execution.v1` from `context.capabilities`. It never imports a
   workflow repository or database.
@@ -33,6 +36,87 @@ Read `docs/adr/0006-agentic-workflows.md`, the approved
 - If the workflow module is absent, the capability registry returns `null`.
   Hide an optional feature or return a clear stable refusal.
 
+## Author a module-owned workflow node template
+
+An action-backed template is module source, not graph source. The business
+manager first records its stable action id, permission, named inputs and
+validation rules, output, effect, replay behavior, and success and refusal
+scenarios in the owning module's specification. In a Sandbox session, the
+operator must approve the hash of that exact spec before implementation. A
+later edit requires renewed approval. If any of these decisions are absent,
+hand the spec delta to `business-manager`; do not infer a field, permission,
+external effect, or idempotency rule from the brief.
+
+Work inside the existing role boundaries:
+
+1. `backend-engineer` owns the tenant-bound service, code-level validator,
+   endpoint or CLI target, and durable target ledger for a mutation. Validation
+   runs before any write and returns a stable bounded refusal. A repeated
+   idempotency key returns its first result; the same key with different input
+   conflicts. Ask backend to supply a missing service rather than writing in
+   `src/services/**` or `src/api/**` from the agentic role.
+2. `agentic-engineer` defines the tool under `src/agent/**`, registers it once
+   from `createServerComposition` in `src/platform.ts`, and adds behavioral
+   tests. `defineApiAgentTool` or `defineCliAgentTool` carries the existing
+   public target. `agents.core` exposes the registered action through
+   `agents.actions.v2`; the business module does not register that capability
+   or access the workflow database.
+3. Give the tool a stable dotted id, positive `contractVersion`, required
+   permission, bounded input and output JSON Schemas, `risk: 'read'` or
+   `'workspace-write'`, `idempotency: 'required'`, cancellation policy, and
+   timeout. A workspace write also needs
+   `idempotencyProtection: 'target-ledger'` backed by the service's real ledger.
+   The handler receives trusted tenant, actor, permission snapshot,
+   idempotency key, and `AbortSignal` from `AgentToolContext`; none comes from
+   graph input. Its output must satisfy its declared schema.
+4. Add static `workflowTemplate: { label, description, effect }` on that same
+   tool. The label is at most 80 characters, the description at most 240, and
+   effect is `local` or `connector-egress`. Metadata contains no code,
+   credential, or tenant value. Invalid or duplicate metadata must fail
+   composition with a safe diagnostic. A workflow-eligible tool without the
+   metadata remains in the generic action editor.
+
+The selected template becomes a normal `action` node with input, success, and
+failure ports. It pins the action id, contract version, schemas, permissions,
+risk, idempotency protection, timeout, cancellation, and effect. Changing any
+of those or the handler's behavior requires a new action identity or contract
+version. The current registry keeps one version per action id, so retain the
+old id and register a distinct id when published graphs must keep running;
+label and description may change without rebinding a published graph.
+
+Graph bindings may never supply a raw secret. `writeOnly` and
+`x-flowdular-secret` apply at every schema depth, including array items and
+alternatives. A marked field cannot carry `default`, `const`, `enum`,
+`example`, or `examples` data. A template requiring
+a raw secret input is ineligible. Accept a nonsecret opaque reference and let
+the owning module resolve a credential from its tenant-bound vault or a
+declared capability. Never put secret values in fixtures, graph definitions,
+events, audit, or error text.
+
+For `connector-egress`, the consumer module declares `connectors.core` and
+`connectors.calls.v1`, uses `caller: 'workflow'`, checks the instance's
+`allowWorkflows` consent, and passes the stable workflow side-effect key to
+the connector. Credentials remain in `connectors.core`. A replay-stable
+output may contain the recorded call id and outcome, not a response body the
+connector replay does not return. Propagate `CALL_OUTCOME_UNKNOWN` as a
+terminal failure when the remote mutation may have happened but no call was
+recorded; never send a second request just to rebuild output. A separate
+provider contract with remote idempotency or readback is required before
+retrying an uncertain mutation.
+
+Prove the module behavior at its public service or action boundary: valid
+input, structural and business validation refusal before mutation, missing
+permission, foreign tenant, same-key replay, different-input conflict,
+cancellation, and recovery around the target commit. Connector actions also
+prove absent consent and `CALL_OUTCOME_UNKNOWN` with a recorded fixture. Run a
+deterministic workflow simulation on invented, reviewed fixtures for success,
+failure, and refusal edges. Assert semantic attempts and edge outcomes, not
+real timestamps; simulation must never invoke the handler, connector, or
+network. Inspect the named template and safe run trail in Sandbox preview,
+then run scoped gates, exact-source `auto-review`, and host eject. The agent
+cannot approve the spec, install code into the running server, or push a
+repository from the Sandbox.
+
 ## Graph contract
 
 Version one is a bounded DAG. The graph contains:
@@ -41,9 +125,11 @@ Version one is a bounded DAG. The graph contains:
 - `agent`: calls one exact immutable agent revision and validates structured
   output.
 - `agent-decision`: produces one schema-valid `pass` or `fail` outcome.
+- `typed-decision`: routes one bounded typed answer through `pass` or `fail`.
 - `gate`: evaluates the versioned allowlisted logic language.
 - `validator`: validates an envelope against a pinned JSON schema.
 - `action`: calls one exact registered action contract version.
+- `human-approval`: waits for an `approvals.core` request to resolve.
 - `merge`: waits for all declared incoming paths.
 - `output`: settles the workflow with a typed result.
 

package/agent-template/docs/adr/0007-module-owned-agents.md

@@ -266,6 +266,39 @@ existing bindings in one transaction:
 - a definition absent from the sealed registry is unavailable for new work;
   retained revisions and historical runs remain untouched.
 
+Amendment (2026-10-05, `agents.core` 0.15.2): reconciliation no longer runs at
+runtime start, and a lower revision no longer fails boot.
+
+- `agents.core` opens once in every role, before its first request, capability
+  call or `startWorker()`. Opening runs its migrations, then reconciles the
+  registered definitions into the durable catalogue. When every definition
+  matches its stored revision and content hash, opening costs one catalogue read
+  and writes nothing. Otherwise it takes the advisory lock
+  `agents.core.module-catalog`, reads the catalogue again under it and writes
+  only what is still missing or behind, so roles that open together never fail
+  with a duplicate key. A failed opening fails only the request or worker start
+  that triggered it, and the next one opens again.
+- Opening never reads or writes a tenant binding. A request that lists, reads or
+  runs a module agent advances that tenant's stale binding first, inside its own
+  tenant transaction, under the binding row lock and a share lock on the
+  catalogue row, so concurrent requests advance it once. Configuring a binding
+  writes it at the served revision under the same locks. After its execution
+  workers start, the worker advances the bindings no request has touched, in
+  pages of at most 100 tenants, and logs a failing tenant without tenant data.
+  That pass never gates worker readiness.
+- Tenant-created definitions saved before the retained revision ledger are
+  adopted once. A request adopts its own tenant's owed definitions in its own
+  transaction, and the worker adopts the rest in pages after it starts.
+- An instance that registers a lower revision than the catalogue holds, such as
+  an older deployment during a rolling deploy, is superseded for that agent and
+  keeps running. It writes nothing for the agent, lists it unavailable with
+  `MODULE_AGENT_REVISION_SUPERSEDED`, refuses a binding change or a run of it
+  with status 409 and logs a warning once per process and agent. Queued runs and
+  workflow references pinned to a retained executable revision keep the
+  exact-revision contract.
+- The same revision with different content is still refused, by preparation and
+  by the opening, as `MODULE_AGENT_REVISION_DRIFT`.
+
 An old retained revision remains executable after a newer module definition is
 registered only while the owning module is still present, the selected provider
 is usable, and every required registered tool still exists. Module removal is
@@ -327,7 +360,8 @@ not change shape.
 - Business-agent definition content is immutable within one definition
   revision.
 - Duplicate ids, late registration, revision downgrade and same-revision content
-  drift fail platform boot before workers start.
+  drift fail platform boot before workers start. Since the 2026-10-05
+  amendment, a revision downgrade supersedes the agent instead.
 - Module behavior cannot be edited or deleted through tenant APIs.
 - Tenant bindings cannot enable a tool outside the code allowlist.
 - Every execution is tenant-scoped and uses the initiating Actor and trusted

package/agent-template/docs/agent-contract.md

@@ -14,7 +14,7 @@ Use the already selected task skill. Consult `.ai/references/catalog` for implem
 3. Identifiers: module, permission and capability ids match `^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$`. `inventory.core` lives in `modules/inventory` as `@flowdular/module-inventory`; permissions are `<module>.<entity>.read` and `<module>.<entity>.manage`.
 4. A module is created only from a spec with `status: approved`. An agent never initiates, infers, or grants approval from its own judgment. After a current, explicit user instruction naming the spec, a host coding agent may record that decision mechanically by following `spec-approval`; a sandbox specialist can only request approval, and the operator route records the exact approved hash. Spec `permissions[].id` equal the constants in `src/acl/permissions.ts`: the spec is what `auth sync-scopes` grants.
 5. Every endpoint is `defineEndpoint` from `@flowdular/sdk/server` with `access: { kind: 'permission', permission }` and `resolveIdentity: endpointIdentityFromContext`. Deny by default; a public endpoint needs a written reason. No raw `new ServerRoute` outside `modules/auth`.
-6. The tenant id comes only from `principalFromContext(octane)!.tenantId`, never from the body, query or headers. Every query on a tenant-owned table filters by `tenant_id`; unique constraints and indexes start with `tenant_id`; SQL uses bound parameters. PostgreSQL tenant tables also enable and force row-level security with `USING` and `WITH CHECK` policies bound to transaction-local `coreloom.tenant_id`. Every repository operation runs through `database.transaction(..., { tenantId, access })`; the runtime role is never a superuser and never has `BYPASSRLS`, while a separate migration lease may own DDL. `WHERE tenant_id = ...` remains defense in depth.
+6. The tenant id comes only from `principalFromContext(octane)!.tenantId`, never from the body, query or headers. Every query on a tenant-owned table filters by `tenant_id`; unique constraints and indexes start with `tenant_id`; SQL uses bound parameters. PostgreSQL tenant tables also enable and force row-level security with `USING` and `WITH CHECK` policies bound to transaction-local `flowdular.tenant_id`. Every repository operation runs through `database.transaction(..., { tenantId, access })`; the runtime role is never a superuser and never has `BYPASSRLS`, while a separate migration lease may own DDL. `WHERE tenant_id = ...` remains defense in depth.
 7. Every mutation calls `sessionMutationDenial(octane, auth)` first and reads its body with `readJsonObject` plus `requiredString`, `optionalString`, `requiredInteger`. Clients send `content-type: application/json`, `x-csrf-token`, and `credentials: 'same-origin'`.
 8. Routes mount only through `src/platform.ts` exporting `createServerComposition(context)` with `platform.server: true` in `module.json` and a `./platform` export in `package.json`; the context carries `auth`, `settings`, `agentTools`, `agentDefinitions`, `capabilities` and `databases`. A database module passes `context.databases` into one runtime, which acquires and releases one provider lease lazily; `prepare` stays read-only and never opens a database. A composition may return `settings`, read-only `prepare`, `start`, background-work `stop`, and final `dispose`. Client contributions mount only through `createClientContribution(context)` in `src/client/index.ts` with `platform.client: true`. `pnpm flowdular module validate` fails on a missing entry (`PLATFORM_*`).
 9. Never edit the composition by hand: `platform/octane.config.ts`, `platform/src/App.tsrx`, `platform/src/generated/**`, `platform/package.json` dependencies and `modules.enabled` in `flowdular.json` are written by `pnpm flowdular module enable <id> --apply` and `pnpm flowdular module sync --apply`.
@@ -26,7 +26,7 @@ Use the already selected task skill. Consult `.ai/references/catalog` for implem
 15. One screen, form, table or stateful region per named component. Records own the page; create and edit happen in a `Drawer`. Every screen shows loading, empty, error, populated and denied.
 16. Tests live in `tests/*.test.ts`: identity, tenant isolation, uniqueness, one 401 and one 403 per endpoint, each validation bound. Repository behavior uses `createTestDatabaseProvider()` from `@flowdular/sdk/database-testing`: PGlite locally and isolated server PostgreSQL in CI. Open one provider per test file, migrate once, and truncate module tables between cases (`modules/profile/tests/support/database.ts`). Tenancy tests use two tenants, prove `TENANT_CONTEXT_REQUIRED` without a transaction tenant id, prove RLS prevents cross-tenant reads and writes under the non-bypass runtime role, and cover `WITH CHECK`. Tenant fixture work also supplies tenant context on a migration connection. The sandbox `tests` gate passes with zero tests, so an empty suite is a defect.
 17. Translations are live. Every module contribution registers all declared `translations/*.json` bundles, user-facing copy uses fully qualified `t('<module>.<key>')` keys, navigation labels are lazy getters, locale-aware formatting uses `activeLocale()`, and every locale has the same key set, where a plural family (`<key>.one`/`.other`, plus `.few`/`.many` in `pl`, read as `t(key, { count })`) counts as one key. `module validate` rejects missing files, key drift, and missing static translation keys.
-18. Numbered migration SQL is immutable source. `migrations/000N_<module>_<name>.up.sql` and `.down.sql` are PostgreSQL and the only schema source; there is no dialect subdirectory. `src/services/migration.ts` mirrors every `.up.sql` byte for byte as `databaseMigrations: readonly DatabaseMigration[]` with `sql: { postgresql: ... }`, and the runtime calls `runDatabaseMigrations` through its provider lease. The namespaced `_coreloom_migrations_v2` ledger records the checksum, adopts only an explicit complete `inspectExisting` result (`postgresTenantTableState` is the standard check), and refuses drift, duplicates, or partial schema. Add a new numbered, additive migration instead of changing existing bytes. A tenant table's migration includes enabled and forced RLS plus a tenant policy, with the policy behavior covered by tests.
+18. Numbered migration SQL is immutable source. `migrations/000N_<module>_<name>.up.sql` and `.down.sql` are PostgreSQL and the only schema source; there is no dialect subdirectory. `src/services/migration.ts` mirrors every `.up.sql` byte for byte as `databaseMigrations: readonly DatabaseMigration[]` with `sql: { postgresql: ... }`, and the runtime calls `runDatabaseMigrations` through its provider lease. The namespaced `_flowdular_migrations_v2` ledger records the checksum, adopts only an explicit complete `inspectExisting` result (`postgresTenantTableState` is the standard check), and refuses drift, duplicates, or partial schema. Add a new numbered, additive migration instead of changing existing bytes. A tenant table's migration includes enabled and forced RLS plus a tenant policy, with the policy behavior covered by tests.
 19. Module CLI commands live in `src/cli/commands.json` and `src/cli/index.ts`, metadata-identical, inside the module namespace.
 20. Passwords, session tokens and provider credentials never leave `auth.core` (or the `agents.core` vault) and never appear in logs, audit metadata or responses.
 21. `setup quick` and `auth greenfield` are destructive local resets. Preview first, stop the app, never point them at a custom or deployed database.

package/agent-template/docs/cli.md

@@ -47,8 +47,29 @@ flowdular database restore --input <dir> --apply --confirm restore-database
 flowdular setup check                              # alias of doctor
 flowdular setup quick [--apply --confirm reset-local-auth]
 flowdular setup migrate-state [--apply --confirm migrate-legacy-state]
+flowdular deploy targets                            # runtime support and launch modes
+flowdular deploy plan <target> [--json]              # read-only provider preflight
+flowdular deploy start docker [--apply]              # local Compose launch; without --apply returns plan
+flowdular deploy start vercel [--apply]              # provision and deploy to Vercel Production; without --apply returns plan
 ```
 
+`deploy start docker --apply` prints a one-time setup token, so it refuses
+`--json` and redirected output and must run in a private interactive terminal. The deployment targets are
+documented in [infra/README.md](../infra/README.md). `deploy plan vercel`
+checks the build source and links to Vercel import when the branch is pushed.
+
+`deploy start vercel --apply` drives the signed-in Vercel CLI: it provisions
+Neon PostgreSQL and its roles, writes the stable keys to
+`.flowdular/deploy/vercel-<project id>.env` (mode 0600) before uploading them
+through stdin, connects a private Blob store and deploys to Production. While
+the database has no workspace it prints a one-time token for `/setup`, where the
+first workspace and owner are created in the browser; Vercel holds only the
+token's SHA-256. That gives it the same terminal rules as the Docker launch.
+`--database-url-env NAME` takes the owner URL from a variable instead of Neon;
+`--plan hobby|pro` overrides the plan read from `vercel whoami --json`;
+`--project`, `--scope`, `--origin` and `--cron` are optional. A rerun resumes
+without regenerating keys. See [infra/vercel/README.md](../infra/vercel/README.md).
+
 ### Authoring a migration
 
 `migration new` writes exactly two files,
@@ -59,7 +80,7 @@ already filled in. Replace the placeholder columns with the real schema.
 `migration verify` then checks that every applied ledger checksum still matches,
 that every tenant table a migration leaves behind has `ENABLE ROW LEVEL
 SECURITY`, `FORCE ROW LEVEL SECURITY` and a tenant policy declared after the
-last statement that puts the table in place, that a `coreloom_background` policy
+last statement that puts the table in place, that a `flowdular_background` policy
 grants no more than `FOR SELECT`, and that every `migrations/*.up.sql` file has
 a matching id in `databaseMigrations` and the other way round.
 
@@ -198,6 +219,6 @@ per-package seconds in `scripts/test-weights.json`. A new package without a
 weight counts as 30 seconds; refresh the file from a CI run when the shards
 drift apart.
 
-## Official module distribution
+## Module Studio distribution
 
-`module search`, `module info`, `module install`, `module update`, `module recover`, and `module validate --locked` manage reviewed external source. See [the distribution contract](module-distribution.md) for flags, trust, activation and recovery.
+`module source`, `module search`, `module info`, `module plan`, `module apply`, `module recover`, and `module validate --locked` manage reviewed external source. See [Module Studio](module-distribution.md) for flags, trust, activation and recovery.