Skip to content

Latest commit

 

History

History
115 lines (105 loc) · 7.4 KB

README.md

File metadata and controls

115 lines (105 loc) · 7.4 KB

Machine-control contract projections

This directory owns the exercised JSON projection used by resident desktop implementations. It is deliberately a small, evolving facade contract rather than a frozen cross-device wire protocol.

  • request-v0.schema.json describes the common request envelope and currently exercised desktop fields.
  • result-v0.schema.json describes the truthful result envelope shared by the Windows, macOS, and Linux slices.
  • update-status-v0.schema.json describes the native desktop discovery snapshot returned as data.update by update.check and update.status. data.queued reports pending discovery; acceptance is not network completion or installation. Only existing desktop product transports expose it. There is no public update install or endpoint method.
  • doctor-v0.schema.json describes the minimized, independent readiness dimensions emitted by authoritative testbeds. Desktop targets report desktop/resident state; device targets report connection, boot, interaction, and runner state without pretending those processes are identical. Its optional lifecycle extension reports suspend availability, reasons, and the provider's default down action without implying that an unavailable operation is safe.
  • targets-v0.schema.json describes ignored local target selection. It contains adapter commands, never bearer authority. See the target-registry guide for setup modes, source precedence, and the optional inventory-provider contract.
  • controller-config-v0.schema.json describes the per-user controller configuration that selects a registry file and inventory provider outside any checkout, disables sibling-inventory discovery, and declares whether the host is attended.
  • claim-capabilities-v0.schema.json describes exclusive exact-resource claim policy, ordinary/disruptive use classes, duration bounds, claimant attribution limits, and queueing behavior.
  • claim-result-v0.schema.json describes claim acquisition, use class, status, validation, renewal, release, and typed conflicts without exposing the concrete provider identity.
  • access-admission-v1.schema.json separates resource availability, live waiting intents, finite activation offers and generation-bound control sessions. Mutation authority belongs to the live admitted channel; IDs remain selectors. This extension does not change legacy claim v0 or advertise production queue support by itself.
  • run-result-v0.schema.json describes scoped-task stderr audit records, including independent task outcome and cleanup status.
  • workspace-capabilities-v0.schema.json describes provider-neutral persistent, isolated, and candidate workspace support without naming the hypervisor or a concrete VM.
  • workspace-result-v0.schema.json describes acquire, inventory, release, and garbage-collection dry-run results. Its handles are opaque selectors backed by private provider receipts, not bearer authority. Accepted VM acquisition also carries the exact workspace's public target-use claim descriptor.
  • candidate-assertion-v0.schema.json is the minimized adapter-to-client proof of an exact candidate role, power state, and absence of workspace ownership. It intentionally omits the provider identity itself.
  • maintenance-capabilities-v0.schema.json describes read-only discovery of explicit platform audit, repair, and exact-source certification operations. Profiles and operations may be unavailable when a physical target does not have an appliance image.
  • maintenance-result-v0.schema.json is the common minimized projection of validated platform-owned maintenance evidence. It omits private boot, service, endpoint, and staging details.

Platform adapters may add fields under the permissive schema while the corpus is still v0. They may not omit route, generation, delivery/effect separation, host interference, uncertainty, or typed refusal merely because an upstream provider uses a different response shape.

The physical-iOS adapter now returns this result envelope for its explicitly iOS application and XCTest operations. generation: unavailable is honest when CoreDevice supplies no public boot generation; semantic payloads preserve Agent Device's provider-scoped refsGeneration instead of fabricating a target generation.

Transport is outside these schemas. Local IPC, a CLI, SSH, tart exec, an authenticated carrier, and MCP may all carry the same request and result. The current dependency-free projection is bin/machine-control; its adapter tests and guarded three-desktop workflow are documented in tests/client.

  • Desktop event v0 defines the private desktop audit and diagnostic metadata format; it is not an agent control endpoint.

The live admission channel schema and API guide define connection-owned waiting, explicit activation and fenced dispatch under a negotiated profile.

  • Claim capabilities v1 explicitly negotiates the cooperative live queue while preserving v0 fail-fast behavior.

  • Claim admission channel v1 defines connection-owned waits, short offers, exact claim activation and cancellation. Its claimant assurance remains self-asserted; it does not grant desktop access.

  • Outer borrow v1 describes private adapter-derived controller-local VM claim binding. It is not a public target projection or authenticated caller credential.

  • Admission channel v2 describes the live owner channel on every desktop resident: open/command frames, the reply envelope used for every reply after control.open (refusals included), the shared admission view, and the common refusal vocabulary. renewal appears only when control.renew can succeed for that owner.

  • Deployment status v1, locked-use status v1 and common desktop status v1 describe the status.data fields every desktop resident projects: desktopState, deployment.policy.protectedAdministration and a common locked-use phase. tests/conformance/platform_contract.py checks a claimed target against these contracts through the ordinary CLI (Tactical 159).

  • Caller verification v1 describes the opt-in Only verified callers mode: status.data.callerVerification and the data of a caller_not_verified refusal (Tactical 161). Status names approved apps by display name and publisher only. The mode is a picket fence against callers not started from an approved app, never same-user containment. macOS projects it today; other residents omit it until they implement it, then report supported: false where unavailable.