Define middleware and hook contracts for document execution and provider APIs #957

Story

Integration authors can tell which document-execution and provider operations they may replace, retry or transform, and which operations they may observe through hooks while the engine or provider owns the outcome.

For example, an Issue provider legitimately handles its destination and returns an answer without calling another provider. Execution.document deliberately offers withProps() to change document inputs. Those contracts need explicit treatment when observation APIs move to hooks.

Current gap

The same continuation API currently represents both intentional replacement and owner-controlled operations. Some operations enforce restrictions through feature-specific request and outcome machinery. #954 defines a security model and a hook contract, but does not classify or migrate those existing APIs.

Scope and acceptance

Produce an accepted, bounded contract map for:

• Execution.document, including withProps() and the document result;
• GitHost.route, including provider routing and accepted effect outcomes;
• IssueOperations and IssueApi;
• PullRequestOperations, PullRequestAPI and PullRequestReadExecution;
• Component.importComponent, distinguishing ordinary authored replacement from generated-evaluation admission.

For each operation, the map independently states permitted request changes, whether delegation may be omitted or repeated, whether a handler may replace the returned value, and who owns execution, settlement and durable publication. Include a real consumer and an existing regression that distinguishes those rights.

The resulting architecture and public references give an author a consistent answer. Observation-only responsibilities use the approved hook contract. Intentional routing, retries, synthetic answers and transformations retain middleware where they are part of the supported feature contract. A mixed operation has an explicit decision about separating these responsibilities before migration.

Preserve the host's generated-evaluation limits, credential restrictions, publication evidence, replay identities, transaction ownership and cancellation. Trusted native middleware is outside the malicious-code containment model; restrictions still need an in-scope threat or a concrete reliability/compatibility consequence.

Every proposed removal or migration names the machinery it replaces and the supported behavior it preserves. Return a material behavior or public-interface change for architecture resolution; do not silently weaken a contract or invent a generic registry, terminal or capability protocol to satisfy the audit.

Evidence and completion

The map links each decision to current source, its consumer and discriminating evidence. Existing entry points include packages/core/tests/execution-protocol.test.ts, packages/core/tests/invocation-identity.test.ts, packages/git/tests/issue-markdown.test.ts and packages/git/tests/pull-request-read.test.ts.

The issue completes with the accepted contract map, coherent architecture/reference updates and decision-ready migration tasks for each required runtime change. Runtime implementation belongs to those bounded tasks; this issue does not authorize a blanket API conversion or require a repository-wide new test matrix.

Dependencies and related work

Uses the approved model in #954. Contract analysis can proceed alongside #956's hook implementation; an actual conversion depends on that adapter being available. #491 owns the broader scope/resource ownership audit; this issue supplies the specific extension-rights decisions for the API families above. #435 owns review-closure policy. Their existing contracts remain separate.