THOTH-GQL-DATALOADER-01: specify GraphQL DataLoader foundation

[ja573]

Task identity

• Programme: Shared Thoth GraphQL / Backend Architecture
• Control task: THOTH-GQL-DATALOADER-SPEC-01
• Target implementation task: THOTH-GQL-DATALOADER-01
• Risk: HIGH (shared/cross-programme GraphQL architecture)
• Exact base: 687ee0a40360fb28ef9aab1aa41fc69e35ed93ea (develop, the merge of PR ADR-0007: record approved GraphQL DataLoader architecture #800; live origin/develop verified identical at authoring time)
• Branch: docs/shared-architecture/dataloader-foundation-spec

Authority

ADR-0007 (docs/engineering/decisions/ADR-0007-conventional-request-scoped-graphql-dataloader.md) is APPROVED (CTO, 2026-08-11) and repository-authoritative through the merge of PR #800. ADR-0006 remains SUPERSEDED for batching architecture and preserved as the historical record; its pinned-Juniper duplicate-top-level-mutation-execution finding remains a live, separately controlled concern.

This PR carries the implementation specification only. The specification received CTO specification approval on 2026-08-11, granted against the exact independently reviewed head bb4f57e0d446270b4c404879ef61b5e229e90bbf and limited to the exact specification content at that head; commit 310bc4fe mechanically records that approval in the repository. The approval is not implementation authorization, not implementation-branch authorization, and not PR #801 merge authorization.

THOTH-GQL-DATALOADER-01 implementation remains NOT AUTHORIZED.

Scope

Documentation/control record only:

1. docs/engineering/ai-delivery/tasks/THOTH-GQL-DATALOADER-01.md (new, Status: APPROVED — CTO specification approval recorded 2026-08-11; Implementation: NOT AUTHORIZED; the section 18 implementation-authorization record remains blank)
2. CHANGELOG.md (one Unreleased/Added entry describing the specification/control record, updated to reflect the recorded approval)

No runtime, Rust, Cargo, GraphQL schema, migration, workflow, configuration or production change. No implementation branch created.

Architecture carried forward

The proposed specification carries ADR-0007 into a bounded implementable task:

• request-scoped, non-cached DataLoaders (dataloader 0.18.x, non_cached::Loader, default features off, Tokio runtime support), owned by the real GraphQL Context, one request per loader, no static/global/cross-request state;
• async Juniper execution as the supported test/resolver model, with one bounded central test bridge migrating the general execute_sync unit-test path;
• the loader-first scheduling rule carried verbatim as binding;
• explicit 200 max batch size / 10 yield count configuration — no crate defaults;
• try_load only for Thoth DB loaders; total, fail-closed batch functions;
• set-based Diesel behind a tokio::task::spawn_blocking boundary — pool handle crosses the async boundary, the connection never does, no connection across .await, no hidden per-parent SQL loop;
• a safe, non-panicking, shareable batch-error representation preserving each field's actual current GraphQL-visible error convention; the spike's serde round-trip error clone is explicitly prohibited as production plumbing;
• retirement of the unused ADR-0006 A2 infrastructure with a concrete source inventory (batching.rs/GraphqlBatchStore, prefetch.rs, scope.rs shim, Context.batch_store, A2 fixtures/tests). The batching_tests.rs query_path module is split, not wholly retired: its A2-independent mutation-guard/query-path regressions (valid queries never restricted and emit no guard event in any mode; valid-query responses equivalent to the no-guard baseline across guard modes; baseline-invalid queries keep Juniper's canonical error behaviour with no guard event) are preserved and rehosted onto A2-independent fixtures; only its store/scope-specific coverage is retired;
• the mutation concern kept separate: the independent guard mechanism, request-boundary wiring and CLI/env mode resolution preserved with activation state unchanged — but mutation_guard.rs is not preserved in full: the A2-only MutationGuardMode::store_available() API and its guard-mode-as-store-switch coupling documentation are removed with the store; DataLoader availability is independent of guard mode; guard/duplicate-mutation regression evidence rehosted onto A2-independent fixtures;
• explicit observability/operations disposition: required production logs NONE, required metrics/alerts NONE, runbook changes NONE; no deployment, activation, runtime-configuration, guard-mode, request-acceptance or migration effect — test batching instrumentation is evidence, not production observability;
• no production consumer: no production GraphQL field adopts the loader; production SDL must remain byte-identical (byte length + SHA-256 evidence required).

Plus a full acceptance-evidence matrix: batch boundaries (N = 1/100/200/201/500 with expected chunk shapes, both Tokio runtime flavours), scheduling fixtures (including deliberate fragmentation and loader-behind-loader), request isolation, completed-result non-caching, read-write-read freshness, missing-key fail-closed behaviour, real-Diesel connection-instrumented query-count evidence across a chunk boundary (e.g. N=250 → two set-based statements), backend-failure equivalence with no fallback/retry SQL, error-representation tests, preserved duplicate-mutation regression, SDL byte-identity, and the full repository fmt/check/clippy/backend/workspace gate.

Non-goals

No BE-02 implementation and no Publisher.distributionPlatforms; no Thoth Metrics adoption; no production GraphQL field adoption; no Juniper upgrade; no async-graphql migration; no database/data/schema migration; no deployment, workflow dispatch, production secrets, protected-source inspection, production database access or fleet/orchestrator queries; no OBSERVE/ENFORCE activation; no mutation-guard redesign; no PR #799 remediation/merge/closure; no OPS-03 continuation or OPS-04 implementation; no unrelated error-contract normalization, authorization changes or refactors.

Evidence

• Exact base: 687ee0a40360fb28ef9aab1aa41fc69e35ed93ea
• Exact PR head: 310bc4fef853e3d778da70e4ceb3cf53ba5952b5
• Approval recording: commit 310bc4fe records the 2026-08-11 CTO specification approval granted at the previously reviewed exact head bb4f57e0d446270b4c404879ef61b5e229e90bbf (spec header status/approved-by/dependency lines plus the narrowly corrected CHANGELOG.md status clause; no other content change). The approval-only delta bb4f57e0..310bc4fe requires fresh independent exact-head verification before separate CTO merge authorization is requested
• Remediation: commit bb4f57e0 corrects the three CHANGES REQUIRED findings from the independent review of the previous head 26b722d0a16493febeb7a4006159af91b1234f73 (query_path preservation boundary; mutation_guard.rs preservation boundary / store_available() removal; explicit observability and operations disposition)
• Documents inspected: ADR-0007 (full), ADR-0006 (supersession/A2 surfaces), decisions/README.md, decision-register.md, root AGENTS.md, thoth-api/AGENTS.md, task-specification-template.md, THOTH-GQL-BATCH-01.md (conventions), CHANGELOG.md
• Source inspected: thoth-api/src/graphql/{mod,model,batching,prefetch,scope,mutation_guard,batching_fixture,batching_tests,tests}.rs, thoth-api/src/model/tests.rs, thoth-api/tests/support/mod.rs, thoth-api-server/src/lib.rs (guard + async execute path), thoth-errors/src/lib.rs (IntoFieldError), thoth-api/src/db.rs (PgPool), thoth-client/build.rs (SDL generation), src/bin/thoth.rs (guard-mode wiring), Cargo.toml/thoth-api/Cargo.toml/Cargo.lock (juniper 0.16.2, diesel 2.3.10, tokio 1.52.3 dev-only in thoth-api, no dataloader)
• Changed files: exactly the two listed under Scope (the changelog entry received one bounded follow-up commit adding the PR THOTH-GQL-DATALOADER-01: specify GraphQL DataLoader foundation #801 reference, per house convention; the remediation commit touches only the specification file)
• git diff --check: clean
• Relative links and every named source path/line verified against the base
• CI: state as reported on this PR (no docs-specific lint workflow exists beyond check_changelog.yml)

Review gate

CTO specification approval was granted 2026-08-11 at exact head bb4f57e0d446270b4c404879ef61b5e229e90bbf and is recorded by commit 310bc4fe.

Fresh independent exact-head verification of the approval-only delta (bb4f57e0..310bc4fe) is required before separate CTO merge authorization is requested.

Implementation authorization remains a distinct later CTO decision, available only after the approved specification is repository-authoritative on develop. This PR does not claim, and must not be read as granting, implementation authorization.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 310bc4fef8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Add the required implementation report

This specification is marked approved after review, but no corresponding report exists under docs/engineering/ai-delivery/implementation-reports/ (I also searched the review records for THOTH-GQL-DATALOADER and PR 801). Consequently, the exact base/head, changed-file inventory, documentation checks, CI status, and operational/authorization assessment required before review have no durable evidence; add a report completed from the repository template.

AGENTS.md reference: AGENTS.md:L321-L338

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Replace the superseded batching task in the delivery index

Adding this approved ADR-0007 task without updating docs/engineering/ai-delivery/README.md leaves the active delivery index pointing only to THOTH-GQL-BATCH-01 as a current DRAFT dependent on the now-superseded ADR-0006, while omitting this replacement. Agents using the documented index can therefore select the obsolete architecture; add this task and mark or remove the old entry from the active source set.

AGENTS.md reference: docs/engineering/AGENTS.md:L70-L80

Useful? React with 👍 / 👎.

[ja573]

CTO implementation authorization — THOTH-GQL-DATALOADER-01

Date: 2026-08-11

The CTO explicitly authorizes implementation of repository-authoritative THOTH-GQL-DATALOADER-01 as merged by PR #801.

Authorized scope is exactly the approved task specification and ADR-0007: create the bounded implementation branch feature/shared-architecture/graphql-dataloader-foundation, inspect/edit/test the approved implementation surfaces, commit, push, and open a draft implementation PR targeting develop with the required acceptance evidence.

This authorization does not authorize merge of the implementation PR, deployment, release, production activation, production access, workflow dispatch, BE-02, Thoth Metrics adoption, OBSERVE, ENFORCE, PR #799 remediation/merge/closure, or any architecture change outside ADR-0007. High-risk merge still requires fresh independent exact-head review and separate explicit CTO merge authorization.

Implementation must preflight a fresh exact develop base and stop BLOCKED on any specification stop condition.