# NEXT temporary cross-cutting contract — CLI/library/MCP and machine contracts {#root}

@status:impl/plan

[p01] @fact:NEXT-G08-SCOPE Frozen cross-cutting requirement source from refined plan revision 4 section 8. It complements domain contracts and must be promoted clause by clause; no product implementation or completion is asserted here. @status:spec/done

[p02] @fact:NEXT-G08-U001 Names below are implementation proposals; accepted behavior governs them. All surfaces use one library result. @status:spec/done

[p03] @fact:NEXT-G08-U002 Requirement: | Capability | CLI / machine input | Library/MCP and output | |---|---|---| | Source/resource | spec resolve, expectations and chunk request | Classified unit/section/raw resource, proof/encoding/spans/errors | | Configuration | choices query, install/reconfigure/update | Captured catalog, requested/resolved effects and graph | | Change read/write | change check/show/coverage; new/answer/promote/close | Snapshot/complete observations; explicit mutation preconditions | | Production/verification | create --change; build; verify --change | Existing engine with explicit operation policy/request/transition; ordinary/scoped verify no new producer | | Full pass | change apply explicit fixed composition | Production once + current-source verification; park/failure explicit | | Migration | migrate plan/apply with source/target epoch | Deterministic diff, NeedsInput, safe apply/recovery | | Boot debugger | JSON request stream/file or equivalent structured CLI input | Versioned inspect/tree/explain/cost/preview/compare/cancel/progress, snapshot IDs | | Interactive debugger | Tree/detail/source/compare frontend | Same library/protocol, suitable for independent IDE client | | External adapter | prepare/plan/apply/update/revoke/remove | Requested capabilities, exact grants, receipts and outcomes | | Derivatives | derive/show/diff/rebase/apply | Owner identity/base/local/result provenance and activation status | | Publication | prepare/authorize/apply/status/recover | Exact prepared batch; A approval or future B policy decision; smoke status | | Brownfield | intake observe/propose/promote | Inventory/proposal/promotion witnesses | | Environments/tools | env inspect/plan/apply/update/remove/verify/exec; tool install --environment | Definition/lock/target/realization/inventory/owned effects/recovery; exact environment ID and generation | | Profiles/store | generation list/activate/rollback; store gc plan/apply | Retained roots/live leases, command conflicts, mutable-state distinctions | | Image build | image plan/build/inspect/export/load/push | Same artifact DAG, BuildKit operations, platform/closure/OCI evidence and typed progress | | Services | service list/describe/probe/call | Tool/API descriptors, bound endpoints, schemas/effects/auth scope, health completeness | | Supply-chain portability | mirror prepare/export/import; realization substitute | Exact captured inputs, alternate locators, cache trust and no-GitHub diagnostics | | ETO discovery | capabilities/models/schema, canonical API call and negotiated session | Whole-product operation/model coverage, schema/effects/applicability/availability/capture capabilities | | Context/working state | context register/select; snapshot capture/get; document open/change/close | Trusted root/target binding, per-client overlays, raw/projection positions and coherent snapshot vectors | | Generic action/control | action prepare/submit; operation get/events/control/attach | Typed plan/input/authority, durable idempotency, responsive progress/cancel/reconnect and partial recovery | | Semantic refactoring | package rename prepare/apply/status/recover | Exact typed scope/edits/identity transition, versioned diagnostics, journal/regeneration/postconditions | | Internal observations | model children/query/explain; trace inspect/capture/export | Versioned stage structures, provenance/completeness, chunked values and retained extension schemas | @status:spec/done

[p04]
```text
| Capability | CLI / machine input | Library/MCP and output |
|---|---|---|
| Source/resource | spec resolve, expectations and chunk request | Classified unit/section/raw resource, proof/encoding/spans/errors |
| Configuration | choices query, install/reconfigure/update | Captured catalog, requested/resolved effects and graph |
| Change read/write | change check/show/coverage; new/answer/promote/close | Snapshot/complete observations; explicit mutation preconditions |
| Production/verification | create --change; build; verify --change | Existing engine with explicit operation policy/request/transition; ordinary/scoped verify no new producer |
| Full pass | change apply explicit fixed composition | Production once + current-source verification; park/failure explicit |
| Migration | migrate plan/apply with source/target epoch | Deterministic diff, NeedsInput, safe apply/recovery |
| Boot debugger | JSON request stream/file or equivalent structured CLI input | Versioned inspect/tree/explain/cost/preview/compare/cancel/progress, snapshot IDs |
| Interactive debugger | Tree/detail/source/compare frontend | Same library/protocol, suitable for independent IDE client |
| External adapter | prepare/plan/apply/update/revoke/remove | Requested capabilities, exact grants, receipts and outcomes |
| Derivatives | derive/show/diff/rebase/apply | Owner identity/base/local/result provenance and activation status |
| Publication | prepare/authorize/apply/status/recover | Exact prepared batch; A approval or future B policy decision; smoke status |
| Brownfield | intake observe/propose/promote | Inventory/proposal/promotion witnesses |
| Environments/tools | env inspect/plan/apply/update/remove/verify/exec; tool install --environment | Definition/lock/target/realization/inventory/owned effects/recovery; exact environment ID and generation |
| Profiles/store | generation list/activate/rollback; store gc plan/apply | Retained roots/live leases, command conflicts, mutable-state distinctions |
| Image build | image plan/build/inspect/export/load/push | Same artifact DAG, BuildKit operations, platform/closure/OCI evidence and typed progress |
| Services | service list/describe/probe/call | Tool/API descriptors, bound endpoints, schemas/effects/auth scope, health completeness |
| Supply-chain portability | mirror prepare/export/import; realization substitute | Exact captured inputs, alternate locators, cache trust and no-GitHub diagnostics |
| ETO discovery | capabilities/models/schema, canonical API call and negotiated session | Whole-product operation/model coverage, schema/effects/applicability/availability/capture capabilities |
| Context/working state | context register/select; snapshot capture/get; document open/change/close | Trusted root/target binding, per-client overlays, raw/projection positions and coherent snapshot vectors |
| Generic action/control | action prepare/submit; operation get/events/control/attach | Typed plan/input/authority, durable idempotency, responsive progress/cancel/reconnect and partial recovery |
| Semantic refactoring | package rename prepare/apply/status/recover | Exact typed scope/edits/identity transition, versioned diagnostics, journal/regeneration/postconditions |
| Internal observations | model children/query/explain; trace inspect/capture/export | Versioned stage structures, provenance/completeness, chunked values and retained extension schemas |
```

[p05] @fact:NEXT-G08-U003 Owned machine surfaces use strict versioned JTD plus generated types/corpora. Carrier map includes authored config, normalized domain, request/result/error/event, durable plan/receipt, outbox/resume, hash frame, artifact/evidence and CLI/MCP. UI never scrapes human sentences. Unsupported operation/epoch/field refuses before effects. @status:spec/done

[p06] @fact:NEXT-G08-U004 Debugger exposes machine **input and output**, not only --json output. Every event binds request_id + snapshot/operation context + sequence; terminal status explicit. Pagination bound to snapshot/filter, stale cursors refused. Limits on response payload do not truncate total boot silently. Dynamic cost scenarios expose conditions; unsupported exact native attribution remains typed unknown. @status:spec/done

[p07] @fact:NEXT-G08-U005 No second evidence authority or general workflow interpreter: API operation envelopes reference existing domain records/journals. Publication authorization API is not autonomous task selection. @status:spec/done

[p08] @fact:NEXT-G08-U006 ETO full path (§3.21) is normative for every row, not only debugger calls: strict schemas, context/snapshot/overlay identity, typed pre/post-effect errors, controls/reconnect and generated capability/model coverage. A negotiated canonical machine session and one-shot calls expose the same semantic operations; MCP maps those capabilities without inheriting its current limited tool grammar as the product boundary. LSP/DAP mapping is future adapter work, not a new domain schema or planned IDE MVP. @status:spec/done