busya
605c5d0552
Add production contract refresh sections and normative contracts: 017/050 capture-reuse trust, 036 evidence promotion, 037 catalog lifecycle/revision, 038 browser actions/decision policy, 044-047 production chain/evidence/atomic triage, and 050 MCP interface artifacts. Requirements marked OPEN pending executable evidence.
5.1 KiB
@{ McpInterface.Modules [C:5] [TYPE ADR]
@BRIEF Versioned public parity for the audited production chain; implemented=false, acceptance OPEN. @PRE Every call authenticates a principal, checks live object/environment ACL and validates bounded typed input before I/O. @POST REST and MCP call the same service transaction and return the same domain result/error; transport wrapping never converts failure to success. @INVARIANT Client hashes, paths and raw image bytes never establish baseline authority. @RATIONALE Existing consume fallback and transport validation divergence make a successful tool envelope insufficient evidence of durable completion. @REJECTED Inferring approval/publication from working-tree YAML, duplicating services per transport, or exposing an agent prompt/launch UI.
Catalog and error contract
Catalog version 050.2.0 adds the schemas in tool-contracts.schema.json.
Existing names are retained where present; new names are normative additions, not a runtime catalog claim.
Every tool has a strict input schema, output schema, permission, principal class and idempotency classification.
Read tools require authenticated object ACL; list filtering never substitutes invocation authorization.
Errors: invalid_arguments (422), unauthenticated (401), permission_denied (403),
not_found (404), conflict (409), gone (410), limit_exceeded (413/429),
precondition_required (428), provider_unavailable (503).
MCP returns isError=true and the stable code; REST returns the corresponding status and identical details.
Approval required is a typed non-success pending result, never completed. No transport fallback invokes legacy approve after consume failure.
Service ownership and curated operations
| Operation | Domain boundary | Required authority / completion |
|---|---|---|
| capture_baseline, capture_visual_baseline | 037 authoritative source/capture | baseline write; registered server capture receipt, no arbitrary client content_ref |
| review_visual_baseline | 037 durable ReviewDisposition | human USER reviewer; immutable capture SHA/profile bound receipt |
| request_baseline_approval | 036 gate + 037 candidate | owner ACL; binds candidate/review/catalog CAS/release/publication intent |
| decide_approval | 036 durable gate | human USER; fresh ACL, reason, CAS, no side effect on denial |
| consume_baseline_approval | 037 catalog CAS | exact approved intent; materialized receipt, not published success |
| publish_baseline_catalog | 037 publication worker | explicit authorized Git intent; expected branch head; commit/push/reconcile receipt |
| rebaseline, retire_baseline, invalidate_baseline | 037 lifecycle | expected catalog revision, reason, gate where policy requires; historical pins unchanged |
| start_scenario_run | 044 admission | explicit revision/env/baseline selector; server resolution before idempotency/gates |
| get_scenario_run, get_scenario_run_result | 044 read projection | run ACL; exact stored pin/result, bounded pages |
| get_scenario_artifact | 044 evidence metadata | run/artifact owner ACL; typed protected content ref, never raw storage path |
| create/update schedule, webhook, CI dispatch | 046 automation | same REST validation even disabled; no HumanStep target |
| open/dispose investigation | 047 case transaction | case/queue/episode CAS atomic; external agent is pull-only |
All result evidence follows 044 result DTO. Artifact content is fetched with the same authorized GET/HEAD contract. MCP metadata refs are not bearer capabilities: expired authorization cannot fetch bytes. Immutable baseline pin follows 037 schema. Publication retries reuse publication_id and reconcile remote commit before retrying push; do not create duplicate revisions.
Browser, LLM and frontend boundary
MCP invokes existing 038/044 browser/capture/provider services; canonical browser mapping is 038 browser-actions. Only an external MCP client conducts agent authoring. Product frontend has manual CRUD/editor, human approval/review, monitoring and read-only evidence/evaluation. No agent chat, prompt, assistant editing, typical-operation-to-agent, proposal generation, agent workspace/start or handoff controls. AgentEvaluationCard is read-only; no retry-agent/provider/prompt buttons. An external agent may submit a new validated revision; it cannot mutate historical evaluation or baseline from a finding.
Acceptance
Fixtures must prove anonymous and cross-owner rejection, user/service decision distinction, stale CAS and changed-intent replay rejection, publication failure/retry without false success, run pin preservation across rebaseline, REST/MCP disabled automation parity, and absence of agent frontend controls. Provider canary readiness and optional approved performance baseline are not implied by this catalog.