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

id	type	title	domain	repo	status	owner	topic_slug	priority	created	updated	related	state_hub_workstream_id
ACTIVITY-WP-0038	workplan	Carry repository grants and reconcile terminal queue closes	infotech	activity-core	finished	codex	activity-core	high	2026-09-04	2026-09-04	ACT-ADR-005 ACT-ADR-006 ACTIVITY-WP-0032 ACTIVITY-WP-0036 REINAH-WP-0003	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

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

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

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

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.