activity-core/workplans/ACTIVITY-WP-0038-repository-grant-close-reconciliation.md

---
id: ACTIVITY-WP-0038
type: workplan
title: "Carry repository grants and reconcile terminal queue closes"
domain: infotech
repo: activity-core
status: finished
owner: codex
topic_slug: activity-core
priority: high
created: "2026-09-04"
updated: "2026-09-04"
related:
  - ACT-ADR-005
  - ACT-ADR-006
  - ACTIVITY-WP-0032
  - ACTIVITY-WP-0036
  - REINAH-WP-0003
state_hub_workstream_id: "2438c30e-24c3-534e-a2b6-8f63a46d8244"
---

# Carry Repository Grants and Reconcile Terminal Queue Closes

## Origin

Rein-aharness enabled its versioned local repository-grant validator and durable
close outbox on 2026-09-04, then reported two Activity Core contract gaps:

1. queued/profiled work has no separately typed authoritative repository grant;
2. a response-lost terminal close retry receives the same undifferentiated 409
   as a wrong-owner, expired-lease, or conflicting-result mutation, while the
   result allowlist drops repository transaction and acceptance identity.

These are Activity Core responsibilities at the definition/emission and durable
queue boundaries. The grant must not be inferred from task prose, labels,
`execution_refs`, a profile, or repository defaults.

## Review and specify the cross-repository contract

```task
id: ACTIVITY-WP-0038-T01
status: done
priority: high
state_hub_task_id: "9d8f9752-6fe3-563c-8d7b-cc8a598920a9"
```

Review rein-aharness repository-grant v1, its close-outbox identity, and exact
ADR-002 revision `36e1096`. Define compatibility, rejection, evidence, and
repeat-close semantics before changing the queue.

Decision: preserve the four-field v1 grant unchanged in a dedicated JSON
column after strict structural and path-safety validation. A first accepted
terminal close returns `applied`; an identical repeat by the same claim owner
returns `reconciled`. Missing rows, wrong owners, expired leases, non-terminal
states, and different terminal intents receive distinct refusal codes. Legacy
grant-absent rows remain valid during migration.

## Carry the authoritative repository grant

```task
id: ACTIVITY-WP-0038-T02
status: done
priority: high
state_hub_task_id: "25c23d30-2868-588c-a64d-61fd2753f8d0"
```

Add a typed repository-grant v1 model to rule actions and instructions, reject
unsupported or unsafe grants during definition parsing and emission preflight,
and carry the exact field through `ops_runs` and claim/read projections. Add an
additive migration; do not place the grant in attribution-only
`execution_refs` or synthesize it from another field.

Completed 2026-09-04. `RepositoryGrant` and `CommitCount` enforce the exact v1
shape, strict scalar types, local-only publication, bounded commit counts, and
safe repository-relative patterns. Definition sync and complete-batch emission
preflight both reject invalid grants. Rule actions copy static grant data
without rendering it; instructions carry the typed payload. Migration `0010`
adds nullable `ops_runs.repository_grant`, and claim/read/run projections keep
it separate from `execution_refs`. Cross-implementation identity tests match
rein-aharness grant id `af2e7c8275c9ba8c8f78485067f9608e` and acceptance
policy id `2ed31282d721f4466bc9ea722067d9d0` for the shared fixture.

## Preserve evidence and reconcile terminal closes

```task
id: ACTIVITY-WP-0038-T03
status: done
priority: high
state_hub_task_id: "53c675f5-ae93-5896-b99b-32dda215733f"
```

Allowlist bounded repository transaction, grant, acceptance, and external
metrics identities in queue results. Persist a digest of the accepted terminal
close intent. Under the row lock, accept an identical repeat by the original
claim owner as reconciled without requiring a now-cleared lease, while refusing
different outcomes/actions/flags, wrong owners, expired active claims, and
unknown rows with distinct API codes. Reopened failures are not terminal and
must not be mistaken for reconciled delivery.

Completed 2026-09-04. The result allowlist now retains bounded
`repository_transaction` baseline, grant, acceptance, and external-metrics
evidence while dropping raw grant patterns and unknown blobs. Migration `0010`
adds `close_intent_digest`. The row-locked close decision returns `applied` for
the first accepted mutation and `reconciled` for an exact normalized terminal
repeat by the same owner. It reports distinct `not_found`, `wrong_owner`,
`expired_lease`, `state_conflict`, `evidence_conflict`, and
`terminal_conflict` refusals. Granted completion additionally proves that the
reported grant and acceptance-policy identities match the queued authority and
that acceptance is positive. Reopened failures clear close identity and remain
non-terminal.

## Verify and hand off

```task
id: ACTIVITY-WP-0038-T04
status: done
priority: high
state_hub_task_id: "d2f106f2-cc62-55d0-95a6-2e4eac3740ce"
```

Run focused and full tests, migration/static checks, update the queue contract,
sync State Hub, and return the exact revision/schema/repeat semantics to
rein-aharness. Production rollout and live outbox activation remain separate
until both repositories consume and deploy the reviewed contract.

Source verification 2026-09-04: 493 tests passed with one live integration test
skipped; critical Python lint, compilation, and whitespace checks passed.
Alembic reports one head (`0010`). A throwaway PostgreSQL 16 database passed
full upgrade, `0010` downgrade to `0009`, column-removal inspection, re-upgrade,
and type/nullability inspection; it was then removed. Remaining work is the
exact-revision State Hub handoff and consistency sync.

Handoff completed at source revision `b63131e`. Activity Core acknowledged
rein-aharness ADR-002 revision `36e1096` / SHA-256
`84b47d2e669949ab6d178a8e452712df197b852341682b175d831cf2c8bb206f`
in State Hub message `84748a7e-a0fd-4423-80e8-94d6e885f3fa`, and returned the
schema and repeat-close contract in message
`cc105786-7936-4a4d-836a-03b110566e98`. Decision
`5ca55e62-6747-48eb-9055-eb7d18ab1b4d` and progress event
`254d7df7-c046-44fd-95e3-cbf8681dc98e` retain the bounded closeout record.
The first two required `statehub fix-consistency` attempts timed out querying
the local API; retry after this final file update remains the only close gate.

Identity correction 2026-09-04: this unregistered workplan was renumbered from
`ACTIVITY-WP-0037` to `ACTIVITY-WP-0038`. The former ID was already immutably
assigned on 2026-08-26 to archived historical record `WP-0002` / State Hub
UUID `b221e65a-6f97-44b0-8dae-442fffcb7f64`.

The third attempt reached inbox-hygiene collection but remained blocked waiting
for the local State Hub messages endpoint for more than two minutes and was
interrupted. Direct message, decision, progress, and mark-read API writes all
succeeded. State Hub was asked to reconcile the file in message
`a96837e6-1c33-4d65-b07a-71dfa7f1b328`. T04 remains `wait` only for State Hub
registration/consistency; the implementation and rein-aharness handoff are
complete.

After the identity correction at commit `41a5815`, repo-manager reports no
remaining collisions. Its projection still refuses before assignment because
seven unrelated, already-registered historical `custodian-WP-*` records do not
match the current identifier grammar. Those immutable records were not renamed.
State Hub request `ff19e5fc-faee-4e63-ad30-6aeac437cd03` asks the registrar to
register this workplan and T01–T04 without rewriting the historical identities,
or return the approved grandfather mechanism.

Closed 2026-09-04. State Hub registered the corrected file binding from Forge
revision `87abeb4ce790d5d136fc28f62c62f7f4d864411c` as workplan UUID
`2438c30e-24c3-534e-a2b6-8f63a46d8244`, assigned deterministic UUIDs to all
four tasks, and confirmed source statuses `done/done/done/wait` without
touching unrelated historical records. This final source update records those
bindings and completes T04.