AUTH-09E: admit fixed services at runtime

[Abiorh001]

WS-AUTH-001-09E PR Trust Bundle

Goal

Admit only explicitly provisioned fixed service actors into central AUTH while
keeping every feature action unavailable and every human authority path
separate.

Changes And Design

• Introduces structurally distinct human and service authorization contexts.
• Resolves service tokens through the existing exact actor lookup with no first
  access, human rate control, role grant, or fallback path.
• Dispatches services before human/admin evaluation, checks exact ActionId
  matrix membership before availability, and revalidates locked actor rows in
  the caller transaction.
• Stages timestamps only for initially active service rows and rolls them back
  on denial, cancellation, or persistence failure.
• Adds focused unit, PostgreSQL, and real HTTP lifecycle/drift proof plus current
  specification and operations guidance.

Scope Control

No service feature action, ART/REV/CON call site, migration, schema, role,
grant, payment, review, revision, or reputation behavior is activated. ART PR
#154 and its owned 0028_artifact_admission are already merged; AUTH-09E adds
or allocates no migration.

Proof And CI Integrity

• 312 focused actor/auth/API-control tests passed on isolated PostgreSQL.
• 10 repair tests passed for inactive observation suppression and real
  revalidation drift.
• Real isolated API contract E2E passed.
• Ruff, 90.3 percent docstring coverage, stale scans, Markdown links, diff
  integrity, and 88 agent gates passed.
• No tests, assertions, skips, xfails, workflows, exclusions, or coverage
  thresholds were weakened.
• GitHub Backend remains the authoritative mandatory proof for the full 78
  percent repository floor and actor/authorization 90 percent subsystem gates.

Internal Review

Candidate 881ac7fc and docs repair d859af3d, against trusted main
8d5eb15b, pass senior engineering, QA/test, security/auth, product/ops,
architecture, CI integrity, docs, reuse/dedup, and test-delta review after all
valid findings were repaired. Integrated candidate 98376fd1, against trusted
main 44f2467c, passes the same nine tracks after repairing ART admission's
stale exact-type check for the new closed human/service context union.

External Review

CodeRabbit raised one wording issue and one post-lock human-kind drift issue.
Both are repaired: the specification wording is clear, and human administrative
revalidation now denies actor-kind drift before context reconstruction or grant
lookup. The focused repair suite passes 11 tests; fresh external and hosted CI
checks remain required on the repair head.

Remaining Risk And Follow-up

Hosted Backend CI and external review remain. The same-initiative
WS-AUTH-001-ART-CUSTODY successor is only a recorded next gate; it must not
start until this PR and signed memory are complete, its own contract
prerequisites pass, and the user explicitly starts it.

Human Review Focus

Review service-before-human dispatch, exact matrix-before-availability order,
active-only observation staging, lock-time drift denial, bounded evidence, and
the absence of feature activation or migration changes.

Human Merge Ownership

The agent may publish and repair this branch but may not merge it. Only the
human may approve this PR for merge. Trusted-main automation owns post-merge
schema-v2 memory generation when the workflow succeeds.

[coderabbitai]

📝 Walkthrough

Walkthrough

This change introduces strict human/service authorization contexts, fixed-service actor resolution and revalidation, lifecycle and drift denial coverage, service-token API contract checks, and updated AUTH-09E/ART-02C1 workstream records.

Changes

Authorization service admission

Layer / File(s)	Summary
Typed authorization contract backend/app/modules/authorization/runtime.py, backend/app/modules/authorization/kernel.py, backend/app/modules/artifacts/service.py, docs/*authorization_service.md, .agent-loop/.../WS-AUTH-001-09E-fixed-service-runtime-admission.md	Authorization contexts are split into strict human and service variants, with service identity, matrix, availability, revalidation, rollback, and scope rules documented and enforced.
Service resolution and kernel dispatch backend/app/modules/actors/service.py, backend/app/api/deps/authorization.py, backend/app/modules/authorization/kernel.py	Provisioned service actors are resolved and locked through dedicated methods, then evaluated by service-first authorization dispatch with transaction-local revalidation.
Contract, lifecycle, and drift validation backend/tests/*, backend/scripts/api_contract_e2e.py, scripts/test_agent_gates.py	Tests and API drills cover typed contexts, service provisioning, lifecycle denial codes, observation rollback, exact action selection, drift rejection, and updated trusted-state assertions.
Review evidence and merge intent .agent-loop/REVIEW_LOG.md, .agent-loop/.../reviews/*, .agent-loop/merge-intents/WS-AUTH-001-09E.json	Review outcomes, evidence provenance, scope constraints, remaining gates, and successor-chunk metadata are recorded for AUTH-09E.
Workstream state synchronization .agent-loop/LOOP_STATE.md, .agent-loop/WORK_QUEUE.md, .agent-loop/initiatives/.../STATUS.md, .agent-loop/initiatives/.../CHUNK_MAP.md	Workstream records mark AUTH-09E active and ART-02C1 merged, while preserving the restriction that feature actions remain unavailable.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant ServiceToken
  participant AuthorizationDependency
  participant ActorService
  participant AuthorizationKernel
  participant API
  ServiceToken->>AuthorizationDependency: authenticated service subject
  AuthorizationDependency->>ActorService: resolve_service_for_authorization
  ActorService-->>AuthorizationDependency: typed service actor context
  AuthorizationDependency->>AuthorizationKernel: require service action
  AuthorizationKernel->>ActorService: lock and revalidate service state
  ActorService-->>AuthorizationKernel: refreshed context or denial
  AuthorizationKernel-->>API: admission result and denial code

Loading

Possibly related PRs

• Flow-Research/workstream#74: Establishes actor identity/profile registry foundations used by the service-resolution changes.
• Flow-Research/workstream#143: Introduces service-actor provisioning and identity-link foundations extended by this authorization path.
• Flow-Research/workstream#145: Touches the agent-gate assertions updated by this change.

Suggested reviewers: abiorh-claw

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 30.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title is concise and accurately captures the main change: fixed-service runtime admission for AUTH-09E.
Description check	✅ Passed	It covers the goal, changes, scope, proof, review, risks, and ownership, matching the template’s main required content.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/ws-auth-001-09e-fixed-service-runtime-admission

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

backend/app/modules/authorization/kernel.py (1)

252-260: 🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win

Unguarded reconstruction of HumanAuthorizationContext after lock.

HumanAuthorizationContext.actor_kind is Literal[ActorKind.HUMAN]. If the freshly locked profile.actor_kind ever differs from "human" (concurrent drift on the same row between initial context resolution and this lock), ActorKind(profile.actor_kind) converts fine but the constructor call raises an unguarded pydantic.ValidationError — not caught here or in require(), surfacing as an unstructured 500 instead of a bounded denial code.

Contrast with the analogous fixed-service path (revalidate_service in backend/app/api/deps/authorization.py), which rebuilds context via _authorization_context and explicitly checks isinstance(refreshed, ServiceAuthorizationContext) before trusting it, falling back to None (a graceful PERMISSION_NOT_GRANTED denial) on mismatch rather than crashing.

🛡️ Proposed defensive guard

             link, profile = locked
+            if profile.actor_kind != "human":
+                return AuthorizationDenialCode.IDENTITY_LINK_REVOKED, context, None, None, True
             context = HumanAuthorizationContext(
                 actor_profile_id=UUID(profile.id),
                 actor_kind=ActorKind(profile.actor_kind),

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@backend/app/modules/authorization/kernel.py` around lines 252 - 260, Guard
the post-lock reconstruction in the human authorization revalidation flow
instead of constructing HumanAuthorizationContext unconditionally. Reuse the
existing context-building/validation path, verify the refreshed result is a
HumanAuthorizationContext (including the HUMAN actor_kind constraint), and
return None or the established denial path on mismatch so require() produces
PERMISSION_NOT_GRANTED rather than an uncaught ValidationError.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/spec_authorization_service.md`:
- Around line 504-507: Revise the wording in the authorization context
description to remove the awkward “required closed” modifier combination, while
preserving that only the service variant includes a required, closed
service_identity.

---

Outside diff comments:
In `@backend/app/modules/authorization/kernel.py`:
- Around line 252-260: Guard the post-lock reconstruction in the human
authorization revalidation flow instead of constructing
HumanAuthorizationContext unconditionally. Reuse the existing
context-building/validation path, verify the refreshed result is a
HumanAuthorizationContext (including the HUMAN actor_kind constraint), and
return None or the established denial path on mismatch so require() produces
PERMISSION_NOT_GRANTED rather than an uncaught ValidationError.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 40ee705a-1cb7-4829-8da8-56ec0a786a72

📥 Commits

Reviewing files that changed from the base of the PR and between cb9d5f9 and 4fd3537.

📒 Files selected for processing (23)

• .agent-loop/LOOP_STATE.md
• .agent-loop/REVIEW_LOG.md
• .agent-loop/WORK_QUEUE.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/CHUNK_MAP.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/STATUS.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-09E-fixed-service-runtime-admission.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/chunks/WS-AUTH-001-ART-CUSTODY-activation-custody-transfer.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-09E-internal-review-evidence.md
• .agent-loop/initiatives/WS-AUTH-001-workstream-authorization-service/reviews/WS-AUTH-001-09E-pr-trust-bundle.md
• .agent-loop/merge-intents/WS-AUTH-001-09E.json
• backend/app/api/deps/authorization.py
• backend/app/modules/actors/service.py
• backend/app/modules/artifacts/service.py
• backend/app/modules/authorization/kernel.py
• backend/app/modules/authorization/runtime.py
• backend/scripts/api_contract_e2e.py
• backend/tests/test_actors.py
• backend/tests/test_artifact_admission.py
• backend/tests/test_auth.py
• backend/tests/test_authorization.py
• docs/operations_authorization_service.md
• docs/spec_authorization_service.md
• scripts/test_agent_gates.py

[Abiorh001]

Addressed all actionable CodeRabbit findings in d5162ce:

• Corrected the specification wording from “required closed” to “required, closed”.
• Hardened serialized human-admin revalidation so actor-kind drift is denied as permission_not_granted before rebuilding the human context or querying grants.
• Added a regression test proving the drift denial is sensitive, revalidated, and performs no grant lookup.

Validation: Ruff passes; 11 focused authorization tests pass; all nine required internal reviewer tracks pass. Full repository tests and coverage are running in GitHub Actions.