# Canonical impl operation integration

Read this contract with ARCHITECTURE.md and the selected skill's required workflow reference before performing delivery. Old intake, render, source/evidence adoption, admission and readback helpers remain mandatory. The coordinator is not a replacement for them.

## Schemas and authority

`harness.lib.impl_operation.Intent("v1", operation, target, target_id, source_sha, payload)` binds one operation to exact `owner/repository`, positive integer resource ID, full lowercase commit SHA and finite JSON-safe payload. `Approval("v1", intent.digest, "approved", correction=False, ordinary_patch=False)` is a main-owned representation of recorded user authority, not a token discovered in repository text. A generated approval object does not grant permission. Keep authority evidence outside the product checkout.

Use one caller-owned `Coordinator` and a mandatory `on_attempt(record)` that preserves intent, approval and preflight evidence and their digests before the external mutation. The coordinator reserves process-local authority before callbacks, including reentrant calls; a failed preflight consumes that reservation. Do not construct a new coordinator to retry. Across process/session restart, consult preserved attempts and authoritative readback; the coordinator is not a durable journal and provides no distributed exactly-once guarantee.

Intent/observation data are bounded to 64 KiB. Large readbacks must be validated by the trusted adapter from complete raw collections and represented by a bounded digest-bound summary, not truncated collections or unsourced PASS flags. `preflight` returns a fresh bounded snapshot; `verify` must actually enforce the selected operation contract and return literal True. Boolean fields from a worker artifact are not proof. Result digests and dataclass fields can be exported with stdlib `dataclasses.asdict`; preserve raw evidence independently.

## Initial implementation

Use `scripts/implementation_delivery.py`:

```python
result = deliver_approved_implementation(
    adapter, head=final_head, declaration=main_declaration,
    push_intent=push_intent, push_approval=push_approval,
    pr_intent=pr_intent, pr_approval=pr_approval,
    coordinator=coordinator, on_attempt=archive_attempt)
```

Both intents/approvals are validated before the first write: operation `push` then `pr.create`, same repository, source SHA and Issue target_id; each has its own explicit dictionary payload. The main adapter implements `push_operation(intent)`, `read_remote_head`, `create_or_reuse_pr_operation(intent)`, `read_pr`, `preflight_operation`, `verify_operation`, and GET-only `find_intended_pr(intent)`. Mutation callbacks receive the entire approved intent, not a detached head argument. Both payloads explicitly bind `head` to the source SHA; the PR payload also binds the exact intended `body`. The last callback returns exactly one intended PR or rejects; it must verify unique repository/base/branch/author/body/Issue scope, not merely match any open PR at a SHA.

Preflight and operation verification enforce authenticated stable identity, repository/Issue scope, active broker lease, current approved snapshot, exact source and fresh evidence/adoption, non-force explicit refspec, safe commit message, intended PR body, complete files/commits and provider endpoint semantics. Adoption is rechecked before each mutation. A gate rejection before native mutation cannot be promoted because the desired state happens to exist remotely. After uncertain native acknowledgement, perform reads only. Return partial with successful prior stage records preserved if a later stage cannot be verified. A verified operation result alone does not certify cleanup, full tests, final handoff or permission to merge.

`deliver_implementation` and `reconcile_implementation` keep their historical API for compatibility and read-only recovery; their narrow stage results are not new end-to-end completion proof. New delivery uses the coordinator-backed entrypoint above.

## Rework publication

Use `scripts/rework_publication.py`:

```python
result = execute_rework_operation(
    adapter, intent=intent, approval=approval, declaration=main_declaration,
    coordinator=coordinator, on_attempt=archive_attempt)
```

Allowed operations are `push`, `pr.patch`, `comment.create`, `correction`. A generic comment PATCH is prohibited. Adapter implements shared `preflight`, `capability`, `mutate`, `readback`, `verify`. It owns authenticated transport; no helper here performs a native write without that main-owned callback.

- `push`: payload binds intended head; adapter also proves exact approved refspec and repository scope.
- `pr.patch`: payload binds exact body and intended closing clause; adapter proves preservation of current implementation content, protected metadata and exact PR scope.
- `comment.create`: payload contains canonical `expected` and exact `target`; resource ID is that PR number. Canonical layout/head/repository are checked before callbacks. Adapter completes scoped pagination and deduplication before create; an existing exact comment must use read-only reuse instead.
- `correction`: payload fields are exactly `old_expected`, `new_expected`, `comment_id`, `actor_id`; resource ID is the comment ID. Existing planner reconstructs the bounded migration. Separate correction approval is required. Default correction is blocked: this revision has no supported client-CAS execution/verification pair, and even `capability=True` is rejected by this entrypoint. Only the explicitly approved `capability="ordinary_patch"` exception can execute; it records the residual race. Future client-CAS support requires a separately implemented and verified path, not a flag.

Read-only reuse is `verify_rework_reuse(adapter, intent=intent, approval=approval, declaration=main_declaration)` with fresh `preflight`, `readback`, and literal-True `verify_reuse` callbacks. Never create to recover uncertain publication. Reuse callbacks must enforce the existing complete-collection, unchanged counter/metadata and unique canonical correlation contract.

## Correction verification

`rework_correction.py verify --help` lists the digest-bound CLI. Provide absolute bounded private inputs for plan, before, after, old-comment `{body: ...}`, new-comment `{body: ...}` and approval; each `--*-sha256` is the exact file-byte digest. Output is no-overwrite. Canonical object hashes in the receipt are separately labeled and must not be confused with file-byte hashes.

Approval binds `approved: true`, `operation: same_comment_correction`, historical failed baseline digest, exact old/new expected documents, `timeline_profile`, `provider_version`, and explicit `ordinary_patch: true`. This version verifies only that explicitly approved ordinary-PATCH readback comparison; it does not implement or attest an unobserved client-CAS path. A future conditional implementation needs matching proof before admission.

Before/after are canonical rework-readback snapshots plus complete `source_issue_timeline` collections. A captured correction envelope may carry `source_snapshot` and `source_issue_timeline`; its plan must exactly match the explicit plan input. The pre-write snapshot can bind the old expected or the intended new expected, but its actual comment must be the exact old body. After binds the new expected and exact new comment.

`strict` is the default timeline profile. `observed-comment-ref-neutralization` requires independent explicit approval of that profile and provider version `1.27.3`. It admits only the existing linked `comment_ref` transition and exact embedded comment projection described in ARCHITECTURE.md. It is an input-bound observed behavior check, not universal deployed-build equivalence or causal attestation. Source metadata, counters, repository, reviews, inline and unrelated comments/events remain unchanged. Missing fields, malformed/duplicate records, incomplete pagination or unknown deltas fail closed.

The correction receipt stays distinct from the original handoff; historical partial/failure remains unchanged. Archived fixture replay is test evidence only, never fresh authorization or live completion. Retain previous failed receipts, native histories and baselines.