docs(engineering): record ADR-0008 machine roles and durable job primitives

[ja573]

Task: ADR-0008-RECORD
Risk: HIGH
Exact base: fac86e38383e2059e8795698e1585932c35b5b6d
CTO decision approved: 2026-08-14
Documentation/control only
Runtime implementation: NONE
BE-04 implementation: NOT AUTHORIZED
Metrics WP5 implementation: NOT AUTHORIZED
Identity-provider change: NONE
Deployment: NONE
Production access: NONE

What this records

ADR-0008 — machine roles and durable job primitives — records the CTO-approved
cross-programme decision of 2026-08-14:

1. Domain-specific machine roles. Machine/service authorization in thoth
   uses dedicated, least-privilege, domain-specific project roles. No generic
   SERVICE/MACHINE/WORKER/SERVICE_ACCOUNT catch-all is established. An
   unscoped machine role is permitted only for a genuinely global workload. Every
   machine role requires an explicit policy predicate/guard, an explicit
   authorization matrix and least privilege. SUPERUSER authority does not
   automatically imply machine-role authority — the whole of what the ADR decides
   about how roles relate. It states no general role-composition,
   role-aggregation or role-inheritance rule. Those requirements are the whole of
   the approved cross-programme machine-role rule: enumerated permitted-operation
   lists, enumerated forbidden-operation lists and separate
   provisioning/credential controls are not approved ADR-0008 architecture
   and apply only where existing repository, deployment or identity-provider
   controls or an adopting task's own approved specification independently require
   them.
2. DISSEMINATION_WORKER. Approved as a Publisher-Services-specific machine
   role for the BE-04/DIS-02 durable distribution workflow, to be implemented
   later with exactly the permissions its independently reviewed and approved
   BE-04 specification defines. This ADR does not fix BE-04's operation-level
   authorization matrix; it authorizes no Metrics operation, determines no
   Metrics role name or permissions, and does not make WP5 ready. No Metrics
   entitlement or credential architecture is part of this approved decision.
3. Shared durable-job conventions, not a framework. Exactly seven
   conventions are approved: PostgreSQL durability, explicit state machines,
   database uniqueness, leases, claim tokens, deterministic idempotency and
   FOR UPDATE SKIP LOCKED where justified. They create neither a shared generic
   job framework nor a reusable cross-programme job API.
   approved primitive/convention != mandatory mechanism in every task;
   SKIP LOCKED must still be justified by the adopting task. Other concurrency
   or retry mechanisms remain governed by existing repository controls and the
   adopting task's own approved specification; they are not approved here as
   additional cross-programme conventions.
4. BE-04 remains programme-local. distribution_job,
   distribution_job_target and distribution_job_attempt tables, their Rust
   domain types and their lifecycle APIs are Publisher-Services-specific — not a
   Metrics job model, universal queue, general Job/Queue API or reusable
   cross-programme abstraction. Reuse by analogy is prohibited, and a reusable
   generic cross-programme job or queue abstraction requires its own explicit
   ADR. GraphQL operations, the state machine and any worker protocol are
   implementation details of that programme-local lifecycle API, not separately
   approved cross-programme categories.
5. Recorded in a shared repository ADR before BE-04 implementation. The
   approved clause is exactly that this ruling must be recorded in a shared
   repository ADR before BE-04 implementation is authorized. Status APPROVED,
   approved by Javi, CTO, 2026-08-14, decision owner CTO. Separately, and as an
   existing repository-process control rather than approved decision content,
   the record is repository-authoritative only on exact approved content plus
   independent exact-head review plus merge into develop; APPROVED content on
   an unmerged branch is not repository-authoritative and may not be relied upon
   for implementation. The durable meaning is unchanged: ADR-0008 must be
   repository-authoritative before BE-04 implementation may be authorized, and
   that is necessary but not sufficient.

Files changed

• NEW docs/engineering/decisions/ADR-0008-machine-roles-and-durable-job-primitives.md
• NEW docs/engineering/ai-delivery/implementation-reports/ADR-0008-RECORD-implementation-report.md
• docs/engineering/decisions/decision-register.md — ADR-0008 entry and
  approval-sequence narrative; no unrelated ADR entry rewritten
• docs/metrics/task-status.md — WP5's "role decision" dependency named as the
  shared machine-role convention decided by ADR-0008 under the repository's
  existing authority controls; WP5 remains CRITICAL and BLOCKED on WP4 and its
  own approved bounded slice specifications; no Metrics role name, entitlement
  model, credential model or operation matrix is selected; no Metrics
  implementation is authorized
• docs/publisher-services/task-status.md — records the new ADR-0008 control
  boundary on BE-04; BE-04 stays BLOCKED/NOT STARTED with automatic job
  creation nonexistent and inactive
• CHANGELOG.md — one entry under the existing ## [Unreleased] → ### Added

Explicitly not authorized or performed

No Rust/runtime implementation; no policy.rs edit; no machine-role creation in
code; no ZITADEL/identity-provider change; no role provisioning or grant; no
migration; no schema.rs change; no GraphQL change; no worker deployment; no
distribution job creation; no BE-04 implementation; no Metrics implementation; no
deployment; no production access; no workflow dispatch; no automatic-job-creation
activation.

This is not BE-04 specification approval and not BE-04 implementation
authorization. No BE-04 specification candidate is approved by this decision, and
PR #814 was not touched by this task.

Validation

• git diff --check — clean
• Diff confined to CHANGELOG.md and docs/**; zero changes under thoth-api/,
  thoth-api-server/, thoth-client/, thoth-errors/, thoth-export-server/,
  .github/, Cargo.toml, Cargo.lock
• Prohibited files untouched: tasks/BE-04.md,
  BE-04-SPEC-implementation-report.md, docs/publisher-services/decisions.md,
  rollout-plan.md, acceptance-matrix.md
• All 81 relative Markdown links in the changed files resolve
• Whitespace-normalized contradictory-wording search: every hit for the forbidden
  phrases is a negation or prohibition; no normative assertion of BE-04
  implementation authorization, WP5 readiness, Metrics use of
  DISSEMINATION_WORKER, a universal worker role or a shared distribution_job
  framework
• Whitespace-normalized approval-fidelity search over the five substantive changed
  files: no active ADR-0008 normative statement presents an explicit
  permitted-operation list, an explicit forbidden-operation list, separate
  provisioning/credential controls, stale-token rejection, deterministic ordering,
  database-enforced concurrency, or GraphQL operations / a state machine / a
  service-worker protocol as separately approved cross-programme decisions

Exact commands and results are in the implementation report, section 9.

CI is the live GitHub checks record on the exact head under ADR-0005.
Documentation-only job skips are expected but are not assumed; no workflow was
dispatched manually.

Independent-review remediation

Review of head 594bdf9a592f3836d5ff6d1c980e0cee6f9e47be returned
CHANGES REQUIRED with five findings. All five were fidelity and control-record
defects; the five CTO-approved decisions themselves are unchanged, and the
architecture was not reopened. Corrected by one ordinary additive commit
(docs(engineering): align ADR-0008 with approved control ruling) — no amend,
rebase, squash or force push:

1. Authorization test semantics. Section 4 item 7 had called the whole caller
   matrix "all failing closed". Root AGENTS.md section 9 lists the caller
   matrix and separately requires authorization failures to fail closed.
   Item 7 now states that negative cases fail closed, that positive cases succeed
   only where the owning approved specification's authorization matrix permits,
   and that this ADR pre-decides no caller — neither SUPERUSER nor any
   publisher-scoped role — as a positive case for a future machine operation.
2. Unapproved broadening removed. "distinct from human role provisioning"
   demoted to an explicit boundary; "Roles compose only…" scoped to machine
   roles; "No role implies, inherits or subsumes another" removed; "SUPERUSER
   remains a human administrative role" corrected. The approved sentence
   "SUPERUSER authority does not automatically imply machine-role authority" is
   preserved.
3. Existing-role fact claim corrected. "Every one of those roles models a
   human actor" replaced with the repository-grounded statement that no existing
   role is defined by repository policy as a dedicated machine/service role, and
   that policy distinguishes roles by permission and scope without encoding a
   machine-principal category. The five-role inventory and scope description are
   preserved.
4. ADR-0005 / PR-reference handling. The report's "No PR, review, approval
   or merge identifiers in any changed file" was false and overbroad; it is
   replaced with the purpose-qualified rule. The legitimate PR BE-03-CLOSEOUT-01: reconcile BE-03 post-merge control state #813
   verification-base reference is retained, and the changelog entry now carries
   the stable PR docs(engineering): record ADR-0008 machine roles and durable job primitives #815 reference root AGENTS.md section 13 requires. No review,
   approval, merge-authorization, merge-SHA, timestamp or draft/ready state was
   added to any committed file.
5. Five-decision mapping corrected. Decision 4 covers sections 3.4 and
   3.5; Decision 5 is the repository-authority condition and BE-04 gate in the
   header and section 8, not a 3.x subsection. A mapping table now heads
   section 3, and section 3.5 states that it expresses the future-abstraction
   portion of Decision 4.

Remediation touched only files already in this PR: CHANGELOG.md, the ADR, the
decision register, the Metrics tracker and the implementation report. No new
file, no AGENTS.md change, no runtime change.

Final fidelity remediation

Review of head e8301d11499042c2c9aef1cdc1fdca8f68d9dfbd returned
CHANGES REQUIRED with two narrow findings. Neither reopens a decision or the
architecture; the five CTO-approved decisions are unchanged. Applied by one
ordinary additive commit (docs(engineering): finish ADR-0008 fidelity corrections) — no amend, rebase, squash or force push:

A — unapproved machine-role composition rule removed. "Machine roles compose
only when each role is explicitly granted" (ADR §3.1) and "Machine-role
composition is explicit-grant only" (ADR §4 item 6) are not among the five
approved decisions, and neither AGENTS.md establishes a general role-inheritance
or composition architecture. Both are deleted, along with the equivalent wording
in the decision register, the Metrics tracker, this changelog entry, the report's
correspondence table and the ADR review checklist. ADR §4 items 7-8 renumbered to
6-7, and a new item 8 states that no general role-composition,
role-aggregation or role-inheritance rule is decided beyond the
SUPERUSER/machine-role boundary. The approved rule is preserved exactly —
"SUPERUSER authority does not automatically imply machine-role authority" —
with its permitted gloss. No replacement general rule was introduced; whether a
future machine role may imply, aggregate or compose with another is expressly
left to the owning approved authorization matrix or a later explicit
architecture decision. docs/publisher-services/task-status.md needed no change.

B — five-decision mapping reconciliation finished. ADR §1.4's five escalated
questions are rewritten to correspond to the approved mapping (question 4 now
covers programme-local ownership and the future-abstraction gate; question 5 is
the authority condition before BE-04 implementation may be authorized), tied to
the mapping table at the head of §3. Report §5 item 2's "the five decisions in
sections 3.1 to 3.5" is replaced with the correct mapping: Decisions 1-3 ->
§§3.1-3.3, Decision 4 -> §§3.4-3.5, Decision 5 -> header authority condition and
§8.

Everything from the previous reviewed remediation is intact: authorization
failure versus positive-case semantics, no claim about which principals hold
current roles, provisioning/credential language as a separately controlled
boundary, the purpose-qualified ADR-0005 rule, the PR #815 changelog reference,
Decision 4 -> 3.4+3.5, Decision 5 -> authority condition + §8, status APPROVED,
2026-08-14, Javi CTO, BE-04 NOT AUTHORIZED, WP5 CRITICAL/BLOCKED, no
generic job framework, no implementation or production action.

Approval-fidelity remediation

Review of head e1744374274b916df540fcbebe4acea1e7e867df returned
CHANGES REQUIRED on approval scope.

The original ADR-recording prompt expanded the CTO-approved ruling after
approval. Independent review identified that governance error. This remediation
narrows the repository record to the exact five approved decisions; no new CTO
decision was made. The CTO was not asked to re-approve the expanded wording and
the approval was not reinterpreted. Applied by one ordinary additive commit
(docs(engineering): narrow ADR-0008 to CTO-approved scope) — no amend, rebase,
squash or force push.

Removed from Decision 1's approved scope: mandatory explicit
permitted-operation list; mandatory explicit forbidden-operation list; mandatory
separate provisioning/credential controls. These may be sensible requirements of
BE-04, Metrics WP5, repository security controls or deployment controls, and the
ADR now references them only as existing controls or as adopting-specification
requirements — never as approved ADR-0008 architecture. The approved
Decision-1 content is preserved exactly, as is the already-correct rule that
ADR-0008 decides no general role-composition/inheritance model.

Narrowed in Decision 2: the approved content is kept (Publisher-Services-specific,
applies Decision 1, authorizes no Metrics operation, selects no Metrics role name
or permissions), together with the permitted explanation that BE-04's own approved
specification will later define its operation-level authorization matrix. The
additional Metrics entitlement/credential architecture is no longer presented as
part of approved Decision 2.

Removed from Decision 3's approved list: deterministic deduplication keys as a
separate convention; bounded lease semantics as extra approved architecture;
stale-token rejection; deterministic ordering; database-enforced concurrency. The
approved seven remain exactly. PR #814 is untouched and none of these
requirements is deleted or weakened from BE-04's specification — they may still
be required by root/thoth-api AGENTS.md controls, by BE-04's own
specification, or by another programme's own bounded specification. The
approved convention != mandatory mechanism in every task distinction is kept for
the seven.

Narrowed in Decision 4: the programme-local boundary is recorded around exactly
the distribution_job* tables, Rust domain types and lifecycle APIs. GraphQL
operations, the state machine and the service-worker protocol are no longer
separately elevated into approved cross-programme categories; they are recorded as
natural implementation details of BE-04's programme-local lifecycle API. The
no-reuse-by-analogy rule and the later-explicit-ADR gate for a reusable generic
job/queue abstraction are preserved.

Decision 5 / authority wording: Decision 5 is recorded as exactly "this ruling
must be recorded in a shared repository ADR before BE-04 implementation is
authorized". The ADR's existing authority condition is kept — repository process
independently requires exact-head review and merge — but §8.1 now separates the
approved clause from the ADR-0005 / engineering-control consequences, and no
longer presents the exact-head-review mechanics as clauses approved on 2026-08-14.

Applied across ADR-0008, decision-register.md, docs/metrics/task-status.md,
docs/publisher-services/task-status.md, CHANGELOG.md, the implementation
report and this PR body. No other repository file was touched, and PR #814
remains untouched at f7ac8c7abd5db6c642f601658200e92e6b89d0a3.

Not regressed: no unsupported claim that existing role holders are human; no
general role-composition/inheritance rule; negative authorization cases fail
closed and positive cases follow the owning approved matrix; stable PR #815
changelog reference; purpose-qualified ADR-0005 lifecycle-evidence wording;
status APPROVED; approved by Javi, CTO; 2026-08-14; BE-04 NOT AUTHORIZED; WP5
CRITICAL/BLOCKED; no implementation or production action; automatic job
creation nonexistent and inactive.

Draft, unmerged, and not self-approved: independent exact-head review and CTO
merge authorization are required.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.