Draft policy-bound generated AI metadata read projections (#184)

CHANGELOG.md

@@ -14,6 +14,15 @@ This file is the authoritative user-facing release chronology. The former
 [release-notes ledger](docs/archive/2026/graphql-orm-release-notes.md) is retained
 for historical context.
 
+## 0.58.0 (unreleased) — Required policy bindings
+
+- Add an explicit entity policy-binding contract enforced by `schema_roots!`
+  before generated data operations, including count-only selections.
+- Require matching entity, row and field policy providers; preserve existing
+  callback decisions and reject absent or unrelated bindings.
+- Existing declarations remain unchanged unless the entity opts in. Public AI
+  projections require their AI binding by default.
+
 ## 0.57.0 (2026-10-22)
 
 Companion macros crate: `graphql-orm-macros` **0.57.0**.

Cargo.toml

@@ -40,7 +40,7 @@ cynic-parser = { version = "=0.11.2", features = ["pretty"] }
 futures = "0.3"
 getrandom = "0.3"
 graphql-composition = "=0.12.2"
-graphql-orm = { path = "crates/graphql-orm", version = "0.57.0", default-features = false }
+graphql-orm = { path = "crates/graphql-orm", version = "0.58.0", default-features = false }
 graphql-orm-ai-tool-profiles = { path = "crates/graphql-orm-ai-tool-profiles", version = "0.16.1" }
 graphql-orm-backup = { path = "crates/graphql-orm-backup", version = "0.10.0", default-features = false }
 graphql-orm-operation-catalog = { path = "crates/graphql-orm-operation-catalog", version = "0.4.1" }

MIGRATION.md

@@ -15,6 +15,19 @@ workspace release tag for every chosen workspace package and record its full
 commit from the release manifest. Neither the runtime nor macros crate is
 published to crates.io.
 
+## 0.57.0 to 0.58.0: required policy bindings
+
+Runtime/macros advance together. An entity can declare
+`#[graphql_orm(policy_binding = "owner.contract")]`. Its canonical `schema_roots!`
+builder requires entity, row and field providers whose `supports_policy_binding`
+methods acknowledge that contract; missing or unrelated providers reject all
+operations before reads, including metadata/count-only selections. Provider
+acknowledgement is a binding capability, never an authorization grant: each
+normal current-principal, scope, entity, row and field decision still runs.
+Configure all providers before building the schema. Entities without a binding
+retain their existing authorization mode. No data or physical schema migration
+is required.
+
 ## 0.56.0 to 0.57.0: exact SQL Server MONEY reads
 
 Upgrade `graphql-orm` and `graphql-orm-macros` together to 0.57.0 using one

crates/graphql-orm-ai/CHANGELOG.md

@@ -10,6 +10,12 @@ supersedes: []
 
 # Changelog
 
+Public metadata entities require the `ai.public.metadata` policy binding on all
+three providers. Compose them with `AiPublicEntityAccess::database()`: canonical
+schema builders reject absent or unrelated providers before reads, including
+count-only selections. Existing host binding capabilities remain delegated;
+acknowledging a binding never grants row or field access.
+
 All notable user-visible changes are recorded here. The crate follows
 Semantic Versioning and keeps migration instructions in [MIGRATION.md](MIGRATION.md).
 
@@ -18,6 +24,11 @@ checkpoint facts. For the current workspace baseline and active gates, use the
 [implementation status](docs/implementation-status.md) and the central
 [AI production-readiness plan](../../docs/plans/active/ai-production-readiness/README.md).
 
+## Unreleased - 0.110.0
+
+- Add a draft generated-read integration for safe session/message/run/attachment/tool-policy metadata. Public projection types map read-only to AI-owned tables; raw persistence and protected content remain private. `AiPublicEntityAccess` requires current-principal resolution, exact tenant/owner and host scope/session Read+List decisions, and preserves additional host entity/row/field restrictions. Metadata fields are non-exportable; projection writes, migrations and backup ownership are unavailable.
+- This does not complete issue #184: read-only generated notifications and child propagation remain unimplemented. Do not adopt this slice as entity-first alignment or replace protected-content/custody roots. No data or AI schema-module migration is required for the read projections.
+
 ## Unreleased - 0.109.1
 
 - Align with ORM/macros 0.56.0 and operation catalogue 0.4.1. A new test proves

crates/graphql-orm-ai/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "graphql-orm-ai"
-version = "0.109.1"
+version = "0.110.0"
 edition = "2024"
 authors = ["Toby Martin <toby@dastari.net>"]
 description = "Project-agnostic AI agent runtime for graphql-orm applications"

crates/graphql-orm-ai/MIGRATION.md

@@ -10,6 +10,12 @@ supersedes: []
 
 # Migration Guide
 
+Public metadata entities require the `ai.public.metadata` policy binding on all
+three providers. Compose them with `AiPublicEntityAccess::database()`: canonical
+schema builders reject absent or unrelated providers before reads, including
+count-only selections. Existing host binding capabilities remain delegated;
+acknowledging a binding never grants row or field access.
+
 `graphql-orm-ai` is Git-distributed and is not published to crates.io. This guide
 is mandatory so Git consumers and disposable test deployments can track schema
 and API changes without guessing.
@@ -19,6 +25,14 @@ they describe. For the current workspace baseline and active delivery gates,
 use [implementation status](docs/implementation-status.md) and the central
 [AI production-readiness plan](../../docs/plans/active/ai-production-readiness/README.md).
 
+## 0.109.1 to 0.110.0: generated metadata read projections (draft)
+
+Import `public_entities::*` for `schema_roots!` composition and build the public schema with `AiPublicEntityAccess::new(original_database, ai_access_policy, current_principal_resolver).database()`. Keep the original database and `AiSchemaModule` as the private persistence/schema/backup authority. Public projections declare `external_read_only`, never own those tables, and cannot perform generated writes. Missing policies/principal bindings fail closed under the default ORM authorization mode; deliberately permissive databases are outside this integration contract.
+
+Metadata reads require both scope and session Read+List authority, exact current principal owner identity and exact tenant equality; tool-policy metadata requires scope Read+List. Existing host callbacks are additional restrictions, so hosts that match entity names must admit these projection types explicitly. Relations reauthorize the target and selected fields. Every exposed metadata field is non-exportable. The surface never opens protected messages, exposes credential/storage/upload references or runs custody actions.
+
+This draft is a read slice only. Generated read-only notifications and message-to-session/run propagation are still required by issue #184; existing notification and protected-content roots remain recorded upstream/custody exceptions. No data, physical schema or AI_SCHEMA_MODULE_VERSION migration is needed because no persistent entity/semantic changes occur. Do not claim completed entity-first alignment or publish a complete #184 resolution from this slice.
+
 ## 0.109.0 to 0.109.1: ORM 0.56.0 alignment
 
 Adopt `graphql-orm-ai` 0.109.1 with ORM/macros 0.56.0 from one workspace

crates/graphql-orm-ai/README.md

@@ -10,6 +10,12 @@ supersedes: []
 
 # graphql-orm-ai
 
+Public metadata entities require the `ai.public.metadata` policy binding on all
+three providers. Compose them with `AiPublicEntityAccess::database()`: canonical
+schema builders reject absent or unrelated providers before reads, including
+count-only selections. Existing host binding capabilities remain delegated;
+acknowledging a binding never grants row or field access.
+
 The current workspace selects published Auth `v0.22.1` at
 `86fabec09eea1eec0f675bc150e90e3809734567` for the finite signed-catalogue
 correction. Direct Auth consumers must select the same tag and refresh their
@@ -196,6 +202,18 @@ turn's `with_capability_delivery` binding. Broker operations remain read-only;
 reviewed static bootstrap mutations retain current policy, one-shot approval
 where required, and ordinary resolver authorization.
 
+## Draft generated metadata reads
+
+`public_entities::*` provides read-only session/message/run/attachment/tool-policy
+metadata for `schema_roots!`. Bind `AiPublicEntityAccess` with the original database,
+AI policy and current-principal resolver before building the public schema. Raw
+persistence, protected content and custody remain private; every metadata field is
+non-exportable. Keep `AiSchemaModule` for owned schema/backup custody.
+
+This is the read slice of upstream #184. Generated read-only notifications and
+child propagation are incomplete; it is not a completed alignment or release gate.
+See the [migration contract](MIGRATION.md#01091-to-01100-generated-metadata-read-projections-draft).
+
 ## Install
 
 This active pre-release is Git-only. Pin one reviewed full monorepo revision

crates/graphql-orm-ai/src/lib.rs

@@ -22,6 +22,12 @@ compile_error!(
 
 mod access;
 #[cfg(any(feature = "sqlite", feature = "postgres"))]
+pub mod public_entities;
+#[cfg(any(feature = "sqlite", feature = "postgres"))]
+mod public_entity_access;
+#[cfg(any(feature = "sqlite", feature = "postgres"))]
+pub use public_entity_access::AiPublicEntityAccess;
+#[cfg(any(feature = "sqlite", feature = "postgres"))]
 mod agent_loop;
 mod approvals;
 mod attachments;