@weave-kit/engine 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -3,6 +3,23 @@
 All notable changes to `@weave-kit/engine`. Format follows [Keep a Changelog](https://keepachangelog.com/);
 the project uses [Semantic Versioning](https://semver.org/).
 
+## [1.3.0] - 2026-10-11
+
+Additive (no `CONTRACT_VERSION` bump): MCP surface + formula catalog.
+
+### Added
+
+- **MCP approval tools.** When an approval queue is wired and the session identity holds an
+  `adapters.mcp.adminRoles` role, the surface exposes `list_approvals` / `approve_approval` /
+  `reject_approval` (names frozen in `APPROVAL_TOOLS`). Resolution is audited by the queue facade and
+  the tool call by `callProtected` — the same admin gate as the REST `/approvals` routes.
+- **MCP resources.** The schema is exposed as readable resources (`weavekit://objects`,
+  `weavekit://objects/{name}`), derived from the registry and RBAC-filtered per identity (mirrors
+  `list_objects` / `describe_object`). The server now advertises a `resources` capability.
+- **Formula catalog.** New functions (single-source `FORMULA_FUNCTIONS`): `lower` / `upper` / `trim` /
+  `length` / `substr` / `replace`, `abs` / `floor` / `ceil` / `pow`, and null-coalescing `coalesce`,
+  with arity/type validation.
+
 ## [1.2.0] - 2026-10-11
 
 Additive (no `CONTRACT_VERSION` bump): seams for the Cloud/Console control plane.

package/README.md

@@ -1,210 +1,210 @@
-<h1 align="center">Let AI agents operate your data — safely</h1>
-
-Define your data model once in `schema.json`, and WeaveKit compiles it into PostgreSQL tables, REST
-and GraphQL APIs with row- and field-level RBAC, an immutable audit log with execution evidence, and
-an MCP tool surface that AI agents call with typed tools — never raw SQL. Self-hosted: your data
-stays in your database.
-
-```
-objects/leads/schema.json   →   Git commit (source of truth)
-                                PostgreSQL tables + indexes + RLS
-                                REST + GraphQL APIs (CRUD + RBAC)
-                                MCP tools (per-identity surface + guardrails + approvals)
-                                Immutable audit log + execution evidence
-                                TypeScript types
-```
-
-## Why WeaveKit
-
-- **Safe by construction** — every agent action is authorized by row- and field-level RBAC and
-  native PostgreSQL RLS, and recorded in an immutable audit log. Guardrails (and optional
-  approvals) sit in front.
-- **Your model is a Git repository** — schema, hooks and policies are files you review, diff and
-  revert; the engine commits every change for you, and PostgreSQL is a derived cache.
-- **One agent, many users** — each MCP call carries the acting user's identity (on-behalf-of), and
-  the engine compiles a per-identity tool surface: a salesperson's agent sees only their own leads,
-  a finance agent cannot read sales notes. Prompt injection cannot bypass RBAC/RLS.
-- **Bring your existing PostgreSQL** — point the engine at a live database and declare the tables
-  you want to expose; existing tables stay read-only unless you explicitly allow additive DDL, and
-  `weave introspect` can reverse-model them into `schema.json`.
-- **Typed tools in minutes, not weeks** — hand-writing an MCP server (tools + permissions + audit)
-  for a few tables takes days; here it is a few `schema.json` files, and new fields or tables
-  extend the tool surface automatically.
-- **More than MCP** — the same schema also drives REST and GraphQL APIs and generated TypeScript
-  types, so people and agents share one governed contract.
-- **Self-hosted** — the engine runs in your environment; no data leaves your database.
-
-## How it works
-
-`weave` reads `objects/<name>/schema.json`, validates it, and syncs it to PostgreSQL (state-diff
-migrations; existing tables stay read-only unless you allow additive DDL). The same metadata drives
-the REST routes and the MCP tool surface, and the data-access layer enforces RBAC and audits every
-write.
-
-## Features
-
-- **Git-versioned metadata** — schema, hooks and policies are plain files in your repository; every
-  change is a scoped, atomic Git commit, so review, history and rollback come for free. PostgreSQL
-  stays a derived cache.
-- **Schema as the source of truth** — `objects/<name>/schema.json` drives the tables, REST API and MCP
-  surface; state-diff migrations to PostgreSQL.
-- **Custom field types** — register business-semantic types (`money`, `address`, …) as thin, namespaced
-  layers over a built-in primitive; they inherit storage, REST/MCP/OpenAPI schemas and generated
-  types. Declared in a project-local, Git-committed `field-types/` directory.
-- **Named enums** — declare a shared enum once in `enums/` and reference it from any object by
-  `enumType`; every field shares one native PostgreSQL type and one set of per-value labels.
-- **Governed REST API** — object CRUD with row-level (`all`/`own`/`department`) and field-level RBAC
-  and a uniform error contract.
-- **MCP tool surface** — a streamable HTTP endpoint at `/mcp` with a per-identity tool surface and
-  guardrails.
-- **GraphQL API** — an opt-in read/write GraphQL endpoint compiled from the same `schema.json`, with
-  nested relations, the same RBAC/audit, per-request batching and query hardening.
-- **Schema revisions & atomic deploys** — `weave deploy plan` previews the diff; `weave deploy apply`
-  commits the DDL, the metadata cache and a global **schema revision** in one transaction (no
-  half-applied deploys).
-- **Agent execution pipeline** — every write and tool call runs through one
-  Plan → Validate → Authorize → Guardrail → Approval → Execute → Commit → Evidence pipeline, so
-  guardrails and approvals cover REST, MCP and GraphQL alike; enable `evidence` to record a
-  `weavekit_evidence` row per execution (correlated by request / trace / schema revision).
-- **Query budget** — bound a read/query across the engine: rows, filters and sorts in data-access,
-  joins / SQL length / statement timeout in restricted SQL, and GraphQL depth.
-- **Multi-tenancy (row)** — mark a field `"tenant": true` and every read/write is scoped to the
-  subject's tenant (RBAC row scope + PostgreSQL RLS + audit); single-tenant by default.
-- **Audit log** — an immutable event log for data mutations, with durability modes
-  (`best-effort` / `transactional` / `durable`) and a keyset-cursor query.
-- **Observability** — a low-level metrics/trace seam (`MetricsSink` / `TraceSink`, `METRIC_NAMES`)
-  that emits request latency, RBAC denials, query-budget rejects and W3C `traceparent`-correlated
-  spans; the engine ships a no-op default and brings no backend.
-- **Sandboxed hooks** — `*.server.js` lifecycle hooks running in isolated workers.
-- **Type generation** — object-level TypeScript types derived from the schema.
-- **Live events** — an SSE stream with replay.
-- **Operations** — `weave doctor` preflight, health / readiness / version endpoints, request rate
-  limiting, CORS and structured logging.
-
-## Requirements
-
-- Node.js 22+
-- PostgreSQL 12+ (the engine's tested floor; `weave doctor` reports the version)
-
-## Quick start
-
-```sh
-npm create weavekit-app my-app -- --type=agent
-cd my-app
-cp .env.example .env      # set DATABASE_URL
-weave migrate             # state-diff migration: schema.json → PostgreSQL tables (+ metadata cache)
-weave dev                 # http://localhost:3000 — hot reload
-weave types               # object-level TS types → generated/types.ts
-```
-
-**Existing database?** Reverse-model it instead of authoring from scratch:
-
-```sh
-weave introspect          # live tables → objects/<table>/schema.json (read-only)
-weave schema:map          # schema field ↔ PostgreSQL column mapping + drift
-```
-
-**Connect an agent** (MCP is available at `/mcp`):
-
-```sh
-weave mcp:config          # ready-to-paste config for Claude Code / Cursor / VS Code / Claude Desktop
-```
-
-## Documentation
-
-Full documentation: **[docs.weavekit.io/engine](https://docs.weavekit.io/engine)**
-
-- [Getting started](https://docs.weavekit.io/engine/guides/getting-started) — scaffold, migrate, run, consume
-- [Git-versioned metadata](https://docs.weavekit.io/engine/guides/model/git-versioned-metadata) — your data model as reviewable Git commits
-- [Schema guide](https://docs.weavekit.io/engine/guides/model/schema) · [RBAC](https://docs.weavekit.io/engine/guides/access/rbac) · [Multi-tenancy](https://docs.weavekit.io/engine/guides/access/multi-tenancy) · [Formulas](https://docs.weavekit.io/engine/guides/model/formulas) · [Audit](https://docs.weavekit.io/engine/guides/platform/audit)
-- [CLI reference](https://docs.weavekit.io/engine/guides/platform/cli) · [Observability](https://docs.weavekit.io/engine/guides/platform/observability) · [MCP](https://docs.weavekit.io/engine/guides/agents/mcp) · [Execution & evidence](https://docs.weavekit.io/engine/guides/agents/execution-and-evidence) · [Script hooks](https://docs.weavekit.io/engine/guides/automation/script-hooks)
-- [Custom tools & guardrails](https://docs.weavekit.io/engine/guides/agents/custom-tools-and-guardrails) · [Query budget](https://docs.weavekit.io/engine/guides/automation/query-budget) · [Custom field types](https://docs.weavekit.io/engine/reference/schema/custom-field-types) · [Quotas](https://docs.weavekit.io/engine/guides/automation/quotas) · [Inbound events](https://docs.weavekit.io/engine/guides/integration/ingress)
-- [Public API & dependency budget](https://docs.weavekit.io/engine/reference/api/public-api) · [Enterprise seams](https://docs.weavekit.io/engine/reference/enterprise-seams) · [Contract freeze](https://docs.weavekit.io/engine/reference/contract-freeze)
-- [Practices & operations](https://docs.weavekit.io/engine/practices/agent/existing-crm-to-mcp) · [Release checklist](https://docs.weavekit.io/engine/operations/release) — real integration and deployment walkthroughs
-
-The Markdown sources live in [`docs/`](https://github.com/weavekit/engine/tree/main/docs).
-
-## Programmatic use
-
-```ts
-import { createEngine } from '@weave-kit/engine';
-
-const engine = await createEngine({
-  databaseUrl: process.env.DATABASE_URL,
-  schemaDir: '.', // project root containing objects/
-  auth: { source: { 'sk-admin': { id: 'admin', roles: ['admin'] } } },
-});
-await engine.app.listen({ port: 3000 });
-```
-
-## Metadata
-
-- **Objects** live in `objects/<name>/schema.json` (one directory per object; the directory name must
-  equal the object name).
-- **`weavekit.config.ts`** is the single wiring point — a default export `satisfies EngineConfig`
-  (`schemaDir`, `auth`, `adapters`, `subsystems`).
-- `schema.json` is versioned in Git and is the source of truth; the engine syncs it to PostgreSQL and
-  a metadata cache.
-
-## CLI
-
-| Command | Description |
-| --- | --- |
-| `weave migrate [--dry-run]` | State-diff migration + metadata cache + auto-commit |
-| `weave deploy plan` / `weave deploy apply` | Preview / atomically apply schema changes and record a global schema revision |
-| `weave doctor` | Read-only preflight (connection, PostgreSQL compatibility, drift, system tables, RLS + sandbox) |
-| `weave dev [--port]` | Run with hot reload |
-| `weave build` | Bundle the server entry (esbuild) |
-| `weave test` | Proxy the project test suite |
-| `weave types [--outdir]` | Compile `schema.json` into object-level TS types |
-| `weave introspect` | Reverse-model an existing Postgres DB into `objects/*/schema.json` |
-| `weave schema:map [object] [--drift]` | Report the schema field ↔ PostgreSQL column mapping |
-| `weave schema:upgrade [--dry-run]` | Upgrade `objects/*/schema.json` to the current format version |
-| `weave openapi [--out] [--generic] [--server]` | Emit an OpenAPI 3.1 document for the REST API |
-| `weave graphql:schema [--out]` | Emit the GraphQL SDL for this project |
-| `weave mcp:config [--host]` | Print MCP client config for this project's `/mcp` endpoint |
-| `weave connect` | Connect a self-hosted engine out to a governance tunnel endpoint |
-| `weave object:create <name>` | Scaffold `objects/<name>/schema.json` + `server.js` hooks |
-| `weave field:add <object>` | Add a validated field to a schema |
-| `weave field-type:list` | List built-in + registered field types |
-| `weave field-type:check` | Validate registrations + schemas against the registry |
-| `weave enum:list` | List declared named enums (`enums/<name>.json`) |
-| `weave enum:check` | Validate enum declarations + schema references |
-| `weave module:add` / `module:remove <name>` | Enable/disable an optional subsystem (audit/script/workflow) |
-
-## Object-level types
-
-```sh
-weave types   # → generated/types.ts
-```
-
-```ts
-import type { Lead } from './generated/types';
-import { createClient } from '@weave-kit/client';
-
-const leads = createClient({ baseUrl, apiKey }).objects<Lead>('lead');
-const { rows } = await leads.find({ filter: { status: 'open' } });
-```
-
-## Development
-
-```sh
-npm install
-npm run build        # tsc → dist
-npm test             # unit + e2e (e2e needs DATABASE_URL)
-npm run test:coverage # coverage gate on security-critical paths
-npm run typecheck
-npm run lint
-node scripts/check-exports.mjs  # verify package exports + contract names
-```
-
-Issues and pull requests are welcome. See [`AGENTS.md`](AGENTS.md) for architecture notes and
-contribution invariants.
-
-## Support
-
-Questions, bug reports and security reports: **support@weavekit.io**.
-
-## License
-
-[MIT](LICENSE) · For support, contact **support@weavekit.io**.
+<h1 align="center">Let AI agents operate your data — safely</h1>
+
+Define your data model once in `schema.json`, and WeaveKit compiles it into PostgreSQL tables, REST
+and GraphQL APIs with row- and field-level RBAC, an immutable audit log with execution evidence, and
+an MCP tool surface that AI agents call with typed tools — never raw SQL. Self-hosted: your data
+stays in your database.
+
+```
+objects/leads/schema.json   →   Git commit (source of truth)
+                                PostgreSQL tables + indexes + RLS
+                                REST + GraphQL APIs (CRUD + RBAC)
+                                MCP tools (per-identity surface + guardrails + approvals)
+                                Immutable audit log + execution evidence
+                                TypeScript types
+```
+
+## Why WeaveKit
+
+- **Safe by construction** — every agent action is authorized by row- and field-level RBAC and
+  native PostgreSQL RLS, and recorded in an immutable audit log. Guardrails (and optional
+  approvals) sit in front.
+- **Your model is a Git repository** — schema, hooks and policies are files you review, diff and
+  revert; the engine commits every change for you, and PostgreSQL is a derived cache.
+- **One agent, many users** — each MCP call carries the acting user's identity (on-behalf-of), and
+  the engine compiles a per-identity tool surface: a salesperson's agent sees only their own leads,
+  a finance agent cannot read sales notes. Prompt injection cannot bypass RBAC/RLS.
+- **Bring your existing PostgreSQL** — point the engine at a live database and declare the tables
+  you want to expose; existing tables stay read-only unless you explicitly allow additive DDL, and
+  `weave introspect` can reverse-model them into `schema.json`.
+- **Typed tools in minutes, not weeks** — hand-writing an MCP server (tools + permissions + audit)
+  for a few tables takes days; here it is a few `schema.json` files, and new fields or tables
+  extend the tool surface automatically.
+- **More than MCP** — the same schema also drives REST and GraphQL APIs and generated TypeScript
+  types, so people and agents share one governed contract.
+- **Self-hosted** — the engine runs in your environment; no data leaves your database.
+
+## How it works
+
+`weave` reads `objects/<name>/schema.json`, validates it, and syncs it to PostgreSQL (state-diff
+migrations; existing tables stay read-only unless you allow additive DDL). The same metadata drives
+the REST routes and the MCP tool surface, and the data-access layer enforces RBAC and audits every
+write.
+
+## Features
+
+- **Git-versioned metadata** — schema, hooks and policies are plain files in your repository; every
+  change is a scoped, atomic Git commit, so review, history and rollback come for free. PostgreSQL
+  stays a derived cache.
+- **Schema as the source of truth** — `objects/<name>/schema.json` drives the tables, REST API and MCP
+  surface; state-diff migrations to PostgreSQL.
+- **Custom field types** — register business-semantic types (`money`, `address`, …) as thin, namespaced
+  layers over a built-in primitive; they inherit storage, REST/MCP/OpenAPI schemas and generated
+  types. Declared in a project-local, Git-committed `field-types/` directory.
+- **Named enums** — declare a shared enum once in `enums/` and reference it from any object by
+  `enumType`; every field shares one native PostgreSQL type and one set of per-value labels.
+- **Governed REST API** — object CRUD with row-level (`all`/`own`/`department`) and field-level RBAC
+  and a uniform error contract.
+- **MCP tool surface** — a streamable HTTP endpoint at `/mcp` with a per-identity tool surface and
+  guardrails.
+- **GraphQL API** — an opt-in read/write GraphQL endpoint compiled from the same `schema.json`, with
+  nested relations, the same RBAC/audit, per-request batching and query hardening.
+- **Schema revisions & atomic deploys** — `weave deploy plan` previews the diff; `weave deploy apply`
+  commits the DDL, the metadata cache and a global **schema revision** in one transaction (no
+  half-applied deploys).
+- **Agent execution pipeline** — every write and tool call runs through one
+  Plan → Validate → Authorize → Guardrail → Approval → Execute → Commit → Evidence pipeline, so
+  guardrails and approvals cover REST, MCP and GraphQL alike; enable `evidence` to record a
+  `weavekit_evidence` row per execution (correlated by request / trace / schema revision).
+- **Query budget** — bound a read/query across the engine: rows, filters and sorts in data-access,
+  joins / SQL length / statement timeout in restricted SQL, and GraphQL depth.
+- **Multi-tenancy (row)** — mark a field `"tenant": true` and every read/write is scoped to the
+  subject's tenant (RBAC row scope + PostgreSQL RLS + audit); single-tenant by default.
+- **Audit log** — an immutable event log for data mutations, with durability modes
+  (`best-effort` / `transactional` / `durable`) and a keyset-cursor query.
+- **Observability** — a low-level metrics/trace seam (`MetricsSink` / `TraceSink`, `METRIC_NAMES`)
+  that emits request latency, RBAC denials, query-budget rejects and W3C `traceparent`-correlated
+  spans; the engine ships a no-op default and brings no backend.
+- **Sandboxed hooks** — `*.server.js` lifecycle hooks running in isolated workers.
+- **Type generation** — object-level TypeScript types derived from the schema.
+- **Live events** — an SSE stream with replay.
+- **Operations** — `weave doctor` preflight, health / readiness / version endpoints, request rate
+  limiting, CORS and structured logging.
+
+## Requirements
+
+- Node.js 22+
+- PostgreSQL 12+ (the engine's tested floor; `weave doctor` reports the version)
+
+## Quick start
+
+```sh
+npm create weavekit-app my-app -- --type=agent
+cd my-app
+cp .env.example .env      # set DATABASE_URL
+weave migrate             # state-diff migration: schema.json → PostgreSQL tables (+ metadata cache)
+weave dev                 # http://localhost:3000 — hot reload
+weave types               # object-level TS types → generated/types.ts
+```
+
+**Existing database?** Reverse-model it instead of authoring from scratch:
+
+```sh
+weave introspect          # live tables → objects/<table>/schema.json (read-only)
+weave schema:map          # schema field ↔ PostgreSQL column mapping + drift
+```
+
+**Connect an agent** (MCP is available at `/mcp`):
+
+```sh
+weave mcp:config          # ready-to-paste config for Claude Code / Cursor / VS Code / Claude Desktop
+```
+
+## Documentation
+
+Full documentation: **[docs.weavekit.io/engine](https://docs.weavekit.io/engine)**
+
+- [Getting started](https://docs.weavekit.io/engine/guides/getting-started) — scaffold, migrate, run, consume
+- [Git-versioned metadata](https://docs.weavekit.io/engine/guides/model/git-versioned-metadata) — your data model as reviewable Git commits
+- [Schema guide](https://docs.weavekit.io/engine/guides/model/schema) · [RBAC](https://docs.weavekit.io/engine/guides/access/rbac) · [Multi-tenancy](https://docs.weavekit.io/engine/guides/access/multi-tenancy) · [Formulas](https://docs.weavekit.io/engine/guides/model/formulas) · [Audit](https://docs.weavekit.io/engine/guides/platform/audit)
+- [CLI reference](https://docs.weavekit.io/engine/guides/platform/cli) · [Observability](https://docs.weavekit.io/engine/guides/platform/observability) · [MCP](https://docs.weavekit.io/engine/guides/agents/mcp) · [Execution & evidence](https://docs.weavekit.io/engine/guides/agents/execution-and-evidence) · [Script hooks](https://docs.weavekit.io/engine/guides/automation/script-hooks)
+- [Custom tools & guardrails](https://docs.weavekit.io/engine/guides/agents/custom-tools-and-guardrails) · [Query budget](https://docs.weavekit.io/engine/guides/automation/query-budget) · [Custom field types](https://docs.weavekit.io/engine/reference/schema/custom-field-types) · [Quotas](https://docs.weavekit.io/engine/guides/automation/quotas) · [Inbound events](https://docs.weavekit.io/engine/guides/integration/ingress)
+- [Public API & dependency budget](https://docs.weavekit.io/engine/reference/api/public-api) · [Enterprise seams](https://docs.weavekit.io/engine/reference/enterprise-seams) · [Contract freeze](https://docs.weavekit.io/engine/reference/contract-freeze)
+- [Practices & operations](https://docs.weavekit.io/engine/practices/agent/existing-crm-to-mcp) · [Release checklist](https://docs.weavekit.io/engine/operations/release) — real integration and deployment walkthroughs
+
+The Markdown sources live in [`docs/`](https://github.com/weavekit/engine/tree/main/docs).
+
+## Programmatic use
+
+```ts
+import { createEngine } from '@weave-kit/engine';
+
+const engine = await createEngine({
+  databaseUrl: process.env.DATABASE_URL,
+  schemaDir: '.', // project root containing objects/
+  auth: { source: { 'sk-admin': { id: 'admin', roles: ['admin'] } } },
+});
+await engine.app.listen({ port: 3000 });
+```
+
+## Metadata
+
+- **Objects** live in `objects/<name>/schema.json` (one directory per object; the directory name must
+  equal the object name).
+- **`weavekit.config.ts`** is the single wiring point — a default export `satisfies EngineConfig`
+  (`schemaDir`, `auth`, `adapters`, `subsystems`).
+- `schema.json` is versioned in Git and is the source of truth; the engine syncs it to PostgreSQL and
+  a metadata cache.
+
+## CLI
+
+| Command | Description |
+| --- | --- |
+| `weave migrate [--dry-run]` | State-diff migration + metadata cache + auto-commit |
+| `weave deploy plan` / `weave deploy apply` | Preview / atomically apply schema changes and record a global schema revision |
+| `weave doctor` | Read-only preflight (connection, PostgreSQL compatibility, drift, system tables, RLS + sandbox) |
+| `weave dev [--port]` | Run with hot reload |
+| `weave build` | Bundle the server entry (esbuild) |
+| `weave test` | Proxy the project test suite |
+| `weave types [--outdir]` | Compile `schema.json` into object-level TS types |
+| `weave introspect` | Reverse-model an existing Postgres DB into `objects/*/schema.json` |
+| `weave schema:map [object] [--drift]` | Report the schema field ↔ PostgreSQL column mapping |
+| `weave schema:upgrade [--dry-run]` | Upgrade `objects/*/schema.json` to the current format version |
+| `weave openapi [--out] [--generic] [--server]` | Emit an OpenAPI 3.1 document for the REST API |
+| `weave graphql:schema [--out]` | Emit the GraphQL SDL for this project |
+| `weave mcp:config [--host]` | Print MCP client config for this project's `/mcp` endpoint |
+| `weave connect` | Connect a self-hosted engine out to a governance tunnel endpoint |
+| `weave object:create <name>` | Scaffold `objects/<name>/schema.json` + `server.js` hooks |
+| `weave field:add <object>` | Add a validated field to a schema |
+| `weave field-type:list` | List built-in + registered field types |
+| `weave field-type:check` | Validate registrations + schemas against the registry |
+| `weave enum:list` | List declared named enums (`enums/<name>.json`) |
+| `weave enum:check` | Validate enum declarations + schema references |
+| `weave module:add` / `module:remove <name>` | Enable/disable an optional subsystem (audit/script/workflow) |
+
+## Object-level types
+
+```sh
+weave types   # → generated/types.ts
+```
+
+```ts
+import type { Lead } from './generated/types';
+import { createClient } from '@weave-kit/client';
+
+const leads = createClient({ baseUrl, apiKey }).objects<Lead>('lead');
+const { rows } = await leads.find({ filter: { status: 'open' } });
+```
+
+## Development
+
+```sh
+npm install
+npm run build        # tsc → dist
+npm test             # unit + e2e (e2e needs DATABASE_URL)
+npm run test:coverage # coverage gate on security-critical paths
+npm run typecheck
+npm run lint
+node scripts/check-exports.mjs  # verify package exports + contract names
+```
+
+Issues and pull requests are welcome. See [`AGENTS.md`](AGENTS.md) for architecture notes and
+contribution invariants.
+
+## Support
+
+Questions, bug reports and security reports: **support@weavekit.io**.
+
+## License
+
+[MIT](LICENSE) · For support, contact **support@weavekit.io**.

package/dist/adapters/mcp/approvals.d.ts

@@ -0,0 +1,5 @@
+import type { McpToolResult, ToolExecContext } from './types.js';
+export declare function listApprovalsHandler(args: Record<string, unknown>, ctx: ToolExecContext): Promise<McpToolResult>;
+export declare function approveApprovalHandler(args: Record<string, unknown>, ctx: ToolExecContext): Promise<McpToolResult>;
+export declare function rejectApprovalHandler(args: Record<string, unknown>, ctx: ToolExecContext): Promise<McpToolResult>;
+//# sourceMappingURL=approvals.d.ts.map

package/dist/adapters/mcp/approvals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approvals.d.ts","sourceRoot":"","sources":["../../../src/adapters/mcp/approvals.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AA8CjE,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,eAAe,GACnB,OAAO,CAAC,aAAa,CAAC,CAOxB;AAoBD,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,eAAe,GACnB,OAAO,CAAC,aAAa,CAAC,CAExB;AAED,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,eAAe,GACnB,OAAO,CAAC,aAAa,CAAC,CAExB"}

package/dist/adapters/mcp/approvals.js

@@ -0,0 +1,69 @@
+import { APPROVAL_STATUSES, APPROVAL_TOOLS, SchemaError } from '../../core/index.js';
+import { callProtected, textResult } from './tools.js';
+/**
+ * Approval-queue MCP tools (`list_approvals` / `approve_approval` /
+ * `reject_approval`). They mirror the REST `/approvals` routes: admin-gated
+ * (the queue carries request arguments) and backed by the same injected
+ * `ToolApprovals` queue — resolution is audited by the queue facade, the tool
+ * call itself is audited here via `callProtected`.
+ */
+const VALID_STATUSES = new Set(Object.values(APPROVAL_STATUSES));
+/**
+ * Fail-closed gate: the queue must be wired and the caller must carry a role
+ * listed in `adminRoles`. The compiled surface already filters to admins; this
+ * re-check is the execution-layer double (mirrors the object-RBAC double layer).
+ */
+function requireApprovals(ctx) {
+    const approvals = ctx.engine.approvals;
+    const admin = new Set(ctx.engine.adminRoles ?? []);
+    if (approvals === undefined || !ctx.session.user.roles.some((role) => admin.has(role))) {
+        throw new SchemaError('rbac.denied.update', { object: 'approvals', role: ctx.session.user.roles.join(',') }, ctx.engine.locale);
+    }
+    return approvals;
+}
+function parseFilter(args, ctx) {
+    const filter = {};
+    const status = args.status;
+    if (status !== undefined) {
+        if (typeof status !== 'string' || !VALID_STATUSES.has(status)) {
+            throw new SchemaError('http.param.invalid', { param: 'status' }, ctx.engine.locale);
+        }
+        filter.status = status;
+    }
+    if (typeof args.action === 'string')
+        filter.action = args.action;
+    if (typeof args.actorKey === 'string')
+        filter.actorKey = args.actorKey;
+    if (typeof args.limit === 'number')
+        filter.limit = args.limit;
+    if (typeof args.offset === 'number')
+        filter.offset = args.offset;
+    return filter;
+}
+export async function listApprovalsHandler(args, ctx) {
+    return callProtected(ctx, APPROVAL_TOOLS.LIST, undefined, args, async () => ctx.session.user, async () => {
+        const approvals = requireApprovals(ctx);
+        const filter = parseFilter(args, ctx);
+        const [rows, total] = await Promise.all([approvals.list(filter), approvals.count(filter)]);
+        return textResult(JSON.stringify({ rows, total }));
+    });
+}
+async function resolveApproval(args, ctx, decision) {
+    const tool = decision === 'approved' ? APPROVAL_TOOLS.APPROVE : APPROVAL_TOOLS.REJECT;
+    return callProtected(ctx, tool, undefined, args, async () => ctx.session.user, async (subject) => {
+        const approvals = requireApprovals(ctx);
+        const key = String(args.key ?? '');
+        const ok = decision === 'approved' ? await approvals.approve(key, subject.id) : await approvals.reject(key, subject.id);
+        if (!ok) {
+            throw new SchemaError('approval.notFound', { approvalKey: key }, ctx.engine.locale);
+        }
+        return textResult(JSON.stringify({ approvalKey: key, status: decision, approver: subject.id }));
+    });
+}
+export async function approveApprovalHandler(args, ctx) {
+    return resolveApproval(args, ctx, 'approved');
+}
+export async function rejectApprovalHandler(args, ctx) {
+    return resolveApproval(args, ctx, 'rejected');
+}
+//# sourceMappingURL=approvals.js.map

package/dist/adapters/mcp/approvals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approvals.js","sourceRoot":"","sources":["../../../src/adapters/mcp/approvals.ts"],"names":[],"mappings":"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"}

package/dist/adapters/mcp/generate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../src/adapters/mcp/generate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,eAAe,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAI3F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAUjE,OAAO,KAAK,EAAc,SAAS,EAAiB,WAAW,EAAmB,MAAM,YAAY,CAAC;AAErG;;;;;;;;;;GAUG;AAEH,yEAAyE;AACzE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,WAAW,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AA6MD;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,eAAe,EACxB,MAAM,CAAC,EAAE;IAAE,IAAI,EAAE,cAAc,EAAE,CAAC;IAAC,QAAQ,EAAE,YAAY,CAAA;CAAE,GAC1D,YAAY,EAAE,CAiChB"}
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../src/adapters/mcp/generate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,eAAe,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAI3F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAWjE,OAAO,KAAK,EAAc,SAAS,EAAiB,WAAW,EAAmB,MAAM,YAAY,CAAC;AAErG;;;;;;;;;;GAUG;AAEH,yEAAyE;AACzE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,WAAW,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AA6PD;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,eAAe,EACxB,MAAM,CAAC,EAAE;IAAE,IAAI,EAAE,cAAc,EAAE,CAAC;IAAC,QAAQ,EAAE,YAAY,CAAA;CAAE,GAC1D,YAAY,EAAE,CAmChB"}

package/dist/adapters/mcp/generate.js

@@ -1,6 +1,7 @@
-import { INTROSPECTION_TOOLS, REGISTRY_TOOLS, WORKFLOW_TOOLS, resolvePermissionFor } from '../../core/index.js';
+import { APPROVAL_TOOLS, INTROSPECTION_TOOLS, REGISTRY_TOOLS, WORKFLOW_TOOLS, resolvePermissionFor } from '../../core/index.js';
 import { ACTION_PREFIXES } from '../../core/audit/index.js';
 import { createRecordHandler, deleteRecordHandler, getRecordHandler, searchRecordsHandler, updateRecordHandler, workflowTransitionHandler, } from './tools.js';
+import { approveApprovalHandler, listApprovalsHandler, rejectApprovalHandler } from './approvals.js';
 import { describeObjectHandler, listObjectsHandler } from './introspection.js';
 /** capabilities the subject holds on at least one object (drives which generic ops appear) */
 function capabilities(registry, subject) {
@@ -153,6 +154,53 @@ function registryTools(engine, subject) {
     }
     return tools;
 }
+/** approval-queue tools: admin-only, present only when a queue is wired (the queue carries request args) */
+function approvalTools(engine, subject) {
+    if (engine.approvals === undefined)
+        return [];
+    const admin = new Set(engine.adminRoles ?? []);
+    if (!subject.roles.some((role) => admin.has(role)))
+        return [];
+    const KEY_ARG = { type: 'string', description: 'the approval key (see list_approvals)' };
+    return [
+        {
+            objectName: undefined,
+            spec: {
+                name: APPROVAL_TOOLS.LIST,
+                description: 'List the approval queue (paged; filtered to your admin scope)',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        status: { type: 'string', enum: ['pending', 'approved', 'rejected'] },
+                        action: { type: 'string', description: 'filter by the gated action (e.g. object.lead.update)' },
+                        actorKey: { type: 'string', description: 'filter by requester actor key' },
+                        limit: { type: 'integer', minimum: 1, maximum: 1000 },
+                        offset: { type: 'integer', minimum: 0 },
+                    },
+                },
+                handler: (args, ctx) => listApprovalsHandler(args, ctx),
+            },
+        },
+        {
+            objectName: undefined,
+            spec: {
+                name: APPROVAL_TOOLS.APPROVE,
+                description: 'Approve a pending approval (the original call may then be replayed)',
+                inputSchema: { type: 'object', properties: { key: KEY_ARG }, required: ['key'] },
+                handler: (args, ctx) => approveApprovalHandler(args, ctx),
+            },
+        },
+        {
+            objectName: undefined,
+            spec: {
+                name: APPROVAL_TOOLS.REJECT,
+                description: 'Reject a pending approval',
+                inputSchema: { type: 'object', properties: { key: KEY_ARG }, required: ['key'] },
+                handler: (args, ctx) => rejectApprovalHandler(args, ctx),
+            },
+        },
+    ];
+}
 /** custom-tool surface merged into the session tool surface (roles filtered by the executor, cached per subject) */
 function customToolTools(engine, subject, custom) {
     return custom.executor.surface(subject, custom.defs).map((entry) => {
@@ -221,6 +269,7 @@ export function compileToolsFor(engine, subject, custom) {
     if (custom !== undefined) {
         tools.push(...customToolTools(engine, subject, custom));
     }
+    tools.push(...approvalTools(engine, subject));
     return tools;
 }
 //# sourceMappingURL=generate.js.map