BE-05 - Deprecate Figshare and Cambridge University Library distribution destinations

[ja573]

BE-05 - Deprecate Figshare and Cambridge University Library distribution destinations

Status

SPECIFICATION CANDIDATE - REVISED AFTER CONTROL PRE-REVIEW - AWAITING INDEPENDENT REVIEW AND CTO APPROVAL

Implementation: NOT AUTHORIZED

Current gate: HOLD - independent specification review, CTO specification approval and a later fresh exact-base implementation authorization are required. Production assignment/job audit remains a separately authorized later read gate.

This revision resolves two blocking findings found during control pre-review on 2026-08-27:

1. a 15-row distributionPlatformOptions response cannot truthfully retain the existing GraphQL description saying it returns the "full list of distribution platforms";
2. opening/updating a Thoth PR may automatically run publish-to-dockerhub and publish a staging PR image to GHCR, so that automatic side effect must be explicit before PR mutation is authorized.

No source, branch, PR, runtime, provider or production mutation is authorized by this specification revision.

1. Task identity

• Programme: Publisher Services and Distribution Configuration
• Parent programme issue: thoth-pub/thoth#765
• Task ID: BE-05
• Repository: thoth-pub/thoth
• Programme stage: platform-inventory amendment / controlled retirement
• Workflow: STANDARD
• Risk: HIGH
• Specification baseline: develop @ a6c8cb2016179db635c4bc86ef366aae190829c2
• Base branch: develop
• PR target: develop
• Proposed task branch after implementation authorization: feature/publisher-services/be-05
• Exact authorized implementation base: NONE - must be freshly established immediately before implementation
• Owner / implementation agent: not yet assigned
• Independent reviewer: must be a different agent instance; for HIGH risk prefer a different model/model family
• Production/runtime effect at this gate: NONE

Namespace preflight at this specification revision found no branch named feature/publisher-services/be-05. This is not implementation authorization and must be repeated immediately before branch creation.

The CTO-approved programme decision of 2026-08-27 retires Figshare and University of Cambridge Library as Thoth distribution services. This issue specifies the bounded backend/source change implementing that decision; the programme decision does not itself authorize implementation, merge, release, deployment, data access or activation.

2. Objective

Retain the stable historical DistributionPlatform identities for Figshare and Cambridge University Library while making both destinations unavailable for new publisher assignment and absent from the public assignment-option list, without deleting historical configuration/location evidence, changing GraphQL executable type shape, or activating automatic distribution-job creation.

JISC_NBK remains deliberately different: it remains a known inactive/non-assignable destination that is still returned as a visible disabled assignment option.

3. Background and authority

Repository-authoritative ADR-0004 and docs/publisher-services/platform-inventory.md currently classify FIGSHARE and CAMBRIDGE_UNIVERSITY_LIBRARY as active, assignable AutomaticPush destinations. Merged code matches that decision: their descriptors are Active + Assignable, DistributionPlatform::ALL contains all 17 stable values, and DistributionPlatformOption::all() currently projects all 17.

The canonical lifecycle already enforces assignability at both the pool-level and connection-scoped enable primitives, and the canonical service-configuration coordinator pre-validates the whole normalized desired set before writes. BE-05 must change the shared code-owned descriptor policy rather than add a second retirement-specific validation path.

Authoritative source seams:

• docs/engineering/decisions/ADR-0004-distribution-platform-inventory.md
• docs/publisher-services/platform-inventory.md
• thoth-api/src/model/publisher_distribution_platform/mod.rs
• thoth-api/src/model/publisher_distribution_platform/crud.rs (read-only context; no edit expected)
• thoth-api/src/model/publisher_service_configuration/crud.rs (read-only context; no edit expected)
• thoth-api/src/graphql/query.rs
• existing focused model/service-configuration/GraphQL tests

4. Explicit scope

BE-05 must:

1. retain all 17 stable DistributionPlatform enum values and their serialized/database identities;
2. make CAMBRIDGE_UNIVERSITY_LIBRARY and FIGSHARE Inactive + NonAssignable;
3. introduce an internal, code-owned assignment-option visibility policy distinct from assignability/readiness;
4. hide only Cambridge and Figshare from DistributionPlatformOption::all() while retaining JISC_NBK as visible/non-assignable;
5. make distributionPlatformOptions return the 15 visible assignment options in canonical relative order;
6. update the GraphQL field description so it truthfully describes an assignment-option projection rather than the full stable enum inventory;
7. preserve GraphQL executable shape: same field name, return type, option fields, enum values and nullability;
8. update ADR-0004 and the current platform inventory to record the approved retirement semantics;
9. preserve existing canonical read/history behavior for retained retired enum values;
10. add focused regression tests and a bounded CHANGELOG.md entry.

5. Non-goals

BE-05 must not:

• delete, rename, renumber or reuse a DistributionPlatform enum value;
• delete or rewrite existing publisher assignment rows, configuration history, distribution-job rows or historical Location records;
• add a database migration or edit schema.rs;
• create a frontend denylist or require app-specific policy logic;
• edit thoth-app or thoth-dissemination source;
• alter package/capability semantics, auth policy, distribution-job state-machine behavior or worker logic;
• execute production reads/writes, direct SQL cleanup, migration/backfill tooling, provider operations or workflow dispatches;
• enable THOTH_DISTRIBUTION_JOB_CREATION;
• merge, release, deploy or activate production behavior.

6. Cross-repository impact

Affected contracts:

Contract	Impact
database/schema	NOT AFFECTED - stable enum/database labels and tables remain unchanged
domain behavior	AFFECTED - two descriptors become inactive/non-assignable/hidden from assignment options
GraphQL executable schema shape	NOT AFFECTED - same enum values, fields, types and nullability
GraphQL response behavior	AFFECTED - distributionPlatformOptions changes from 17 rows to 15
GraphQL descriptions	AFFECTED - one field description changes to remain truthful
generated clients/types	REMAINS COMPATIBLE - description-only SDL drift and response-subset change require no new type
authorization	NOT AFFECTED
export formats	NOT AFFECTED
environment/configuration	NOT AFFECTED
durable job schema/payload	NOT AFFECTED; new activation of the retired destinations becomes impossible through canonical writes
dissemination execution	AFFECTED downstream - owned by thoth-pub/thoth-dissemination#101 (DIS-03)
UI assumptions	AFFECTED but compatible - owned/verified by thoth-pub/thoth-app#157 (APP-04)

Known direct consumers verified in repository source:

• thoth-pub/thoth-dissemination consumes distributionPlatformOptions for its pinned Publisher Services platform contract. REQUIRES CHANGE, tracked as DIS-03 / Output to CSV #101. It must not guess this unmerged contract.
• thoth-pub/thoth-app consumes distributionPlatformOptions. REMAINS SOURCE-COMPATIBLE because its editors render backend-returned option membership generically; integration verification is tracked as APP-04 / Unify docker images with new domain #157.

Compatibility requirement: the stable GraphQL enum and field/type shape remain usable throughout the cross-repository window. Downstream dissemination source must pin the exact merged BE-05 contract before changing its local compatibility map.

Preferred source order:

BE-05 source merge (not production activation) -> DIS-03 pins merged BE-05 contract -> DIS-03 source merge -> separately authorized dissemination release/runtime retirement -> production assignment/job reconciliation -> BE-05 backend production activation -> APP-04 integration verification

7. Invariants

The implementation must preserve:

1. DistributionPlatform::ALL remains exactly the same 17 values in the same canonical order.
2. Retired enum values remain parseable/serializable/database-valid and usable for historical reads and reverse lookup.
3. Historical assignment/audit/location/job evidence is never deleted by this task.
4. JISC_NBK remains inactive, non-assignable and visible in assignment options.
5. The existing DistributionPlatformNotAssignable rule remains the single canonical assignment rejection rule.
6. Whole-set pre-validation remains atomic: a desired set containing any retired/non-assignable destination writes nothing.
7. Disable/read paths for already-existing retired assignments remain usable so later controlled reconciliation is possible.
8. Automatic distribution-job creation remains OFF unless separately approved later.
9. No downstream repository guesses an unmerged upstream contract.

8. Required behavior

8.1 Descriptor policy

Introduce internal Rust vocabulary equivalent to:

AssignmentOptionVisibility::Visible
AssignmentOptionVisibility::Hidden

as a descriptor field/helper. It is deliberately not a GraphQL field and is not inferred from assignment availability or mechanism readiness.

Required outcomes:

Platform	Mechanism readiness	Assignment availability	Assignment-option visibility
CAMBRIDGE_UNIVERSITY_LIBRARY	Inactive	NonAssignable	Hidden
FIGSHARE	Inactive	NonAssignable	Hidden
JISC_NBK	Inactive	NonAssignable	Visible
all other current destinations	unchanged	unchanged	Visible

backCatalogueBehaviour and the retained adapter-profile identity may remain as historical/domain classification. ADR-0004 and the inventory must say explicitly that a retained adapter-profile identity does not assert a currently executable/supported service.

8.2 Visible option projection

DistributionPlatformOption::all() becomes the authoritative visible assignment-options projection:

• iterate the stable 17-value enum inventory;
• include only descriptors with visible assignment-option status;
• preserve canonical relative order;
• return exactly 15 rows;
• omit only CAMBRIDGE_UNIVERSITY_LIBRARY and FIGSHARE;
• retain JISC_NBK with assignable=false.

8.3 Assignment mutation

Reuse DistributionPlatform::is_assignable() and the existing lifecycle/coordinator validation. Do not add a retirement-specific validator.

After BE-05, attempts to enable either retired platform through the low-level supported lifecycle or canonical service-configuration coordinator must return the existing DistributionPlatformNotAssignable classification before any persistent write. Mixed valid+retired complete-set replacements must fail atomically with no package, assignment, audit or durable-job write.

Disable paths remain permitted for retained historical assignments.

8.4 GraphQL compatibility and truthful description

The current QueryRoot::distribution_platform_options description says it returns the "full list of distribution platforms and their metadata". That becomes false when two stable enum identities are deliberately omitted.

Therefore BE-05 must update only that description to wording equivalent to:

Query the visible distribution-platform assignment options and their metadata. Retired stable platform identities may be omitted.

The executable GraphQL contract must otherwise remain unchanged:

• DistributionPlatform retains all 17 enum values;
• distributionPlatformOptions keeps the same name and list return type;
• DistributionPlatformOption keeps the same fields/types/nullability;
• no new GraphQL visibility/readiness field is introduced.

A byte-identical SDL is not expected after this correction. Required evidence instead is that the generated SDL diff is confined to the intended distributionPlatformOptions description and contains no executable type/field/enum/nullability change.

thoth-app's pinned v1.7 SDL remains executable-compatible and does not need a re-pin or generated-type change merely for a server-side description change and a smaller returned list.

9. Data, migration, auth and operations

• Database migration required: NO
• schema.rs change: NO
• Data/backfill in this source task: NO
• Authorization change: NO
• New logs/metrics: NO
• Provider/runtime access for implementation validation: NO
• Production assignment/job audit: separate later authorization

10. Required documentation amendment

Update both current repository-authoritative decision surfaces:

• docs/engineering/decisions/ADR-0004-distribution-platform-inventory.md
• docs/publisher-services/platform-inventory.md

Record that:

• the stable inventory remains 17 enum identities;
• Figshare/Cambridge are retained deprecated identities, inactive, non-assignable and hidden from assignment options;
• JISC NBK remains visible-but-inactive/non-assignable;
• the GraphQL assignment-option projection intentionally contains 15 rows while the enum inventory remains 17;
• dissemination execution is retired separately by DIS-03 / thoth-pub/thoth-dissemination#101;
• historical rows/locations/audit evidence remain valid historical evidence;
• automatic distribution-job creation remains OFF.

Do not rewrite historical ADR-01/BE-02 task specifications or implementation reports as if this decision existed at the time.

11. Exact candidate write budget

Existing files permitted:

• docs/engineering/decisions/ADR-0004-distribution-platform-inventory.md
• docs/publisher-services/platform-inventory.md
• thoth-api/src/model/publisher_distribution_platform/mod.rs
• thoth-api/src/model/publisher_distribution_platform/tests.rs
• thoth-api/src/model/publisher_service_configuration/tests.rs
• thoth-api/src/graphql/distribution_platform_tests.rs
• thoth-api/src/graphql/query.rs - description-only change for distributionPlatformOptions
• CHANGELOG.md

New files: NONE

Deletion/move/rename: NONE

Explicitly prohibited without specification amendment:

• database migrations / thoth-api/src/schema.rs
• GraphQL mutation/type/model source outside the paths listed above
• generated/pinned downstream app schema artifacts
• distribution-job state-machine source
• auth/policy source
• package/capability source
• production scripts/data manifests
• provider/deployment/workflow configuration
• thoth-dissemination or thoth-app source

If implementation requires another path, return HOLD before editing it.

12. Test-first implementation sequence

1. Update focused model/GraphQL/service-configuration tests first to express the 17-enum / 15-visible-option contract and prove they fail on the baseline.
2. Generalize the existing non-assignable tests to cover JISC_NBK, FIGSHARE and CAMBRIDGE_UNIVERSITY_LIBRARY, including mixed valid+retired desired sets and low-level enable rejection.
3. Add the internal descriptor visibility policy and update only the two retired descriptors plus the default visible state of the remaining inventory.
4. Change DistributionPlatformOption::all() to filter by descriptor visibility while preserving canonical order.
5. Change only the distributionPlatformOptions GraphQL description required for truthful API documentation.
6. Update ADR-0004 and the current platform inventory.
7. Add the bounded CHANGELOG.md entry under the appropriate Unreleased heading.
8. Run full validation and prove the SDL executable shape is unchanged apart from the intended description diff.

13. Required acceptance/test evidence

At minimum prove:

• DistributionPlatform::ALL remains exactly 17 unchanged values in canonical order;
• string/serde round-trip still supports both retired enum values;
• CUL/Figshare descriptors are inactive, non-assignable and hidden;
• JISC is inactive, non-assignable and visible;
• every other descriptor retains its current readiness/assignability and is visible;
• DistributionPlatformOption::all() returns exactly 15 values, omitting only CUL/Figshare and retaining JISC;
• GraphQL distributionPlatformOptions returns the same 15-row projection;
• the GraphQL enum still contains all 17 platform values;
• the only SDL change is the approved option-field description wording;
• direct supported PublisherDistributionPlatform::enable rejects CUL/Figshare/JISC before a write;
• the canonical configuration coordinator rejects CUL/Figshare/JISC before any write;
• a mixed valid+retired request is fully rejected with no partial write;
• disable/read/reverse-lookup behavior remains available for retained historical retired assignments;
• ordinary valid assignment/disable/linkage behavior remains green;
• no migration/schema/auth/job-state-machine change exists.

14. Required validation

For the later implementation PR, report at minimum:

git diff --check
cargo fmt --all -- --check
cargo check --workspace
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace

Also capture and review the generated create_schema().as_sdl() diff, requiring that the only SDL change is the approved distributionPlatformOptions description.

No production API/database/provider access is required for source validation.

15. Candidate implementation action-authorization matrix

This matrix is part of the specification only and is NOT active authorization. It becomes usable only if a later CTO implementation-authorization record explicitly adopts it at one exact base SHA.

Action	Candidate authorization
repository/GitHub read inspection	YES
source/worktree edits within the listed write budget	YES
create new files	NO
delete/move/rename files	NO
branch creation from exact authorized base	YES
local validation	YES
commit	YES
push	YES
open/update draft PR	YES only if the implementation authorization explicitly acknowledges the automatic CI/container-publication side effect below
issue/comment mutation for task evidence	YES
manual CI dispatch/rerun	NO
provider/runtime read	NO
provider/runtime write	NO
migration execution	NO
release/tag/publication action	NO
merge	NO
deployment	NO
production activation	NO
THOTH_DISTRIBUTION_JOB_CREATION mutation	NO

16. Automatic side effects

Live baseline workflow inspection shows:

• build_test_and_check.yml runs on pull requests and on pushes to develop/master;
• docker_build_and_push_to_dockerhub.yml runs on pull_request and, when its classifier selects the Docker path, logs into GHCR and pushes a staging-pr-* container image.

Therefore opening/updating a BE-05 PR can have an automatic external container-publication side effect even though the task itself contains no workflow edit. A later implementation authorization that permits PR mutation must explicitly acknowledge/authorize this expected automatic side effect. If that authorization is absent, the implementation agent must stop before opening/updating the PR.

No manual CI dispatch is authorized. No production deployment, migration, provider action or distribution activation is implied by CI or staging-image publication.

17. Production assignment transition - separate later gates

The source change is not safe to activate blindly in production because complete-set replacement validates the whole desired platform set. If a publisher still has CUL/Figshare enabled when those values become non-assignable, a later unrelated replacement that retains the enabled value will fail until it is removed.

Keep these gates distinct:

1. BE-05 source implementation/review/merge;
2. DIS-03 source implementation/review/merge;
3. separately authorized dissemination release/runtime retirement;
4. separately authorized production read/audit of enabled CUL/Figshare assignments and relevant durable-job state;
5. disposition of every current assignment/job;
6. separately authorized production write to disable required assignments through the canonical coordinator/audit path, never ad-hoc SQL by default;
7. post-write reconciliation showing no unexplained enabled retired assignment;
8. backend release/deployment/activation of BE-05 behavior;
9. APP-04 integration verification;
10. observation/closure.

Pending/running durable jobs must be reconciled through their canonical lifecycle. A RUNNING attempt is not assumed safely cancellable. Production state must be read, not inferred.

THOTH_DISTRIBUTION_JOB_CREATION remains OFF throughout unless a completely separate later activation is approved.

18. Rollout

Initial state after merge to develop: source decision is merged but production behavior is not assumed active.

No feature flag is introduced by BE-05. Production cutover is therefore controlled by deployment/release ordering and the pre-activation assignment/job reconciliation above.

Stop conditions before backend production activation:

• DIS-03 executable retirement is not production-effective;
• production assignment/job audit is incomplete;
• unexplained enabled CUL/Figshare assignment remains;
• rollback path is not agreed;
• automatic job-creation state differs from the approved OFF state.

19. Rollback

Before production activation: revert the exact BE-05 source PR if required.

After production assignment reconciliation, a source rollback may re-expose the destinations as assignable options and must not be performed casually. It must account for whether DIS-03 has already removed executable service paths. Do not restore an assignable API/UI state without an executable service merely to reverse source.

No historical data restoration should be required because BE-05 deletes no historical rows.

20. HOLD / STOP

HOLD if:

• this exact revised specification is not independently reviewed and CTO-approved;
• the implementation base is not freshly authorized at one exact SHA;
• develop moves after base authorization;
• feature/publisher-services/be-05 or a materially overlapping PR appears;
• another source path becomes necessary;
• GraphQL executable shape would change beyond the approved description-only drift;
• production assignment/job state is unknown at activation gate;
• DIS-03 cannot consume a pinned merged BE-05 contract;
• safe rollout ordering cannot be established;
• PR creation would trigger an automatic publication side effect not explicitly covered by the implementation authorization.

STOP if implementation begins:

• deleting/reusing enum values;
• adding frontend-specific policy to backend output;
• direct production SQL cleanup;
• deleting historical audit/location/configuration evidence;
• changing unrelated package/auth/job architecture;
• enabling automatic job creation;
• dispatching CI manually;
• merging/releasing/deploying/activating without separate applicable authorization.

21. Expected implementation report and review

The implementing agent must use the canonical implementation-report structure and report exact base/head, commits, files changed, deviations, migration/data/auth effects, validation commands/results, CI/PR state, automatic external effects and remaining gates.

The implementing agent may self-assess but may not approve its own work. HIGH-risk independent source review must be bound to the exact head SHA; a later source commit invalidates approval.

22. Branch and integration plan

• branch source: freshly authorized exact develop SHA
• task branch: feature/publisher-services/be-05
• PR target: develop
• workflow: STANDARD
• downstream contract order: BE-05 merge before DIS-03 source implementation
• branch deletion after merge: YES
• repository release path: develop -> master, separately controlled
• merge authorization: separate HIGH-risk CTO gate after exact-head approval

23. Current authorization

Authorized in the current control-plane step:

• read-only repository/GitHub inspection;
• issue/specification mutation and bounded coordination comments.

Not authorized now:

• source/file writes or deletions;
• branch creation/update;
• commit/push;
• PR creation/mutation;
• manual CI dispatch/rerun;
• automatic staging-image publication caused by a new PR;
• production/provider/database read or write;
• migration execution;
• release/deployment;
• merge;
• production activation;
• THOTH_DISTRIBUTION_JOB_CREATION mutation.

24. Next action

Obtain independent specification review of this revised exact issue body, then CTO specification approval. After approval, freshly reverify develop, branch/PR overlap, CI side effects and the exact write budget before issuing a separate implementation authorization bound to one exact base SHA.

[ja573]

CONTROL DEVIATION RECORD - 2026-08-27

During the read/specification-preparation step for BE-05, the control agent accidentally invoked the GitHub PR metadata update endpoint against unrelated thoth-pub/thoth#799, attempting only maintainer_can_modify=true.

GitHub rejected the request with HTTP 422 (Fork collab can only be enabled on cross-repo pull requests). No PR metadata, source, branch, issue, CI, runtime, provider or production state changed.

The attempted PR mutation was outside the authorized issue-only mutation scope and is recorded here rather than omitted. No retry was made. Subsequent mutations in this control step are restricted to the explicitly authorized issue/specification ledger actions.

[ja573]

CONTROL PRE-REVIEW - REVISED SPECIFICATION READY FOR INDEPENDENT REVIEW

Decision type: CONTROL PRE-REVIEW ONLY - NOT INDEPENDENT APPROVAL.

I re-reviewed the BE-05 candidate against live repository doctrine and source at:

• issue body updatedAt: 2026-08-27T13:58:01Z
• develop: a6c8cb2016179db635c4bc86ef366aae190829c2
• no feature/publisher-services/be-05 branch observed at pre-review

Findings resolved in the revised body

1. GraphQL description contradiction - RESOLVED. The baseline field description says distributionPlatformOptions returns the "full list of distribution platforms". That would be false for the approved target 15-row visible-option projection while the stable enum remains 17. The revised specification therefore adds thoth-api/src/graphql/query.rs to the exact write budget for a description-only correction. Executable GraphQL shape must remain unchanged; byte-identical SDL is no longer required, and the generated SDL diff must be confined to that description.
2. Automatic PR side effect - RESOLVED. Live Thoth workflow inspection confirms an ordinary PR may run docker_build_and_push_to_dockerhub.yml, which can push a staging-pr-* image to GHCR. The candidate implementation matrix now requires a later exact-base authorization to acknowledge that automatic publication side effect before PR mutation is permitted.
3. Canonical assignment enforcement - CONFIRMED. Both supported low-level enable paths and the canonical service-configuration coordinator already derive rejection from is_assignable(). BE-05 therefore changes the shared descriptor policy rather than adding a retirement-specific validator or editing lifecycle/coordinator source.
4. Data/schema boundary - CONFIRMED. The target retains all 17 enum/database identities, requires no migration or schema.rs edit, and leaves historical assignment/audit/location/job evidence intact. The write budget is now eight existing files, no new files and no deletions.
5. Cross-repository order - CONFIRMED. thoth-dissemination#101 must consume the exact merged BE-05 contract; thoth-app#157 remains executable-schema compatible and is verification-only unless later evidence proves a defect.

Gate

No additional blocking specification finding is known from this control pre-review. However, this comment is not an independent review decision: the same control agent participated in preparing/amending the specification, so it cannot satisfy the independent-review requirement.

Current gate: HOLD - distinct independent specification review -> CTO specification approval -> fresh exact-base implementation authorization.

No source, branch, PR, CI dispatch, provider/runtime/data, merge, release, deployment or activation action is authorized by this comment.

[ja573]

INDEPENDENT SPECIFICATION REVIEW HANDOFF - BE-05

Review requested. This handoff is not a review decision and authorizes no implementation.

Review the complete current BE-05 specification in this issue, headed:

SPECIFICATION CANDIDATE - REVISED AFTER CONTROL PRE-REVIEW - AWAITING INDEPENDENT REVIEW AND CTO APPROVAL

Fresh review baseline verified immediately before this handoff:

• repository: thoth-pub/thoth
• develop: a6c8cb2016179db635c4bc86ef366aae190829c2
• candidate issue body was re-fetched before this comment; if the body is materially edited after this handoff, return HOLD and review the new body rather than relying on this package
• programme decision: parent #765, retirement decision comment 5438819001
• prior control pre-review: comment 5440266415 - advisory evidence only, explicitly not independent approval
• risk: HIGH; use a distinct reviewer/agent instance, preferably a different model/model family from the specification-preparation context

Required independent inspection

Do not approve from the issue prose alone. Inspect the actual baseline source, repository doctrine and surrounding behavior needed to test the specification's premises. In particular verify:

1. the stable DistributionPlatform inventory remains exactly 17 identities and can retain CUL/Figshare without migration/schema changes;
2. assignment-option visibility is correctly specified as a policy distinct from mechanism readiness and assignability, so CUL/Figshare can be hidden while JISC_NBK remains visible/non-assignable;
3. the proposed 15-row DistributionPlatformOption::all() projection omits only CAMBRIDGE_UNIVERSITY_LIBRARY and FIGSHARE, preserving canonical relative order;
4. the GraphQL change is limited to response membership plus a truthful description-only SDL change, with no executable enum/field/type/nullability break;
5. canonical assignment rejection remains derived from is_assignable() in the supported low-level lifecycle and whole-set service-configuration coordinator, including atomic rejection of mixed valid+retired desired sets;
6. retained retired identities remain usable for disable/history/reverse-read paths required by later reconciliation;
7. no migration, schema.rs, auth, package/capability or distribution-job state-machine change is required or silently implied;
8. the exact write budget, no-new-file/no-deletion boundary, test-first plan and required workspace validation are sufficient;
9. ordinary PR creation may automatically publish a staging-pr-* GHCR image and the specification correctly keeps that side effect subject to later explicit implementation/PR authorization;
10. cross-repository ordering is safe: BE-05 source first, DIS-03 pins the exact merged contract, dissemination runtime retirement remains separate, production assignment/job audit and reconciliation remain separately authorized, and app verification remains downstream;
11. rollout/rollback/HOLD conditions do not hide any production-data, provider or compatibility obligation.

Required decision record

Post a new comment on this issue using exactly one decision:

• APPROVED - the exact specification reviewed is implementable as written with no blocking finding;
• CHANGES REQUIRED - list every blocking correction/evidence gap with source/spec references;
• BLOCKED - identify the authority/dependency/environment condition preventing safe specification approval.

The review comment must identify the reviewer context/model, the exact develop SHA reviewed, and whether the issue body still matched this handoff's candidate when review began.

An APPROVED decision is specification approval evidence only. It does not authorize source edits, branch creation, commit, push, PR mutation, GHCR publication, production/provider/data access, merge, release, deployment or activation. A later CTO specification approval and fresh exact-base implementation authorization remain required.

[ja573]

INDEPENDENT SPECIFICATION REVIEW - BE-05

Decision: CHANGES REQUIRED

Reviewer context

• Reviewer: independent specification-review agent instance, distinct from the specification-preparation context
• Model: Claude Opus 5 (claude-opus-5), Anthropic; Claude Code CLI harness
• Review type: specification review only. No source edit, branch, commit, push, PR, CI dispatch, provider/production access, merge, deployment or activation was performed. Inspection was read-only against local clones and the GitHub API.
• Review date: 2026-08-27

Baseline verified

• Repository: thoth-pub/thoth
• develop reviewed: a6c8cb2016179db635c4bc86ef366aae190829c2 (re-verified live; Merge pull request #838 …, 2026-08-26T16:53:36+01:00) - matches the handoff baseline exactly
• Handoff followed: comment 5441154877 (2026-08-27T15:10:31Z)
• Issue body still matched the handoff candidate: body lastEditedAt is 2026-08-27T13:58:01Z, i.e. before the handoff comment; updatedAt 2026-08-27T15:10:32Z is the handoff comment itself. The reviewed body is headed SPECIFICATION CANDIDATE - REVISED AFTER CONTROL PRE-REVIEW - AWAITING INDEPENDENT REVIEW AND CTO APPROVAL and contains both control pre-review corrections (§8.4 truthful description, §16 automatic GHCR side effect). No HOLD for body drift.
• Also inspected: parent #765 decision comment 5438819001; control pre-review 5440266415 (read as advisory only, not relied on as approval); thoth-pub/thoth-dissemination @ 7f99fa76b02c9dcdbbfdd1aecb731bfb668f866a; thoth-pub/thoth-app @ origin/main fd88691e0bf9d7aa05a9ba016c7a89a391744f3f; #828 (MIG-01) lifecycle comments.

---

Blocking findings

F1 - The documentation-authority path contradicts repository ADR doctrine, and the write budget forecloses the compliant path

Specification §10 instructs an in-place amendment of docs/engineering/decisions/ADR-0004-distribution-platform-inventory.md; §11 sets New files: **NONE** and omits docs/engineering/decisions/decision-register.md.

Source evidence at a6c8cb20:

• docs/engineering/decisions/README.md, "Amendments": "After approval: material architectural changes require a new ADR that supersedes the old one; factual clarifications may update the ADR only when they do not alter the decision." ADR-0004 status is APPROVED AND REPOSITORY-AUTHORITATIVE.
• ADR-0004 §10 (Rollout and rollback implications): "If a later approved decision changes the inventory, it supersedes this ADR explicitly rather than editing history."
• ADR-0004 §4.1 is the decision itself and carries a per-platform Assignment availability column: CAMBRIDGE_UNIVERSITY_LIBRARY … assignable and FIGSHARE … assignable. §8 invariant 6 records availability at ADR-invariant level (JISC_NBK is included, inactive, non-assignable and job-free). BE-05 inverts that column for two of the 17 values and introduces a new descriptor axis (assignment-option visibility) that ADR-0004 does not contain. That is not a factual clarification that leaves the decision unaltered.
• docs/engineering/decisions/README.md names decision-register.md as the record of current decisions. Every prior ADR status/content change updated it: ADR-0006 carries SUPERSEDED in the register after ADR-0007; the most recent comparable task, CTRL-BRANCH-NAMESPACE-01 (commit 6acbf2fe, PR CTRL-BRANCH-NAMESPACE-01: correct programme-integration branch namespace #838), changed decision-register.md in the same PR that added ADR-0009.
• docs/publisher-services/platform-inventory.md has the same problem: its header is a content approval bound to exact head 44e6f821535fbee56c830dd6eda237fc6d06fbfd.

Consequence as written: the implementing agent either (a) materially rewrites an approved, repository-authoritative ADR in place against that ADR's own recorded rule and the ADR process doctrine, or (b) needs a new superseding ADR file and a decision-register.md edit - both outside the §11 budget - and must therefore HOLD under §20 ("another source path becomes necessary") part-way through the task. Neither outcome is acceptable for a HIGH-risk bounded specification.

Note: parent decision comment 5438819001 describes BE-05 as "ADR-0004 amendment", but a programme decision comment is not an ADR and does not by itself dispose of the ADR-process rule or of ADR-0004 §10.

Required correction (any one, stated explicitly in the specification):

1. adopt the superseding-ADR route: extend §11 to permit exactly one new docs/engineering/decisions/ADR-00NN-*.md and an edit to decision-register.md, and say what ADR-0004's status becomes; or
2. record an explicit CTO decision that this specific change is handled as an in-place amendment notwithstanding decisions/README.md and ADR-0004 §10, and still add decision-register.md to the write budget so the current-decision index does not go stale.

F2 - Blast radius and invariant 5 are inaccurate: a third in-repository is_assignable() consumer is not recorded

thoth-api/src/model/publisher_service_configuration/migration_backfill.rs:1110 rejects a manifest platform that is not assignable, but with a different classification and different granularity:

if !platform.is_assignable() {
    return Err(ThothError::MigrationBackfillManifestInvalid(format!(
        "platform {platform} requested for publisher {publisher_id} is not assignable"
    )));
}

It sits inside build_plan, so the failure aborts the whole dry-run/apply, not just the affected entry.

Against the specification:

• §3 names only the low-level lifecycle and the service-configuration coordinator as the enforcement seams.
• §7 invariant 5 states the DistributionPlatformNotAssignable rule "remains the single canonical assignment rejection rule". After BE-05 there are two rejection classifications keyed on the same predicate, and this one is not DistributionPlatformNotAssignable.
• §6 claims "Known direct consumers verified in repository source" and does not list this one; §13 requires no evidence for it; §11 does not include the file (correctly - it needs no edit, but it does need to be recorded).

Live materiality: MIG-01 (#828) is CLOSED/complete and was executed against production on 2026-08-25 (comments 5412605297, 5412808243, 5412856863): 118 plan publishers, 143 platform rows, 143 enabled, 0 disabled. Its post-run verification is a deterministic rerun of a frozen manifest (58fa6d43e9bdb5529d2f1c591a247bd355b52ec44e05b2710762c5c302e81faf) that must return REVIEWED_NOOP / ALREADY_APPLIED_BY_THIS_PLAN with 0 pending and 0 drift. If that manifest names FIGSHARE or CAMBRIDGE_UNIVERSITY_LIBRARY for any publisher, that rerun stops being reproducible after BE-05: it aborts as MigrationBackfillManifestInvalid instead of classifying. That is a real change to the reproducibility of a completed CRITICAL production operation's verification path, and the specification claims a blast radius that excludes it.

Required correction: record this consumer in §3/§6, correct §7 invariant 5's wording, state the intended post-BE-05 behaviour of the MIG-01 facade, and either add bounded evidence for it in §13 or except it explicitly with the reason. (The correction is specification text and evidence, not a design change; no migration_backfill.rs edit is implied by this finding.)

---

Non-blocking observations

1. §16 understates the workflow trigger. .github/workflows/docker_build_and_push_to_dockerhub.yml gates the publishing job on always() && !cancelled() && (needs.classify.result != 'success' || needs.classify.outputs.run_docker == 'true') - it also publishes when the classifier job fails, not only "when its classifier selects the Docker path". The operative conclusion and the required authorization acknowledgement are correct; make the acknowledgement unconditional.
2. §6's thoth-app compatibility wording is true of rendering but understates two live effects (verified at thoth-app@origin/main): the editor seeds its draft from the actual assignment set (src/widgets/PublisherAdministration/usePublisherAdministrationEditor.ts:151) and submits that draft (:238), while the checkbox rows come from the option list (src/widgets/PublisherAdministration/usePublisherAdministration.ts:97,105) - so a publisher holding a hidden-but-enabled retired platform cannot be edited or corrected through the UI at all; and platformFilterOptions (usePublisherAdministration.ts:167-169) drops the retired platforms, removing the app-side filter staff would use to find publishers needing reconciliation. Both are neutralised by §17's ordering and by publishersByDistributionPlatform, which §7 invariant 7 preserves - but state them, rather than "REMAINS SOURCE-COMPATIBLE" alone.
3. §13 wording. "the only SDL change is the approved option-field description wording" - the §8.4 change is to the distributionPlatformOptions query field description (thoth-api/src/graphql/query.rs:619), not to a field of DistributionPlatformOption. Align the acceptance wording.
4. §14 validation prerequisite. cargo test --workspace requires a live local PostgreSQL: thoth-api/src/model/tests.rs:125 setup_test_db() calls reset_db(), which TRUNCATEs a real database. §9/§14 are correct that no production database access is needed; AGENTS.md:266 already directs local PostgreSQL/Redis use. One line in §14 would close the gap.
5. §21 report location vs §11. The canonical implementation-report structure is required, but New files: NONE forecloses the customary location - every comparable recent task committed one under docs/engineering/ai-delivery/implementation-reports/ (e.g. CTRL-BRANCH-NAMESPACE-01, commit 6acbf2fe). State explicitly whether BE-05's report is a repository file or GitHub-only evidence.

---

Verified as specified (source-backed)

Against the handoff's eleven required checks, at a6c8cb20:

1. 17 identities retained, no migration/schema change - DistributionPlatform::ALL (publisher_distribution_platform/mod.rs:451-469) holds exactly 17 values; every db_rename label is unchanged and the PostgreSQL labels come from the untouched thoth-api/migrations/20260811_v1.7.0/up.sql. CUL/Figshare can be retained without renaming, renumbering or migrating. ✅
2. Visibility as a policy distinct from readiness and assignability - AssignmentAvailability and MechanismReadiness already exist as internal, deliberately non-GraphQL vocabularies (mod.rs:186-206); adding a third is idiomatic here, and JISC_NBK is the live precedent for inactive + non-assignable + still projected. ✅
3. 15-row projection omitting only CUL and Figshare, canonical order preserved - DistributionPlatformOption::all() (mod.rs:543-549) maps over ALL, so a descriptor filter preserves canonical relative order; the two omissions are indices 4 and 6, leaving 15. ✅
4. GraphQL limited to response membership plus a description - the only description at issue is query.rs:619. There is no pinned SDL artefact in-repo and no full-SDL snapshot test: the guards are structural (graphql/sdl_support.rs; graphql/distribution_platform_tests.rs:426-475 asserts field signature, single declarations and enum membership). No executable enum/field/type/nullability change is implied. ✅
5. Canonical rejection derived from is_assignable(), atomic for mixed sets - publisher_distribution_platform/crud.rs:94 (pool wrapper, before a connection is acquired) and :129 (connection-scoped enable_on, independently of the caller); publisher_service_configuration/crud.rs:118-127 validates the whole normalized desired set at step 7, after staleness and before the first lifecycle call, so a mixed valid+retired set writes nothing. ✅
6. Retired identities remain usable for disable/history/reverse-read - disable/disable_on carry no assignability check; disabled rows are retained, never deleted; publishersByDistributionPlatform / publisherCountByDistributionPlatform still accept both enum values (and distribution_platform_tests.rs:341 already exercises FIGSHARE on that path). ✅
7. No migration, schema.rs, auth, package/capability or job-state-machine change implied - every non-doc source reference to the two platforms lives inside the §11 budget (mod.rs, publisher_distribution_platform/tests.rs, graphql/distribution_platform_tests.rs) plus the untouched migration SQL. No test outside the budget asserts a 17-row option list, the current description, or CUL/Figshare assignability (graphql/service_configuration_tests.rs:750 uses JISC_NBK only and stays green). ✅
8. Write budget / test-first plan - the code, test and CHANGELOG budget is sufficient and the test-first sequence is coherent; the documentation budget is not - see F1 and observation 5. ⚠️
9. Automatic GHCR publication on PR - confirmed verbatim: on: pull_request, GHCR login, push: true, tags: type=ref,event=pr,prefix=staging-pr-. §15 correctly makes PR mutation conditional on an implementation authorization that acknowledges it. ✅ (see observation 1)
10. Cross-repository ordering is safe - thoth-dissemination pins the 17-value contract and fails closed on a missing platform (publisher_source.py DESTINATIONS, validate_platform_options, issue code platform_option_missing_platform). That is exactly why BE-05 source merge is separable from backend activation, and why §6's order and §18's stop condition ("DIS-03 executable retirement is not production-effective") are load-bearing. Both are present and correct. ✅
11. Rollout/rollback/HOLD - §17's core premise is sound and matches the code: a complete-set replacement retaining an enabled retired value fails until removed, while removal itself remains possible because the desired set excludes it and the disable path is unguarded. Production reconciliation before activation is correctly a separate gate. Incomplete on the MIG-01 obligation - see F2 - and understated on the app side - see observation 2. ⚠️

---

Disposition

CHANGES REQUIRED. The behavioural design is sound: it is implementable exactly as described in §8, it does not break the executable GraphQL contract, it needs no migration/schema/auth/job-state change, it preserves history and reverse-reads, and its cross-repository ordering is correct against live downstream source. What blocks approval is not the mechanism but the specification's authority path (F1) and one falsified completeness claim with live production-verification consequences (F2).

Re-review after amendment should be bounded to: §3, §6, §7 invariant 5, §10, §11, §13, §14, §16, §21.

This decision is specification review evidence only. It does not authorize source edits, branch creation, commit, push, PR mutation, GHCR publication, production/provider/data access, migration execution, merge, release, deployment or activation. CTO specification approval and a later fresh exact-base implementation authorization remain required.

[ja573]

BE-05 SPECIFICATION AMENDMENT AFTER INDEPENDENT REVIEW - CHANGES REQUIRED ACCEPTED

Decision type: CONTROL SPECIFICATION AMENDMENT - NOT APPROVAL AND NOT IMPLEMENTATION AUTHORIZATION.

Independent review 5441494405 returned CHANGES REQUIRED against exact baseline develop @ a6c8cb2016179db635c4bc86ef366aae190829c2. The two blocking findings have been independently rechecked against live repository doctrine/source and are accepted.

A separate architecture task now exists:

• ADR-02 / ADR-02 - Supersede distribution platform inventory for Figshare/Cambridge retirement #842 - ADR-0010 - Distribution platform retirement
• baseline at creation: develop @ a6c8cb2016179db635c4bc86ef366aae190829c2
• status: specification/architecture decision candidate; implementation not authorized

This comment supersedes the following BE-05 body sections only: §3, §6, §7 invariant 5, §10, §11, §13, §14, §16 and §21. All other body sections remain current except where their sequencing text is necessarily prefixed by the ADR-0010 dependency below.

Current gate

CHANGES REQUIRED / HOLD - #842 ADR-02 must be independently reviewed, explicitly CTO-approved, faithfully recorded, exact-head reviewed and merged to develop as repository-authoritative ADR-0010 before BE-05 implementation may be authorized.

BE-05 implementation remains NOT AUTHORIZED.

Replacement for §3 - Background and authority

ADR-0004 remains the current repository-authoritative platform-inventory decision until a superseding ADR is approved and merged. Repository ADR doctrine prohibits BE-05 from materially rewriting ADR-0004 in place.

ADR-02 / #842 therefore owns the architecture transition to repository-wide ADR-0010. BE-05 must consume the exact merged ADR-0010 identity and may not implement against the candidate alone.

Runtime/source enforcement seams at the reviewed baseline are:

• thoth-api/src/model/publisher_distribution_platform/mod.rs - descriptor policy and visible option projection;
• thoth-api/src/model/publisher_distribution_platform/crud.rs - supported low-level enable rejection (read-only context);
• thoth-api/src/model/publisher_service_configuration/crud.rs - canonical complete-set coordinator validation (read-only context);
• thoth-api/src/model/publisher_service_configuration/migration_backfill.rs - additional is_assignable() consumer used by the closed MIG-01 administrative facade (read-only context; no edit implied);
• thoth-api/src/graphql/query.rs and focused tests.

Replacement additions for §6 - Impact and consumers

The source dependency order now begins:

ADR-02 / ADR-0010 approved + merged -> BE-05 source implementation/review/merge -> DIS-03 pins exact merged BE-05 contract -> DIS-03 source review/merge -> separately authorized dissemination runtime retirement -> production assignment/job audit and reconciliation -> BE-05 backend production activation -> APP-04 integration verification.

Known direct/operational consumers include:

1. thoth-dissemination - requires DIS-03 contract update after exact BE-05 merge.
2. thoth-app - executable-schema/source compatible, but with an important rollout constraint: while a publisher still holds an enabled platform omitted from backend option metadata, the generic complete-set editor retains that server value in draft state and cannot use the omitted option as a normal selectable correction path; the app-side platform filter also no longer exposes omitted retired options. Therefore upstream assignment reconciliation is a pre-activation requirement, not a client denylist problem. APP-04 remains zero-source-change unless later integration evidence proves a generic defect.
3. MIG-01 administrative facade - migration_backfill.rs separately calls DistributionPlatform::is_assignable() and maps failure to MigrationBackfillManifestInvalid at whole-manifest planning granularity.

MIG-01 is CLOSED. Its 2026-08-25 production execution/reconciliation evidence remains authoritative historical evidence. After BE-05 changes the predicate for CUL/Figshare, replay of a historical manifest containing either value may fail closed and is not guaranteed to reproduce the earlier facade result. Such a replay is fresh controlled work, not a continuation implicitly authorized by the closed MIG-01 task.

Replacement for §7 invariant 5

Replace invariant 5 with:

DistributionPlatform::is_assignable() remains the shared policy predicate consumed by supported assignment paths. Normal lifecycle/configuration APIs continue to reject non-assignable platforms with DistributionPlatformNotAssignable; the closed MIG-01 facade has its own fail-closed MigrationBackfillManifestInvalid classification at whole-manifest planning granularity. BE-05 must not add a new retirement-specific assignment predicate or validator.

All other invariants remain unchanged.

Replacement for §10 - Documentation authority

BE-05 no longer owns the material architecture-document rewrite.

ADR-02 / #842 owns:

• new ADR-0010;
• minimum ADR-0004 supersession metadata;
• decision-register.md current/superseded state;
• the current docs/publisher-services/platform-inventory.md retirement semantics.

BE-05 must begin source implementation only after the exact approved ADR-0010 source is merged to develop and recorded as its architecture dependency. BE-05 must not edit ADR-0004, decision-register.md or the platform inventory.

Replacement for §11 - BE-05 candidate write budget

Existing files permitted:

• thoth-api/src/model/publisher_distribution_platform/mod.rs
• thoth-api/src/model/publisher_distribution_platform/tests.rs
• thoth-api/src/model/publisher_service_configuration/tests.rs
• thoth-api/src/graphql/distribution_platform_tests.rs
• thoth-api/src/graphql/query.rs - description-only change for the distributionPlatformOptions query field
• CHANGELOG.md

New files: NONE.

Deletion/move/rename: NONE.

docs/engineering/decisions/ADR-0004-distribution-platform-inventory.md, docs/engineering/decisions/decision-register.md and docs/publisher-services/platform-inventory.md are now explicitly outside BE-05 and owned by #842.

migration_backfill.rs remains read-only context and is not added to the write budget.

Replacement additions for §13 - Acceptance/evidence

Keep the existing runtime acceptance tests, with these corrections/additions:

• wording is GraphQL query-field description, not option-field description;
• source review must record the unchanged MIG-01 facade behavior: it still calls is_assignable() and will fail closed as MigrationBackfillManifestInvalid for a manifest requesting a newly non-assignable destination;
• no MIG-01 source/test mutation or historical production-manifest rerun is required by BE-05; any such replay would be separate controlled work;
• exact merged ADR-0010 identity must be recorded in BE-05 implementation evidence;
• changed files must be a subset of the revised six-file budget above.

Replacement addition for §14 - Validation prerequisite

cargo test --workspace is expected to use the repository's disposable/local PostgreSQL test setup and performs database reset/truncation in that non-production test database. The implementation handoff must require the repository-standard local test database prerequisites and must not point tests at shared/production state.

No production API/database/provider access is needed for BE-05 source validation.

Replacement for §16 - Automatic side effect wording

Opening/updating a Thoth PR must be treated as carrying an unconditional possibility of automatic staging-pr-* GHCR publication. The Docker workflow can publish not only when classification explicitly selects Docker work but also on classifier failure under its always() && !cancelled() condition.

Therefore any later BE-05 authorization permitting PR mutation must explicitly accept that automatic external publication possibility. Without that authorization, STOP before PR mutation.

Replacement for §21 - Implementation report location

BE-05 implementation evidence is GitHub issue/PR ledger evidence, using the canonical report fields: exact base/head, commits, files changed, deviations, migration/data/auth effects, validation commands/results, CI/PR state, automatic external effects, and remaining gates.

No repository implementation-report file is authorized by the revised six-file BE-05 budget. If a repository report file later becomes required, return HOLD and amend/re-review the write budget before creating it.

Re-review scope

The independent reviewer who issued 5441494405 bounded re-review to the amended sections. That bounded re-review should occur only after #842's architecture decision is stable enough that BE-05 is not reviewing against a moving architectural premise; at minimum, #842 must first receive its own independent specification/decision outcome.

No source, branch, PR, CI, provider/runtime/database, production, merge, release, deployment or activation action is authorized by this amendment.