@weave-kit/engine 0.10.0 → 1.0.0

package/CHANGELOG.md

@@ -1,165 +1,240 @@
-# Changelog
-
-All notable changes to `@weave-kit/engine`. Format follows [Keep a Changelog](https://keepachangelog.com/);
-the project uses [Semantic Versioning](https://semver.org/).
-
-## [0.10.0]
-
-### Added
-
-- **QueryBudget.** `EngineConfig.queryBudget` bounds a read/query across the engine:
-  rows / filters / sorts in data-access (all list paths), joins / SQL length / statement timeout in
-  restricted SQL (`this.db.query`), and GraphQL depth. Exported `QueryBudget` / `QUERY_BUDGET_DEFAULTS`
-  / `resolveQueryBudget` / `assertQueryBudget` (`runtime/data-access/query-budget.ts`); a per-context
-  `DataAccessContext.budget` overrides the instance default. Additive — default limits only.
-
-## [0.9.0]
-
-A **breaking** consistency/authorization release. Read the **Breaking** section before upgrading.
-
-### Breaking
-
-- **`DataAccessContext.principal` is now required; the implicit `subject` field is removed.** The old
-  convention — omit `subject` and get unrestricted access — is gone, so a forgotten actor is now a
-  **compile error** instead of a silent RBAC bypass. Migrate:
-  - a user call → `principal: userPrincipal(subject)` (or a literal `{ kind: 'user', subject }`);
-  - an internal/seed/system call → `principal: systemPrincipal(SYSTEM_CAPABILITIES.INTERNAL_ADMIN)`
-    (or `{ kind: 'system', capability: 'internal.admin' }`).
-  `AccessPrincipal`, `userPrincipal`, `systemPrincipal` and `SYSTEM_CAPABILITIES` are exported from
-  the package root. `withRbac` passes through only for an explicit **system** principal.
-
-### Added
-
-- **Global schema revisions + atomic deploys.** New `weavekit_schema_revision` (append-only, anchored
-  on a deterministic aggregate `computeSchemaHash(files)`). `weave migrate` / `weave deploy apply` now
-  commit the DDL, the metadata cache and the schema revision in **one transaction** (serialized by an
-  advisory lock) — a failure rolls the whole deploy back. New CLI: `weave deploy plan` (read-only
-  preview + risk) and `weave deploy apply`.
-- **Audit durability modes.** `subsystems.audit.mode`: `best-effort` (default, unchanged),
-  `transactional` (audit row written in the business transaction) and `durable` (transactional outbox
-  `weavekit_audit_outbox` + a crash-safe, at-least-once relay). New `AuditSink.recordInTx(event,
-  client)` seam; audit events gain `requestId` / `traceId` (new indexed columns).
-- **Cursor pagination.** `FindOptions.cursor` + `FindResult.nextCursor` / `hasMore` (opaque keyset on
-  the single primary key). MCP `search_records` accepts `cursor` and returns `hasMore`/`nextCursor`;
-  offset remains supported.
-- **Access principal types** (`core/types/principal.ts`): `AccessPrincipal`, `SYSTEM_CAPABILITIES`,
-  `userPrincipal`, `systemPrincipal`, `principalSubject`, `principalActorId`.
-
-### Changed
-
-- **MCP compiled-surface cache** key now includes a schema signature (registry-derived) and the
-  custom-tool set, and the cache is bounded — a schema/tool change no longer serves stale tools.
-- **Workflow privileged operations** (`releaseWorkflowLock` / `workflowTodos` / `overrideWorkflow`)
-  are now guarded in the RBAC decorator (fail-closed read/update checks) instead of passing through.
-
-### Fixed
-
-- **Implicit-unrestricted holes** in the custom-tool base context and the transition guardrail
-  context: both now carry a user principal, so a tool/policy cannot read unrestricted by omission.
-
-## [0.8.0]
-
-### Added
-
-- **GraphQL adapter (opt-in).** `adapters.graphql` compiles the same `schema.json` into a read/write
-  GraphQL endpoint (`/graphql`, POST + GET) that reuses the engine's RBAC / RLS / audit unchanged:
-  queries (`<object>` pages + `<object>_by_id`, with nested relations batched per request),
-  mutations (`create`/`update`/`delete` plus workflow `transition`), query hardening
-  (depth / complexity / alias limits), an operation allow list, and an introspection toggle.
-  Its only runtime dependency is `graphql@16` — the engine speaks GraphQL-over-HTTP itself
-  (`graphql-http` is not required). New CLI: `weave graphql:schema` emits the SDL offline. **Off by
-  default** (`adapters.graphql.enabled`).
-- **Named enums (schema v6).** Declare an enum once in `enums/<name>.json` and reference it from any
-  field with `{ "type": "enum", "enumType": "<name>" }`. Values validate centrally, generate named
-  TypeScript unions (`weave types`), surface as shared OpenAPI `components.schemas` (with
-  `x-enumLabels`), and are listed with `weave enum:list` / `weave enum:check`; `weave field:add
-  --enum` wires a new field to an existing enum. The on-disk format is bumped to **v6**
-  (`SCHEMA_FORMAT_VERSION`); existing v5 files migrate on read (additive — run `weave schema:upgrade`
-  to stamp them).
-
-### Changed
-
-- **Uncategorized `SchemaError`s now map to HTTP 400** instead of falling through to 500. The error
-  space is dominated by request conditions (bad params/fields, RBAC, not-found); genuine server
-  faults keep 500 via an explicit set (`http.internal`, `data.schemaDrift`, and script runtime
-  failures `script.timeout` / `script.busy` / `script.compile` / `script.sandbox.unavailable`).
-
-### Fixed
-
-- **MCP session ↔ agent binding.** A follow-up request on an existing session now re-verifies that
-  the presented Bearer key is the one that established the session (compared by a non-secret SHA-256
-  fingerprint); a different key reusing a session id is rejected with `mcp.session.agentMismatch`.
-  The raw API key is no longer stored on the session or written to the audit log — audit `actorId`
-  is the credential fingerprint and the agent principal id stays in `meta`.
-
-## [0.7.0]
-
-### Added
-
-- **Node 22 support.** The engine, CLI and scaffolded projects now run on Node **22+** (verified on
-  Node 22 and Node 24). `engines.node` is `>=22`; generated projects declare the same.
-
-### Changed
-
-- `isolated-vm` — the optional native dependency behind the script sandbox — is pinned to
-  **`^6.2.0`**, which ships prebuilt binaries for both Node 22 and Node 24 (7.x drops Node 22).
-  Behavior is unchanged (the sandbox, RPC bridge and timeout/`__done` handling are covered by the
-  same tests on both runtimes). Note: prebuilds are no longer published for Node 26 — on that
-  runtime the script sandbox may fall back to a source build.
-
-## [0.6.0]
-
-A breaking release. The data model, access control and workflow were reworked end to end. Read the
-**Breaking** section before upgrading.
-
-### Breaking
-
-- **Record ids are the `record_key`.** A record's external id is now a single URL-safe string that
-  encodes the (possibly composite) primary key, surfaced as the read-only `weave_id` field. REST
-  `/{id}`, MCP `id` and batch `ids[]` all take this string — read it from a result or `describe_object`
-  instead of composing the raw primary key.
-- **Field types are bucketed** into PG-native value types and engine-shipped custom types. `person`
-  was renamed to `user`; `SCALAR` was removed; `currency` accepts an optional ISO 4217 code (and an
-  optional `precision`); `json` now maps to PostgreSQL `json` — use `jsonb` for the old behavior. Run
-  `weave schema:upgrade`.
-- **Row scopes add `department`** (`own | department | all`) plus a separate `manage` scope for writes,
-  and a scope column's ids can be `internal` (engine ids) or `external` (customer ids).
-- **Identity directory** — the engine now owns `weavekit_user` / `weavekit_department`; sync an external
-  source with `weave sync:identity`, authenticate through a verifier, and manage users over the admin
-  REST surface.
-- **`multiRelation` uses a link table** (real FK per side, `ON DELETE CASCADE`) instead of a column;
-  reads and filters are scoped to the targets the subject can read.
-- **Workflow rewritten to a single-line node chain** (`workflow.json` format v2). v1 state-machine
-  files are linearized on read. Instance/step/workitem state lives in engine tables
-  (`weavekit_workflow_instances` / `_steps` / `_workitems`, plus locks/definitions/timers). New
-  REST + MCP surface; `weave workflow:migrate` was **removed**; the side-table column
-  `workflow_id` was renamed to `workflow_instance_id`; `weave migrate` drops and recreates the timer
-  table.
-- **Engine-owned system tables + runtime zero-DDL.** All DDL is emitted by `weave migrate`; the runtime
-  never alters or drops customer columns (reads only).
-- **Security hardening** — formula references respect RBAC, `details` children inherit (and can only
-  narrow) their parent's permissions, DDL literals are escaped, and script SQL is gated by an AST pass.
-
-### Added
-
-- Record-metadata side tables with `weave_*` virtual fields (`weave_id`, `weave_status`,
-  `weave_owner_id`, `weave_created_by`/`_modified_by`, `weave_created_time`/`_modified_time`,
-  `weave_workflow_instance_id`) — request them in `fields`, and they work in `filter` / `sort`.
-- Field types: native PG enums for static `enum`s, data-driven `enum` options, `seq_no`, `uuid`,
-  `smallint`/`bigint`/`real`/`double`/`char`, numeric `precision`/`scale`, `json`/`jsonb`.
-- Reverse-modeling: `weave introspect` handles composite primary keys and native enum/array columns;
-  `weave schema:map` reports schema↔column drift.
-- Workflow actions `submit` / `approve` / `reject` / `forward` / `withdraw` / `cancel` / `reactivate`,
-  any-one / all approvals, node timeouts, an admin override, and definition write-back.
-- `describe_object` exposes a field's resolved type `base`.
-
-### Changed
-
-- `weave migrate` registers content-addressed workflow definitions; instances pin the hash they started
-  under, so editing `workflow.json` only affects new records.
-- Live `record.transitioned` events carry `from` / `to` / `action`.
-
-### Fixed
-
-- Correct row-scope parameter offset on `update` / `delete` / `transition`.
-- `record_key` encoding is single-sourced in SQL (contract-tested).
+# Changelog
+
+All notable changes to `@weave-kit/engine`. Format follows [Keep a Changelog](https://keepachangelog.com/);
+the project uses [Semantic Versioning](https://semver.org/).
+
+## [1.0.0]
+
+The **G1 contract-freeze** release: the public surface (schema/workflow formats, REST routes, MCP tool
+names, event types, error codes, data-access/RBAC contracts, package exports) is now frozen under
+`CONTRACT_VERSION` (`1`) and evolves **additively** from here. It also lands multi-tenancy, the
+observability seam and operational tooling.
+
+### Added
+
+- **Multi-tenancy (row).** `EngineConfig.tenants = { enabled?, defaultTenant? }`; an object field
+  marked `"tenant": true` scopes every read/write to the subject's tenant — RBAC row scope (even for
+  `read: "all"`) + native RLS (`weavekit.tenant_id` GUC) + audit (`tenant_id`). The tenant is forced
+  on create and immutable on update (`object.tenant.immutable`); `withDefaultTenant` stamps a subject
+  that lacks one. Absent tenant = single-tenant (unchanged). Exported `principalTenantId`, `tenantOf`,
+  `scopedQuotaKey`, `ROW_SCOPE_MARKERS.TENANT`.
+- **Contract freeze (G1).** `CONTRACT_VERSION` (exported from the package root; mirrored in
+  `GET /version` and the OpenAPI `info.x-contract-version`) plus a freeze gate test and the
+  contract-freeze / deprecation policy.
+- **Observability seam.** `MetricsSink` / `TraceSink` + single-source `METRIC_NAMES`
+  (`core/observability`), injected via `EngineConfig.observability`; the engine emits request
+  latency/status, `rbac.deny` and `query.budget.reject`, and records spans. `core/trace.ts`
+  (`parseTraceparent`) parses the inbound W3C `traceparent`; the `traceId` threads through
+  audit / evidence / events. No-op default; no telemetry backend bundled.
+- **`weave doctor` preflight** — read-only (connection, PostgreSQL compatibility, schema↔DB drift,
+  engine system tables, RLS role + sandbox), `--json` supported; `weave migrate --preflight` runs it
+  first and aborts on any failure.
+- **`weave deploy plan` schema-impact analysis** (`analyzeImpact` / `SchemaImpact`): creates, column
+  adds, constraints, indexes, enum + RLS changes, a data-compat risk and an API-breaking flag, plus
+  the live schema revision and a **config-drift** flag.
+- **Audit + evidence keyset cursor.** `AuditQuery.cursor` / `AuditQueryResult.nextCursor` and
+  `EvidenceQuery` / `EvidenceQueryResult` + `queryEvidence` (stable `(ts DESC, id DESC)` paging;
+  offset still supported).
+- **Enterprise seams** documented and annotated (`@enterprise-reserved`): `AuditSink`,
+  `ApprovalsBackend`, `WorkflowTimerStore` / `WorkflowBackend`, `IdentityStore`,
+  `AuthSource` / `AuthVerifier`, `GuardrailPolicy`, `ProxyTargetResolver`, `MetricsSink` / `TraceSink`.
+
+### Changed
+
+- **GraphQL query cost is weighted by the list `limit`** (was a raw field count), matching the
+  documented behavior.
+- Query-budget filter counting is robust against malformed `$or` groups.
+
+### Fixed
+
+- **System-principal audit `actorId` is `'system'`** again (matches the documented contract; the
+  specific capability is kept on the event's `meta.capability`).
+- **Tenant write isolation**: `create` forces the tenant column to the subject's tenant, and `update`
+  rejects moving a row to another tenant (`object.tenant.immutable`).
+- MCP argument-validation denials are audited under `tool.args.invalid` (not `mcp.tool.notFound`).
+
+### Removed
+
+- `EngineAuditConfig.retention` — the no-op placeholder is gone (retention / export / compliance are
+  the enterprise E2 layer).
+
+## [0.11.0]
+
+### Added
+
+- **Agent Execution pipeline + Evidence.** A protocol-agnostic orchestrator (`runPipeline`,
+  `EXECUTION_STAGES` / `ExecutionPlan` / `Evidence` / `EvidenceSink`) runs one execution through
+  Plan → Validate → Authorize → Guardrail → Approval → Execute → Commit → Evidence. The custom-tool
+  executor and the data-access write path (`create`/`update`/`delete`, action
+  `object.<object>.<op>`) now share the same guardrail/approval gate, so REST / MCP generic CRUD /
+  GraphQL / script writes are all covered (previously only custom tools and workflow transitions
+  were). Tool arguments are validated against the declared `ToolJsonSchema` (`tool.args.invalid`).
+  Enable `evidence.enabled` to record one `weavekit_evidence` row per gated execution
+  (request/trace/schema-revision correlated). Additive — with no guardrail policies configured and
+  evidence disabled, behavior and queries are unchanged.
+
+### Fixed
+
+- Guardrail/approval is no longer bypassed by MCP generic CRUD and REST writes (new action
+  `object.<object>.<op>`).
+
+## [0.10.0]
+
+### Added
+
+- **QueryBudget.** `EngineConfig.queryBudget` bounds a read/query across the engine:
+  rows / filters / sorts in data-access (all list paths), joins / SQL length / statement timeout in
+  restricted SQL (`this.db.query`), and GraphQL depth. Exported `QueryBudget` / `QUERY_BUDGET_DEFAULTS`
+  / `resolveQueryBudget` / `assertQueryBudget` (`runtime/data-access/query-budget.ts`); a per-context
+  `DataAccessContext.budget` overrides the instance default. Additive — default limits only.
+
+## [0.9.0]
+
+A **breaking** consistency/authorization release. Read the **Breaking** section before upgrading.
+
+### Breaking
+
+- **`DataAccessContext.principal` is now required; the implicit `subject` field is removed.** The old
+  convention — omit `subject` and get unrestricted access — is gone, so a forgotten actor is now a
+  **compile error** instead of a silent RBAC bypass. Migrate:
+  - a user call → `principal: userPrincipal(subject)` (or a literal `{ kind: 'user', subject }`);
+  - an internal/seed/system call → `principal: systemPrincipal(SYSTEM_CAPABILITIES.INTERNAL_ADMIN)`
+    (or `{ kind: 'system', capability: 'internal.admin' }`).
+  `AccessPrincipal`, `userPrincipal`, `systemPrincipal` and `SYSTEM_CAPABILITIES` are exported from
+  the package root. `withRbac` passes through only for an explicit **system** principal.
+
+### Added
+
+- **Global schema revisions + atomic deploys.** New `weavekit_schema_revision` (append-only, anchored
+  on a deterministic aggregate `computeSchemaHash(files)`). `weave migrate` / `weave deploy apply` now
+  commit the DDL, the metadata cache and the schema revision in **one transaction** (serialized by an
+  advisory lock) — a failure rolls the whole deploy back. New CLI: `weave deploy plan` (read-only
+  preview + risk) and `weave deploy apply`.
+- **Audit durability modes.** `subsystems.audit.mode`: `best-effort` (default, unchanged),
+  `transactional` (audit row written in the business transaction) and `durable` (transactional outbox
+  `weavekit_audit_outbox` + a crash-safe, at-least-once relay). New `AuditSink.recordInTx(event,
+  client)` seam; audit events gain `requestId` / `traceId` (new indexed columns).
+- **Cursor pagination.** `FindOptions.cursor` + `FindResult.nextCursor` / `hasMore` (opaque keyset on
+  the single primary key). MCP `search_records` accepts `cursor` and returns `hasMore`/`nextCursor`;
+  offset remains supported.
+- **Access principal types** (`core/types/principal.ts`): `AccessPrincipal`, `SYSTEM_CAPABILITIES`,
+  `userPrincipal`, `systemPrincipal`, `principalSubject`, `principalActorId`.
+
+### Changed
+
+- **MCP compiled-surface cache** key now includes a schema signature (registry-derived) and the
+  custom-tool set, and the cache is bounded — a schema/tool change no longer serves stale tools.
+- **Workflow privileged operations** (`releaseWorkflowLock` / `workflowTodos` / `overrideWorkflow`)
+  are now guarded in the RBAC decorator (fail-closed read/update checks) instead of passing through.
+
+### Fixed
+
+- **Implicit-unrestricted holes** in the custom-tool base context and the transition guardrail
+  context: both now carry a user principal, so a tool/policy cannot read unrestricted by omission.
+
+## [0.8.0]
+
+### Added
+
+- **GraphQL adapter (opt-in).** `adapters.graphql` compiles the same `schema.json` into a read/write
+  GraphQL endpoint (`/graphql`, POST + GET) that reuses the engine's RBAC / RLS / audit unchanged:
+  queries (`<object>` pages + `<object>_by_id`, with nested relations batched per request),
+  mutations (`create`/`update`/`delete` plus workflow `transition`), query hardening
+  (depth / complexity / alias limits), an operation allow list, and an introspection toggle.
+  Its only runtime dependency is `graphql@16` — the engine speaks GraphQL-over-HTTP itself
+  (`graphql-http` is not required). New CLI: `weave graphql:schema` emits the SDL offline. **Off by
+  default** (`adapters.graphql.enabled`).
+- **Named enums (schema v6).** Declare an enum once in `enums/<name>.json` and reference it from any
+  field with `{ "type": "enum", "enumType": "<name>" }`. Values validate centrally, generate named
+  TypeScript unions (`weave types`), surface as shared OpenAPI `components.schemas` (with
+  `x-enumLabels`), and are listed with `weave enum:list` / `weave enum:check`; `weave field:add
+  --enum` wires a new field to an existing enum. The on-disk format is bumped to **v6**
+  (`SCHEMA_FORMAT_VERSION`); existing v5 files migrate on read (additive — run `weave schema:upgrade`
+  to stamp them).
+
+### Changed
+
+- **Uncategorized `SchemaError`s now map to HTTP 400** instead of falling through to 500. The error
+  space is dominated by request conditions (bad params/fields, RBAC, not-found); genuine server
+  faults keep 500 via an explicit set (`http.internal`, `data.schemaDrift`, and script runtime
+  failures `script.timeout` / `script.busy` / `script.compile` / `script.sandbox.unavailable`).
+
+### Fixed
+
+- **MCP session ↔ agent binding.** A follow-up request on an existing session now re-verifies that
+  the presented Bearer key is the one that established the session (compared by a non-secret SHA-256
+  fingerprint); a different key reusing a session id is rejected with `mcp.session.agentMismatch`.
+  The raw API key is no longer stored on the session or written to the audit log — audit `actorId`
+  is the credential fingerprint and the agent principal id stays in `meta`.
+
+## [0.7.0]
+
+### Added
+
+- **Node 22 support.** The engine, CLI and scaffolded projects now run on Node **22+** (verified on
+  Node 22 and Node 24). `engines.node` is `>=22`; generated projects declare the same.
+
+### Changed
+
+- `isolated-vm` — the optional native dependency behind the script sandbox — is pinned to
+  **`^6.2.0`**, which ships prebuilt binaries for both Node 22 and Node 24 (7.x drops Node 22).
+  Behavior is unchanged (the sandbox, RPC bridge and timeout/`__done` handling are covered by the
+  same tests on both runtimes). Note: prebuilds are no longer published for Node 26 — on that
+  runtime the script sandbox may fall back to a source build.
+
+## [0.6.0]
+
+A breaking release. The data model, access control and workflow were reworked end to end. Read the
+**Breaking** section before upgrading.
+
+### Breaking
+
+- **Record ids are the `record_key`.** A record's external id is now a single URL-safe string that
+  encodes the (possibly composite) primary key, surfaced as the read-only `weave_id` field. REST
+  `/{id}`, MCP `id` and batch `ids[]` all take this string — read it from a result or `describe_object`
+  instead of composing the raw primary key.
+- **Field types are bucketed** into PG-native value types and engine-shipped custom types. `person`
+  was renamed to `user`; `SCALAR` was removed; `currency` accepts an optional ISO 4217 code (and an
+  optional `precision`); `json` now maps to PostgreSQL `json` — use `jsonb` for the old behavior. Run
+  `weave schema:upgrade`.
+- **Row scopes add `department`** (`own | department | all`) plus a separate `manage` scope for writes,
+  and a scope column's ids can be `internal` (engine ids) or `external` (customer ids).
+- **Identity directory** — the engine now owns `weavekit_user` / `weavekit_department`; sync an external
+  source with `weave sync:identity`, authenticate through a verifier, and manage users over the admin
+  REST surface.
+- **`multiRelation` uses a link table** (real FK per side, `ON DELETE CASCADE`) instead of a column;
+  reads and filters are scoped to the targets the subject can read.
+- **Workflow rewritten to a single-line node chain** (`workflow.json` format v2). v1 state-machine
+  files are linearized on read. Instance/step/workitem state lives in engine tables
+  (`weavekit_workflow_instances` / `_steps` / `_workitems`, plus locks/definitions/timers). New
+  REST + MCP surface; `weave workflow:migrate` was **removed**; the side-table column
+  `workflow_id` was renamed to `workflow_instance_id`; `weave migrate` drops and recreates the timer
+  table.
+- **Engine-owned system tables + runtime zero-DDL.** All DDL is emitted by `weave migrate`; the runtime
+  never alters or drops customer columns (reads only).
+- **Security hardening** — formula references respect RBAC, `details` children inherit (and can only
+  narrow) their parent's permissions, DDL literals are escaped, and script SQL is gated by an AST pass.
+
+### Added
+
+- Record-metadata side tables with `weave_*` virtual fields (`weave_id`, `weave_status`,
+  `weave_owner_id`, `weave_created_by`/`_modified_by`, `weave_created_time`/`_modified_time`,
+  `weave_workflow_instance_id`) — request them in `fields`, and they work in `filter` / `sort`.
+- Field types: native PG enums for static `enum`s, data-driven `enum` options, `seq_no`, `uuid`,
+  `smallint`/`bigint`/`real`/`double`/`char`, numeric `precision`/`scale`, `json`/`jsonb`.
+- Reverse-modeling: `weave introspect` handles composite primary keys and native enum/array columns;
+  `weave schema:map` reports schema↔column drift.
+- Workflow actions `submit` / `approve` / `reject` / `forward` / `withdraw` / `cancel` / `reactivate`,
+  any-one / all approvals, node timeouts, an admin override, and definition write-back.
+- `describe_object` exposes a field's resolved type `base`.
+
+### Changed
+
+- `weave migrate` registers content-addressed workflow definitions; instances pin the hash they started
+  under, so editing `workflow.json` only affects new records.
+- Live `record.transitioned` events carry `from` / `to` / `action`.
+
+### Fixed
+
+- Correct row-scope parameter offset on `update` / `delete` / `transition`.
+- `record_key` encoding is single-sourced in SQL (contract-tested).

package/README.md

@@ -1,15 +1,16 @@
 <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, a
-REST API with row- and field-level RBAC, an immutable audit log, and an MCP tool surface that AI
-agents call with typed tools — never raw SQL. Self-hosted: your data stays in your database.
+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 API (CRUD + RBAC)
-                                MCP tools (per-identity surface + guardrails)
-                                Immutable audit log
+                                REST + GraphQL APIs (CRUD + RBAC)
+                                MCP tools (per-identity surface + guardrails + approvals)
+                                Immutable audit log + execution evidence
                                 TypeScript types
 ```
 
@@ -29,8 +30,8 @@ objects/leads/schema.json   →   Git commit (source of truth)
 - **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 a REST API and generated TypeScript types, so
-  people and agents share one governed contract.
+- **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
@@ -52,23 +53,38 @@ write.
   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`/`team`) and field-level RBAC and a
-  uniform error contract.
+- **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.
-- **Audit log** — an immutable event log for data mutations.
+- **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** — health / readiness / version endpoints, request rate limiting, CORS and
-  structured logging.
+- **Operations** — `weave doctor` preflight, health / readiness / version endpoints, request rate
+  limiting, CORS and structured logging.
 
 ## Requirements
 
 - Node.js 22+
-- PostgreSQL
+- PostgreSQL 12+ (the engine's tested floor; `weave doctor` reports the version)
 
 ## Quick start
 
@@ -100,11 +116,11 @@ 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) · [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) · [MCP](https://docs.weavekit.io/engine/guides/agents/mcp) · [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) · [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)
-- [Practices & operations](https://docs.weavekit.io/engine/practices/agent/existing-crm-to-mcp) — real integration and deployment walkthroughs
+- [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).
 
@@ -135,6 +151,8 @@ await engine.app.listen({ port: 3000 });
 | 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 |
@@ -152,7 +170,7 @@ await engine.app.listen({ port: 3000 });
 | `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) |
+| `weave module:add` / `module:remove <name>` | Enable/disable an optional subsystem (audit/script/workflow) |
 
 ## Object-level types
 
@@ -174,8 +192,10 @@ const { rows } = await leads.find({ filter: { status: 'open' } });
 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

package/dist/adapters/auth/index.d.ts

@@ -4,7 +4,7 @@ import { type AuthConfig, type Authenticator } from './source.js';
 export type { Authenticator, AuthConfig, AuthResolver, AuthSource } from './source.js';
 export { createAuth } from './source.js';
 export type { AuthVerifier } from './verify.js';
-export { createDirectoryAuthenticator, enforceSyncedIdentity } from './subject.js';
+export { createDirectoryAuthenticator, enforceSyncedIdentity, withDefaultTenant } from './subject.js';
 /**
  * Resolve the Authorization header into a subject, or throw a 401-family
  * {@link SchemaError}. Missing header → `auth.missingKey`; present but

package/dist/adapters/auth/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/auth/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAElD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAc,KAAK,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAE9E,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACvF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,4BAA4B,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAEnF;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,aAAa,EAAE,aAAa,EAC5B,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,eAAe,CAAC,CAK1B;AAED,0FAA0F;AAC1F,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,UAAU,GAAG,aAAa,CAEpE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/auth/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAElD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAc,KAAK,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAE9E,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACvF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,4BAA4B,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtG;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,aAAa,EAAE,aAAa,EAC5B,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,eAAe,CAAC,CAK1B;AAED,0FAA0F;AAC1F,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,UAAU,GAAG,aAAa,CAEpE"}

package/dist/adapters/auth/index.js

@@ -1,7 +1,7 @@
 import { SchemaError } from '../../core/index.js';
 import { createAuth } from './source.js';
 export { createAuth } from './source.js';
-export { createDirectoryAuthenticator, enforceSyncedIdentity } from './subject.js';
+export { createDirectoryAuthenticator, enforceSyncedIdentity, withDefaultTenant } from './subject.js';
 /**
  * Resolve the Authorization header into a subject, or throw a 401-family
  * {@link SchemaError}. Missing header → `auth.missingKey`; present but

package/dist/adapters/auth/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/adapters/auth/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAElD,OAAO,EAAE,UAAU,EAAuC,MAAM,aAAa,CAAC;AAG9E,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,4BAA4B,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAEnF;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,aAA4B,EAC5B,MAA0B,EAC1B,MAAc;IAEd,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACpD,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,OAAO,CAAC;IACrC,IAAI,MAAM,KAAK,SAAS;QAAE,MAAM,IAAI,WAAW,CAAC,iBAAiB,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC;IAC/E,MAAM,IAAI,WAAW,CAAC,iBAAiB,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC;AACvD,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,kBAAkB,CAAC,MAAkB;IACnD,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC;AAC5B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/adapters/auth/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAElD,OAAO,EAAE,UAAU,EAAuC,MAAM,aAAa,CAAC;AAG9E,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,4BAA4B,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtG;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,aAA4B,EAC5B,MAA0B,EAC1B,MAAc;IAEd,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACpD,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,OAAO,CAAC;IACrC,IAAI,MAAM,KAAK,SAAS;QAAE,MAAM,IAAI,WAAW,CAAC,iBAAiB,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC;IAC/E,MAAM,IAAI,WAAW,CAAC,iBAAiB,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC;AACvD,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,kBAAkB,CAAC,MAAkB;IACnD,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC;AAC5B,CAAC"}

package/dist/adapters/auth/source.d.ts

@@ -13,6 +13,9 @@ export type AuthResolver = (header: string | undefined) => IdentitySubject | nul
 /**
  * The authentication source: either a static key map or a resolver function.
  * `source` is required whenever `auth` is configured (fail fast otherwise).
+ *
+ * Stable seam (`@enterprise-reserved`): SSO/OIDC/SAML is enterprise E1; the
+ * engine ships static-key and custom-resolver sources.
  */
 export type AuthSource = Record<string, IdentitySubject> | AuthResolver;
 /** authentication config — the single source of truth is `source` */

package/dist/adapters/auth/source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../../src/adapters/auth/source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,+FAA+F;AAC/F,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,eAAe,GAAG,IAAI,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;CAC/F;AAED;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,KAAK,eAAe,GAAG,IAAI,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;AAEpH;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,YAAY,CAAC;AAExE,qEAAqE;AACrE,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,UAAU,CAAC;CACpB;AAED,gFAAgF;AAChF,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,aAAa,CAiB5D"}
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../../src/adapters/auth/source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,+FAA+F;AAC/F,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,eAAe,GAAG,IAAI,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;CAC/F;AAED;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,KAAK,eAAe,GAAG,IAAI,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;AAEpH;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,YAAY,CAAC;AAExE,qEAAqE;AACrE,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,UAAU,CAAC;CACpB;AAED,gFAAgF;AAChF,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,aAAa,CAiB5D"}