diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d309582..d7c1638 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -15,16 +15,6 @@ jobs: with: path: graphql-orm-ai fetch-depth: 0 - - uses: actions/checkout@v5 - with: - repository: Dastari/graphql-orm - ref: 1e145a124e9e3f1b0ffd70165289170b627ecb73 - path: graphql-orm - - uses: actions/checkout@v5 - with: - repository: Dastari/agql-auth - ref: c92dcb441237bbe308499b26525945f60ffa394a - path: agql-auth - uses: dtolnay/rust-toolchain@stable with: components: rustfmt, clippy @@ -49,16 +39,6 @@ jobs: with: path: graphql-orm-ai fetch-depth: 0 - - uses: actions/checkout@v5 - with: - repository: Dastari/graphql-orm - ref: 1e145a124e9e3f1b0ffd70165289170b627ecb73 - path: graphql-orm - - uses: actions/checkout@v5 - with: - repository: Dastari/agql-auth - ref: c92dcb441237bbe308499b26525945f60ffa394a - path: agql-auth - uses: dtolnay/rust-toolchain@stable - uses: Swatinem/rust-cache@v2 - name: Run ORM parity against a test-owned disposable PostgreSQL container @@ -85,24 +65,8 @@ jobs: with: path: graphql-orm-ai fetch-depth: 0 - - uses: actions/checkout@v5 - with: - repository: Dastari/graphql-orm - ref: 1e145a124e9e3f1b0ffd70165289170b627ecb73 - path: graphql-orm - - uses: actions/checkout@v5 - with: - repository: Dastari/agql-auth - ref: c92dcb441237bbe308499b26525945f60ffa394a - path: agql-auth - name: Create baseline worktree run: git -C graphql-orm-ai worktree add ../graphql-orm-ai-baseline "${{ github.event.pull_request.base.sha }}" - - name: Reconstruct unpublished baseline dependency universe - run: | - sed -i 's/version = "0.8.0"/version = "0.10.0"/' graphql-orm-ai-baseline/Cargo.toml - sed -i 's/version = "0.6.1"/version = "0.7.0"/' graphql-orm-ai-baseline/Cargo.toml - grep -F 'agql-auth = { path = "../agql-auth", version = "0.10.0" }' graphql-orm-ai-baseline/Cargo.toml - grep -F 'graphql-orm = { path = "../graphql-orm/crates/graphql-orm", version = "0.7.0", default-features = false }' graphql-orm-ai-baseline/Cargo.toml - uses: obi1kenobi/cargo-semver-checks-action@v2 with: manifest-path: graphql-orm-ai/Cargo.toml diff --git a/AGENTS.md b/AGENTS.md index 17b178b..03bb541 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,6 +24,12 @@ These rules apply to every human or automated change in this repository. otherwise mutate their worktrees or GitHub branches. - Read-only inspection of sibling source, tags, PRs, and dependency metadata is allowed when needed to define an integration requirement. +- Never implement an upstream change from this repository, regardless of its + size or urgency. Every required change to `graphql-orm`, `agql-auth`, or any + other upstream crate must be expressed as a copy-ready prompt in `.handoffs/` + and assigned to a separate owning agent. Until that owner returns a reviewed + final merge or release SHA, this repository remains read-only and blocked on + that upstream requirement. - When a reusable upstream change is required, stage a copy-ready prompt in `.handoffs/` for the owning repository agent. That directory is deliberately ignored so temporary coordination state is not published with the crate. diff --git a/CHANGELOG.md b/CHANGELOG.md index 8f0cf41..2e26f5a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,9 +5,10 @@ Semantic Versioning and keeps migration instructions in [MIGRATION.md](MIGRATION ## [Unreleased] -This development line advances the pre-1.0 crate version to `0.50.0` and AI -schema module to `0.47.0`. It adds a fortieth private entity for exact, -content-free OpenAI background-submission bindings. +This development line advances the pre-1.0 crate version to `0.51.0` while the +AI schema module remains `0.47.0`. It aligns the reviewed dependency universe +after adding a fortieth private entity for exact, content-free OpenAI +background-submission bindings. ### Added @@ -156,6 +157,25 @@ content-free OpenAI background-submission bindings. ### Changed +- The exact Git dependency universe now pins `graphql-orm` 0.15.0 at + `6beef53633befd90a4d4810887a3e4640dc4ad91` and `agql-auth` 0.12.0 at the + peeled `v0.12.0` target + `3f3b0c5365adfbe436514a681d977b600991b797`. The ORM update incorporates the + reviewed PostgreSQL constraint-index introspection fix, aligns its optional + auth bridge to the same auth revision, and fixes exact bounded-mutation and + retention-purge sentinels above the public 100-row read cap. No AI entity, + GraphQL SDL, or stored-data migration changes. +- Ordinary CI jobs now resolve the exact upstream revisions from the public + manifest instead of checking out unused sibling worktrees. The SemVer job + now resolves the reviewed exact Git dependencies recorded independently by + the current and baseline manifests; it no longer rewrites a historical + baseline to hard-coded local path dependencies. +- Repository ownership is now explicit and unconditional: every upstream + implementation request must be staged as a copy-ready `.handoffs/` prompt + for a separate owning agent. Agents working in this repository may inspect + upstream state and consume reviewed final SHAs but never mutate an upstream + worktree or branch. + - Schema module `0.46.0` adds deterministic receipt/profile/event-kind/time bindings to the existing private webhook receipt placeholder and combines its deterministic UUID with the existing provider family as private key diff --git a/Cargo.lock b/Cargo.lock index b4ed9b4..1b1daa2 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -10,8 +10,8 @@ checksum = "fe438c63458706e03479442743baae6c88256498e6431708f6dfc520a26515d3" [[package]] name = "agql-auth" -version = "0.10.0" -source = "git+https://github.com/Dastari/agql-auth.git?rev=c92dcb441237bbe308499b26525945f60ffa394a#c92dcb441237bbe308499b26525945f60ffa394a" +version = "0.12.0" +source = "git+https://github.com/Dastari/agql-auth.git?rev=3f3b0c5365adfbe436514a681d977b600991b797#3f3b0c5365adfbe436514a681d977b600991b797" dependencies = [ "argon2", "async-graphql", @@ -62,6 +62,15 @@ version = "0.2.21" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "683d7910e743518b0e34f1186f92494becacb047c7b6bf616c96772180fef923" +[[package]] +name = "android_system_properties" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "819e7219dbd41043ac279b19830f2efc897156490d7fd6ea916720117ee66311" +dependencies = [ + "libc", +] + [[package]] name = "approx" version = "0.5.1" @@ -445,7 +454,9 @@ version = "0.4.45" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "1aa79e62e7697b8e29b513a68abacf485adcd1fe8284a4316c5ae868e6633327" dependencies = [ + "iana-time-zone", "num-traits", + "windows-link", ] [[package]] @@ -906,7 +917,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb" dependencies = [ "libc", - "windows-sys 0.61.2", + "windows-sys 0.52.0", ] [[package]] @@ -1289,10 +1300,11 @@ dependencies = [ [[package]] name = "graphql-orm" -version = "0.9.0" -source = "git+https://github.com/Dastari/graphql-orm.git?rev=f996cdbe2ef1867dea029ec3ff16e051dbe7566e#f996cdbe2ef1867dea029ec3ff16e051dbe7566e" +version = "0.15.0" +source = "git+https://github.com/Dastari/graphql-orm.git?rev=6beef53633befd90a4d4810887a3e4640dc4ad91#6beef53633befd90a4d4810887a3e4640dc4ad91" dependencies = [ "async-graphql", + "chrono", "futures", "geo", "geo-types", @@ -1310,7 +1322,7 @@ dependencies = [ [[package]] name = "graphql-orm-ai" -version = "0.50.0" +version = "0.51.0" dependencies = [ "agql-auth", "async-graphql", @@ -1338,8 +1350,8 @@ dependencies = [ [[package]] name = "graphql-orm-macros" -version = "0.9.0" -source = "git+https://github.com/Dastari/graphql-orm.git?rev=f996cdbe2ef1867dea029ec3ff16e051dbe7566e#f996cdbe2ef1867dea029ec3ff16e051dbe7566e" +version = "0.15.0" +source = "git+https://github.com/Dastari/graphql-orm.git?rev=6beef53633befd90a4d4810887a3e4640dc4ad91#6beef53633befd90a4d4810887a3e4640dc4ad91" dependencies = [ "convert_case", "proc-macro2", @@ -1698,6 +1710,30 @@ version = "0.18.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "4804bdc1dc124eb7e1aa9e144ecc04096bcf787a10a15fa44af682b51f0f6cce" +[[package]] +name = "iana-time-zone" +version = "0.1.65" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e31bc9ad994ba00e440a8aa5c9ef0ec67d5cb5e5cb0cc7f8b744a35b389cc470" +dependencies = [ + "android_system_properties", + "core-foundation-sys", + "iana-time-zone-haiku", + "js-sys", + "log", + "wasm-bindgen", + "windows-core", +] + +[[package]] +name = "iana-time-zone-haiku" +version = "0.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f31827a206f56af32e590ba56d5d2d085f558508192593743f16b2306495269f" +dependencies = [ + "cc", +] + [[package]] name = "icu_collections" version = "2.2.0" @@ -2544,7 +2580,7 @@ dependencies = [ "once_cell", "socket2", "tracing", - "windows-sys 0.61.2", + "windows-sys 0.52.0", ] [[package]] @@ -2885,7 +2921,7 @@ dependencies = [ "errno", "libc", "linux-raw-sys", - "windows-sys 0.61.2", + "windows-sys 0.52.0", ] [[package]] @@ -2976,7 +3012,7 @@ dependencies = [ "security-framework 3.7.0", "security-framework-sys", "webpki-root-certs", - "windows-sys 0.61.2", + "windows-sys 0.52.0", ] [[package]] @@ -3311,6 +3347,7 @@ checksum = "ee6798b1838b6a0f69c007c133b8df5866302197e404e8b6ee8ed3e3a5e68dc6" dependencies = [ "base64 0.22.1", "bytes", + "chrono", "crc", "crossbeam-queue", "either", @@ -3389,6 +3426,7 @@ dependencies = [ "bitflags", "byteorder", "bytes", + "chrono", "crc", "digest", "dotenvy", @@ -3431,6 +3469,7 @@ dependencies = [ "base64 0.22.1", "bitflags", "byteorder", + "chrono", "crc", "dotenvy", "etcetera", @@ -3466,6 +3505,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "c2d12fe70b2c1b4401038055f90f151b78208de1f9f89a7dbfd41587a10c3eea" dependencies = [ "atoi", + "chrono", "flume", "futures-channel", "futures-core", @@ -3578,10 +3618,10 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd" dependencies = [ "fastrand", - "getrandom 0.4.3", + "getrandom 0.3.4", "once_cell", "rustix", - "windows-sys 0.61.2", + "windows-sys 0.52.0", ] [[package]] @@ -4180,7 +4220,42 @@ version = "0.1.11" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22" dependencies = [ - "windows-sys 0.61.2", + "windows-sys 0.48.0", +] + +[[package]] +name = "windows-core" +version = "0.62.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb" +dependencies = [ + "windows-implement", + "windows-interface", + "windows-link", + "windows-result", + "windows-strings", +] + +[[package]] +name = "windows-implement" +version = "0.60.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "windows-interface" +version = "0.59.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358" +dependencies = [ + "proc-macro2", + "quote", + "syn", ] [[package]] @@ -4189,6 +4264,24 @@ version = "0.2.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5" +[[package]] +name = "windows-result" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5" +dependencies = [ + "windows-link", +] + +[[package]] +name = "windows-strings" +version = "0.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091" +dependencies = [ + "windows-link", +] + [[package]] name = "windows-sys" version = "0.48.0" diff --git a/Cargo.toml b/Cargo.toml index 9cadce0..c781d79 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "graphql-orm-ai" -version = "0.50.0" +version = "0.51.0" edition = "2024" authors = ["Toby Martin "] description = "Project-agnostic AI agent runtime for graphql-orm applications" @@ -31,13 +31,13 @@ graphql-case-pascal = [ ] [dependencies] -agql-auth = { git = "https://github.com/Dastari/agql-auth.git", rev = "c92dcb441237bbe308499b26525945f60ffa394a", version = "0.10.0" } +agql-auth = { git = "https://github.com/Dastari/agql-auth.git", rev = "3f3b0c5365adfbe436514a681d977b600991b797", version = "0.12.0" } async-graphql = { version = "7", features = ["uuid"] } async-stream = "0.3" async-trait = "0.1" base64 = { version = "0.22", optional = true } futures = "0.3" -graphql-orm = { git = "https://github.com/Dastari/graphql-orm.git", rev = "f996cdbe2ef1867dea029ec3ff16e051dbe7566e", version = "0.9.0", default-features = false } +graphql-orm = { git = "https://github.com/Dastari/graphql-orm.git", rev = "6beef53633befd90a4d4810887a3e4640dc4ad91", version = "0.15.0", default-features = false } graphql-orm-storage = { git = "https://github.com/Dastari/graphql-orm-storage.git", rev = "f1a1f06483d5fd3a0b8fd17f013b3ad4dd9849c5", version = "0.5.0", default-features = false } hex = "0.4" hmac = { version = "0.12", optional = true } diff --git a/MIGRATION.md b/MIGRATION.md index 984b145..8c89e78 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -4,6 +4,51 @@ Git consumers and disposable test deployments can track schema and API changes without guessing. +## Unreleased: upstream dependency alignment to graphql-orm 0.15.0 and agql-auth 0.12.0 + +Update the exact Git dependency universe to: + +- `graphql-orm` 0.15.0 at + `6beef53633befd90a4d4810887a3e4640dc4ad91`; and +- `agql-auth` 0.12.0 at the peeled `v0.12.0` target + `3f3b0c5365adfbe436514a681d977b600991b797`. + +Remove host patches, path overrides, or direct dependencies that resolve an +older source identity. Hosts enabling the ORM's optional `auth-agql` bridge +must use the same exact auth version and revision so one public type universe +resolves. + +The ORM update includes the reviewed PostgreSQL constraint-index +introspection fix from 0.13.0. Constraint-owned PRIMARY KEY and UNIQUE backing +indexes are no longer planned as ordinary `DROP INDEX` operations, and +composite UNIQUE constraints are rendered and introspected in key order. +Operators must replan the complete generated target and run an owned +prior-to-current migration rehearsal before rollout. Do not mark an older +module version as newly applied to conceal a real historical schema mismatch. + +The 0.15.0 ORM also corrects bounded generated updates, deletes, and retention +purges whose `MutationLimit + 1` sentinel exceeds the public 100-row read cap. +Public GraphQL and repository read limits are unchanged. Residual or in-memory +bounded-mutation predicates now fail before selection or writes; callers must +use fully database-renderable predicates. + +Direct `agql-auth` consumers must also follow its 0.10.0-to-0.12.0 migration. +Version 0.11.0 replaces split durable rate-limit load/save behavior with +revision-bound compare-and-swap; custom durable stores need an atomic revision +column or equivalent and must backfill existing rows. Version 0.12.0 adds the +typed list-valued OIDC `EssentialAcrs` request and `matched_acrs` outcome, +advances stored OIDC policies containing that requirement to representation +version 2, and requires updates to exhaustive matches and public struct +literals. This crate does not implement an auth rate-limit store or infer local +MFA from provider ACR/ACRS evidence. + +This dependency alignment advances the unreleased crate from 0.50.0 to 0.51.0 +and does not change the AI schema module from 0.47.0. It changes no AI entity, +GraphQL SDL, persisted AI data, backup descriptor, or application +authorization policy, so no AI data migration is required. Regenerate +`Cargo.lock`, verify one source/type universe, and rerun the full SQLite, +PostgreSQL, MSSQL, Rustdoc, Clippy, naming, SemVer, and release-policy matrix. + ## Unreleased: exact OpenAI background submission binding (crate 0.49.0 to 0.50.0; schema 0.46.0 to 0.47.0) Apply AI schema module `0.47.0` while provider workers, webhook intake, diff --git a/README.md b/README.md index ef90a57..3ea5d7e 100644 --- a/README.md +++ b/README.md @@ -282,7 +282,7 @@ graphql-orm-ai = { git = "https://github.com/Dastari/graphql-orm-ai", rev = " **Pre-release dependency note:** this source snapshot pins the reviewed final -> `graphql-orm` 0.9.0, `agql-auth` 0.10.0, and `graphql-orm-storage` 0.5.0 +> `graphql-orm` 0.15.0, `agql-auth` 0.12.0, and `graphql-orm-storage` 0.5.0 > commits exactly. Keep the full revisions from this manifest; do not replace > the shared contracts with moving branches or application-specific > substitutes. @@ -452,8 +452,8 @@ Mocked HTTP/SSE tests are the default and require no provider credential. ## Documentation and releases The [documentation index](docs/README.md) links architecture, security, -development, release, and implementation-status guides. Public APIs are -documented in generated Rustdoc. +development, release, implementation-status, and checkpoint-based completion +guides. Public APIs are documented in generated Rustdoc. The root README stays aligned with every public/runtime change. Every user-visible change updates [CHANGELOG.md](CHANGELOG.md), and every public diff --git a/docs/README.md b/docs/README.md index ac67e11..6224084 100644 --- a/docs/README.md +++ b/docs/README.md @@ -31,6 +31,7 @@ Start with the root [README](../README.md), then use the focused guides below. - [Release, SemVer, changelog, and migration process](release-process.md) - [Upstream contribution and multi-repository workflow](upstream-contributions.md) - [Implementation status](implementation-status.md) +- [Checkpoint-based completion plan](completion-plan.md) - [Migration guide](../MIGRATION.md) - [Changelog](../CHANGELOG.md) diff --git a/docs/completion-plan.md b/docs/completion-plan.md new file mode 100644 index 0000000..9860441 --- /dev/null +++ b/docs/completion-plan.md @@ -0,0 +1,416 @@ +# Completion Plan + +This is the active execution plan for completing `graphql-orm-ai` from the +current `0.51.0` dependency-alignment checkpoint. The historical architecture +plan at `1573017:docs/plan.md` remains useful design context, but its original +delivery phases no longer describe the worktree: most foundation, provider, +persistence, authorization, approval, and coordination contracts are already +implemented. + +[Implementation status](implementation-status.md) is authoritative for the +current inventory. This document is authoritative for work order, dependencies, +and exit gates. Update both whenever a slice changes what is implemented or +what remains deliberately closed. + +## Baseline + +- Crate version: `0.51.0` (unpublished pre-release). +- AI schema-module version: `0.47.0`. +- Exact reviewed dependencies: + - `graphql-orm` and `graphql-orm-macros` `0.15.0` at + `6beef53633befd90a4d4810887a3e4640dc4ad91`. + - `agql-auth` `0.12.0` at + `3f3b0c5365adfbe436514a681d977b600991b797`. +- SQLite/provider, warnings-denied Clippy, warnings/missing-docs-denied + Rustdoc, PascalCase GraphQL, PostgreSQL/MSSQL compile-only, owned disposable + PostgreSQL migration, release-policy, package, and SemVer checks pass + locally. +- The dependency-alignment implementation checkpoint is committed and pushed at + `72757bdc63d28ee63d48d0e3e0cd503cb1f27566`; draft PR #2 CI run + `30252247582` passed all four jobs. +- No upstream handoff is currently open. + +## Rules for every slice + +1. Keep the crate project-agnostic. Consumer entities, policies, routes, + deployments, and domain mutations are not implementation shortcuts. +2. Keep all sibling repositories read-only. If a missing reusable contract is + discovered, stop that dependent slice, write a copy-ready prompt under + `.handoffs/`, assign it to the owning repository agent, and wait for a + reviewed final merge or release SHA. +3. Use generated `graphql-orm` repository, transaction, schema-module, + migration, and restore APIs only. Do not introduce raw SQL or a direct + database driver. +4. Rehydrate current principals before provider egress, every application tool, + after approval, and at long-running checkpoints. Never persist bearer + credentials or stale scope/role snapshots. +5. Keep tool registration, provider capability, webhook verification, and + discovery separate from authorization. +6. Preserve exact egress, retention, budget, disclosure, fencing, and + one-shot-approval proofs. Ambiguous external effects remain closed and are + never replayed automatically. +7. Use only temporary/in-memory SQLite or a test-owned disposable Docker + database. Never consume a host database URL. +8. For every public API, GraphQL, schema, persistence, authorization, feature, + or behavioral change, update the changelog, migration guide, focused docs, + Rustdoc, and schema-module version when required. +9. Finish each slice with the repository release matrix. Never use Cargo + `--all-features` while database backends are mutually exclusive. + +## Work order + +```text +0. Durable 0.51.0 checkpoint + | + v +1. OpenAI background terminal reconciliation + | + v +2. Provider-persistent file lifecycle + | + v +3. Supervised ordering/history proof + | + v +4. Recovery, retention, and restore closure + | + v +5. Carefully gated coordination and review expansion + | + v +6. Control-plane and production integration closure + | + v +7. Backend production acceptance +``` + +Slices are ordered by dependency and risk. A later slice may be designed while +an earlier slice is under review, but its runtime boundary must remain closed +until every prerequisite exit gate passes. + +## Slice 0: make the current checkpoint durable + +Status: complete on the draft PR branch. Merge, tagging, and publishing remain +separate owner decisions. + +### Work + +- Review the complete `0.51.0` dependency-alignment diff. +- Verify one Cargo source/type universe for `graphql-orm`, + `graphql-orm-macros`, and `agql-auth`. +- Commit and push the downstream-only change. +- Run branch CI and record the final downstream commit and CI result in + [implementation status](implementation-status.md). +- Confirm the worktree is clean before beginning a schema or runtime change. + +### Exit gate + +- The exact reviewed dependency revisions resolve from a pushed commit. +- The complete local matrix and branch CI are green. +- No ignored handoff, credential, local path, or consumer-specific artifact is + present in the commit. +- No sibling worktree or branch was mutated. + +## Slice 1: OpenAI background terminal reconciliation + +This is the first runtime implementation slice. Exact background submission and +verified webhook intake already exist, but an accepted run remains parked in +`WaitingProvider`, its budget remains uncertain, and a receipt grants no +authority to retrieve output or mutate the run. + +### Design gate + +Before changing code, document the complete state machine and transaction +boundaries in [OpenAI background submission](openai-background.md) and +[OpenAI webhook intake](openai-webhooks.md). The design must cover: + +- deterministic submission, verified receipt, provider response, run, attempt, + generation, profile, model, output ceiling, storage, budget, egress, and + retention matching; +- bounded worker claiming, leases, fencing, idempotency, redelivery, and + concurrent reconciliation; +- just-in-time secret resolution and current-principal rehydration before + provider retrieval and again before durable mutation; +- fixed-destination retrieval with bounded terminal status, output, usage, and + unknown-field handling; +- exact-once budget/usage settlement and protected output persistence; +- cancellation, provider failure, malformed output, revoked authority, policy + changes, expired retention, and ambiguous transport behavior; +- crash windows before retrieval, after retrieval, during protected + persistence, and after terminal commit; and +- restore facts and readiness behavior for pending, complete, invalid, and + recovery-required reconciliation. + +### Implementation + +- Add only the minimum durable state and indexes needed for bounded claims and + exact-once terminal reconciliation. +- Add an OpenAI retrieval capability that cannot list responses, choose a + destination, or retrieve an unbound response ID. +- Reuse provider normalization, disclosure, content protection, egress audit, + pricing, usage, and run-fence contracts rather than creating a background + bypass. +- Commit the protected assistant result, reconciled budget/usage facts, + submission/receipt terminal states, immutable outcome, and run terminal + transition with an explicitly reviewed atomicity boundary. +- Keep unsupported or unprovable provider states in a redacted, + operator-reviewable recovery state. + +### Required tests + +- Exact successful receipt-to-submission-to-response completion. +- Polling or receipt selection cannot substitute for an exact durable match. +- Duplicate receipt, duplicate worker, and restart retry are idempotent. +- Mismatched provider/profile/model/response/storage/output metadata fails + closed. +- Revoked/expired principal, changed session access, denied egress, expired + retention, stale fence, or invalid budget prevents retrieval or mutation as + appropriate. +- Usage cannot settle twice and uncertain capacity is not released without + proof. +- Oversized, malformed, unsupported, incomplete, cancelled, and unknown + provider responses cannot become assistant output. +- Every enumerated crash window has a deterministic retry, terminal, or + recovery-required result. +- Restore readiness rejects invalid reconciliation facts and never replays an + external call. +- SQLite and owned disposable PostgreSQL behavior agree. + +### Exit gate + +- A valid accepted background run can reach one protected terminal outcome + without manual database intervention. +- A verified webhook alone still grants no execution authority. +- No ambiguous provider effect is automatically repeated. +- Budget and usage are reconciled exactly once. +- Focused docs, changelog, migration guide, schema contracts, and the full + release matrix pass. + +## Slice 2: provider-persistent file lifecycle + +Build this on the existing attachment quarantine/release/reopening flow and the +exact profile-bound OpenAI deletion seam. + +### Design gate + +Define separate capabilities for upload, retrieval/use, search, and deletion. +The model must never list files, choose an arbitrary provider object, reuse a +file across an unauthorized scope, or turn a local attachment reference into +provider authority. + +The design must bind: + +- current principal, scope, session, attachment, released object hash and MIME; +- logical provider profile, model/capability, destination, provider file ID, + purpose, expiry, and retention class; +- upload and search egress manifests, budgets, quotas, pricing dimensions, and + immutable audit; +- local/provider object lifecycle, cleanup generations, exact absence proof, + backup metadata, restore readiness, and deleting-session behavior; and +- derivatives to their exact source, producer, policy, and content-protection + state. + +### Implementation and tests + +- Implement bounded upload and exact-reference use/search without list or + arbitrary-ID APIs. +- Add attachment count/byte quotas and derivative records only where the full + cleanup and restore lifecycle is defined. +- Extend pricing and settlement only for dimensions that can be normalized and + reconciled authoritatively. +- Prove concurrent upload idempotency, cross-scope denial, content swap denial, + interrupted upload cleanup, exact deletion, retention expiry, session + deletion, and restore closure on SQLite and owned PostgreSQL. + +### Exit gate + +- Every provider-persistent object has exact creation authority, an owner and + retention binding, bounded use, authoritative cost handling, and a + deterministic deletion or operator-recovery path. +- The crate does not claim upload/search support for a provider until its + entire lifecycle passes conformance tests. + +## Slice 3: supervised ordering and history proof + +This slice is a design deliverable, not permission to open additional runtime +paths. + +### Work + +- Specify canonical ordering for provider calls, parallel application calls, + approvals, mutations, results, egress decisions, budgets, checkpoints, and + continuation history. +- Define what can be adopted across generations without repeating a resolver or + provider effect. +- Separate safe completed-batch adoption from partial read-only work, + consequential work with consumed approval, and unknown external effects. +- Define capacity accounting before approval/checkpoint consumption so a later + continuation cannot exceed loop, provider, tool, or budget bounds. +- Define stateless transcript reconstruction rules for each provider family, + including reasoning or provider-owned state that cannot be safely replayed. +- Review whether partial or parallel consequential batches should remain + permanently unsupported rather than forcing an unsafe generic abstraction. + +### Exit gate + +- The proof has reviewable invariants, state transitions, crash windows, + negative tests, and explicit unsupported cases. +- No runtime path is opened merely because a provider advertises parallel or + multi-call capability. +- Any missing reusable ORM/auth primitive has a copy-ready upstream handoff and + the dependent implementation remains blocked pending a reviewed final SHA. + +## Slice 4: recovery, retention, and restore closure + +Complete lifecycle safety before broadening orchestration. + +### Work + +- Add bounded, privileged uncertain-call recovery based on exact evidence; + never infer success or replay a consequential effect. +- Finish deleting-session and age-based purge handling for provider objects, + attachments/blobs, protected payloads, checkpoints, and other erasable + content while preserving required redacted security facts. +- Define explicit treatment for append-only usage/audit facts, active or + recovery-required runs, accepted proposals, and dependency-ambiguous + artifacts instead of claiming erasure. +- Implement backup adapter execution and applied restore transactions where + current reviewed dependency contracts suffice. +- Keep runtime startup, workers, subscriptions, and callbacks closed until + reconciliation and restore application both succeed. + +### Upstream gate + +Inspect sibling APIs read-only before implementation. If portable transaction, +backup, migration, encrypted-field, or restore primitives are missing, write a +prompt in `.handoffs/` for the owning agent. Do not add SQL, backend-specific +workarounds, substitute types, or downstream copies. + +### Exit gate + +- Every externally uncertain or content-bearing state has a bounded normal, + terminal, retained-with-reason, or privileged-recovery outcome. +- Backup/restore preserves required bindings and cannot reopen stale authority. +- Retention reports distinguish logical tombstoning, physical content/blob + deletion, retained audit facts, and blocked items truthfully. + +## Slice 5: gated coordination and review expansion + +Implement only the paths admitted by the Slice 3 proof, in this order: + +1. validated provider-turn checkpoint adoption; +2. safe partial read-only batch recovery, if proven; +3. sequential multi-call provider-retained supervision; +4. mixed read/write supervision with a fresh checkpoint before every + consequential action; +5. parallel read-only calls; and +6. stateless supervised continuation only for providers whose complete visible + history can be reconstructed safely. + +Parallel consequential execution, autonomous writes, or replay of ambiguous +effects may remain intentionally unsupported. Completion means a defensible +closed boundary, not enabling every provider feature. + +Also add generic per-item proposal review while leaving application-specific +rendering and final domain mutation in the consumer. + +### Exit gate + +- Every consequential action has fresh current authority, exact policy and + resource versions, recent assurance when required, a canonical preview, + one-shot approval, a current resolver authorization check, and its own + egress/budget checkpoint. +- Retries and cross-generation adoption cannot duplicate provider or + application side effects. +- Unsupported batch shapes fail before approval consumption or external I/O. + +## Slice 6: control-plane and production integration closure + +### Work + +- Complete the authenticated tool-enablement configuration lifecycle. +- Generate resolver-operation disclosure metadata where reviewed upstream + contracts expose sufficient information. +- Complete schema-aware recursion/control-plane validation while retaining the + explicit reviewed catalog and fail-closed scanner as defense in depth. +- Complete richer provider file preflight and built-in result normalization for + every capability the crate advertises. +- Add conformance suites for production secret stores/keyrings, delegated + credential issuers, and private GraphQL transports without embedding + deployment-specific implementations. +- Confirm documentation clearly distinguishes a required host implementation + from a missing crate implementation. + +### Upstream gate + +Resolver metadata generation, portable encrypted fields, backend migration +behavior, or other reusable dependency work belongs upstream. If an existing +reviewed API is insufficient, create an upstream handoff and wait; never patch +the sibling repository from this worktree. + +### Exit gate + +- Configuration and disclosure management are authenticated, bounded, + versioned, auditable, and fail closed on schema drift. +- Every production host seam has a public conformance contract and no insecure + built-in fallback. + +## Slice 7: backend production acceptance + +Run acceptance separately for each backend and capability profile. + +### SQLite and PostgreSQL + +- Run formatting, complete tests, warnings-denied Clippy, warnings and + missing-docs-denied Rustdoc, GraphQL naming/SDL contracts, SemVer, packaging, + release policy, and privacy checks. +- Rehearse prior-to-current migration and backup/restore in test-owned stores. +- Run concurrency, stale-fence, crash-window, retention, reconciliation, and + provider conformance suites. +- Publish an exact capability matrix that distinguishes implemented, + host-supplied, deliberately unsupported, and experimental behavior. +- Require consumer owners to perform their own schema composition, migration, + restore, authorization-parity, and deployment tests. + +### MSSQL + +MSSQL production support remains a separate claim. Do not advertise it until +reviewed upstream write, transaction, migration, policy, queue, stream, +encryption, backup, and concurrency parity exists and this crate's disposable +MSSQL matrix passes. Any required upstream work is delegated through +`.handoffs/`; it is never implemented here. + +### Exit gate + +- The selected backend/capability profile meets every applicable production + acceptance criterion with recorded evidence. +- The exact release commit, dependencies, schema module, SDL, migration guide, + changelog, and capability documentation agree. +- Publishing remains an explicit owner decision; passing this gate does not + silently change `publish = false`. + +## Intentionally host- or consumer-owned + +The following do not move into this crate: + +- consumer schema composition, migration acceptance, integration tests, and + restore rehearsal; +- application entities, tenant/domain policy, routes, final proposal rendering, + and domain mutations; +- concrete principal/session persistence and current-principal resolver + implementations; +- deployment-specific delegated credential issuance, private network + transport, audit integration, and secret/key management; +- production OS/container implementation of the trusted local-harness launcher; + and +- frontend routing or execution of typed UI intents. + +The crate should provide safe traits, exact bindings, fail-closed defaults, and +conformance tests for these seams. It should not absorb deployment authority. + +## Current queue + +1. Write the Slice 1 OpenAI background reconciliation state-machine design and + negative-test table. +2. Implement Slice 1 only after that design makes every external-I/O and crash + boundary explicit. diff --git a/docs/development.md b/docs/development.md index 8b78615..b0e02cb 100644 --- a/docs/development.md +++ b/docs/development.md @@ -72,7 +72,9 @@ scripts/check-release-policy.sh cargo semver-checks --baseline-rev --default-features ``` -CI additionally runs `cargo-semver-checks` against a sibling baseline worktree -so local path dependencies resolve consistently. The explicit default-feature -selection is required: the backend features are mutually exclusive, while the -tool's ordinary heuristic attempts to enable every feature at once. +CI additionally runs `cargo-semver-checks` against a baseline worktree. The +current and baseline manifests each resolve their own reviewed exact Git +dependency revisions; CI does not rewrite either universe to local sibling +paths. The explicit default-feature selection is required: the backend +features are mutually exclusive, while the tool's ordinary heuristic attempts +to enable every feature at once. diff --git a/docs/getting-started.md b/docs/getting-started.md index 20824b1..cd6358c 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -5,10 +5,10 @@ reviewed dependency universe for `graphql-orm-ai`, `graphql-orm`, and `agql-auth`. The public manifest pins reviewed full Git revisions; local path overrides are unsupported release artifacts. -The current public source snapshot consumes the final reviewed `graphql-orm` -0.9.0 merge commit and `agql-auth` 0.10.0 annotated-tag target. Standalone Git -builds therefore resolve the reviewed dependency universe without depending -on moving sibling default branches. +The current public source snapshot consumes the reviewed final `graphql-orm` +0.15.0 main commit and the peeled `agql-auth` 0.12.0 annotated-tag target. +Standalone Git builds therefore resolve one reviewed dependency universe +without depending on moving sibling default branches. ## Features diff --git a/docs/implementation-status.md b/docs/implementation-status.md index b00b087..e494286 100644 --- a/docs/implementation-status.md +++ b/docs/implementation-status.md @@ -3,6 +3,10 @@ This file is intentionally explicit about what is a compiled contract versus production-ready behavior. +The [checkpoint-based completion plan](completion-plan.md) defines the active +work order and exit gates. This file remains authoritative for the implemented +and deliberately incomplete inventory. + ## Implemented foundation - Crate scaffold and SQLite/PostgreSQL/MSSQL compile-time backend selection. @@ -488,6 +492,9 @@ production-ready behavior. ## Next implementation slice +The detailed sequence and acceptance gates are maintained in the +[completion plan](completion-plan.md). The leading runtime priorities are: + 1. Complete the OpenAI background lifecycle after exact submission and receipt intake: add a bounded reconciler that matches the exact prepared submission, verified receipt, and provider response, then independently re-proves @@ -509,7 +516,7 @@ intentional. ## Current verification -- The complete `0.50.0` SQLite/provider matrix passed: 148 unit tests, all +- The complete `0.51.0` SQLite/provider matrix passed: 148 unit tests, all integration tests, one explicit live OpenAI test ignored, and 31 generated private-ORM doctests intentionally ignored. - Full warnings-denied Clippy and warnings/missing-docs-denied Rustdoc passed @@ -522,16 +529,22 @@ intentional. - SemVer comparison against pushed `0.49.0` passed. Package-file and tracked- diff privacy review excludes ignored handoffs/plans, credentials, local paths, and project-specific references. -- The current owned-disposable-PostgreSQL prior-to-current migration rehearsal - is blocked by a confirmed pinned-`graphql-orm` introspection defect: - constraint-backing unique indexes are planned as ordinary `DROP INDEX` - operations. The test-owned container was removed. The rehearsal remains - unchanged pending a reviewed upstream fix; no downstream SQL or live/shared - database workaround is permitted. +- The dependency universe now resolves exactly `graphql-orm` 0.15.0 at + `6beef53633befd90a4d4810887a3e4640dc4ad91` and `agql-auth` 0.12.0 at + `3f3b0c5365adfbe436514a681d977b600991b797`, with one runtime/macro/auth + source and public type universe. +- The owned-disposable-PostgreSQL prior-to-current migration rehearsal now + passes with the reviewed upstream constraint-index introspection fix. The + generated plan no longer attempts to drop UNIQUE constraint-backing indexes; + no downstream SQL or live/shared database workaround was introduced, and + the test removed its ownership-labeled container. - Pushed `0.49.0`/schema `0.46.0` and PR CI run `29495696905` are fully green. - The `0.50.0`/schema `0.47.0` work may be carried on the draft branch as a - durable checkpoint, but it is not release-ready until the reviewed upstream - pin is integrated and the owned PostgreSQL upgrade plus branch CI pass. + The current `0.51.0`/schema `0.47.0` dependency-alignment implementation + checkpoint is committed and pushed at + `72757bdc63d28ee63d48d0e3e0cd503cb1f27566`; draft PR #2 CI run + `30252247582` passed unit/compile, owned PostgreSQL parity, release-policy, + and SemVer jobs. The draft PR remains unmerged, and no release/tag/publish + action has occurred. - The mutually exclusive backend features intentionally cannot be checked with Cargo `--all-features` in one build. diff --git a/docs/upstream-contributions.md b/docs/upstream-contributions.md index 9bb523f..eeadcdd 100644 --- a/docs/upstream-contributions.md +++ b/docs/upstream-contributions.md @@ -18,6 +18,13 @@ express required changes as copy-ready prompts in the ignored `.handoffs/` directory and wait for the upstream owner to return a reviewed final commit SHA. +This delegation is unconditional. An agent owning `graphql-orm-ai` never +implements, formats, commits, rebases, merges, or otherwise mutates an upstream +change, even when the change is small or apparently mechanical. Every upstream +implementation request must be staged as a copy-ready `.handoffs/` prompt for a +separately assigned owning agent. Read-only inspection and consuming an already +reviewed final upstream SHA are the only permitted upstream interactions. + ## Dependency sequence For the current stack, merge and repin from the bottom upward: