# Typed RootHelper bridge contract (implementation, not native acceptance) ## Host reboot evidence and historical configured effect (Spec 1.13) An ambient `reboot_required=true` is honest pending evidence, not an implicit reboot request or a failed package postcondition. Future fixture effects must prove equal HOST flags before/after, unchanged boot and no private-worker flag. The parent captures `active/host-reboot-before.json` **before unshare/private `/run`**. Schema 1 fields are `transaction_sha256`, `job_payload_sha256`, `effect_armed_ledger_id`, `grant_id`, `boot_id`, `host_reboot_required` (bool), and `observed_at_ms`, plus `schema_version`. Creation is exclusive and fsynced; its observation must belong to the original grant window. New native prechecks use schema 2, retaining the old exact checks and adding `host_reboot_before_sha256` and `host_reboot_required_before`. The child binds the saved host observation; its private `/run` never measures the host flag. After real APT success the parent verifies the current host flag equals the saved value, boot is unchanged and `sandbox-result.reboot_required` is false. False/false and true/true are valid; either change or a private-worker flag vetoes acceptance. Outcome evidence includes `host_reboot_required_before`, `host_reboot_required_after`, `host_reboot_before_sha256`, `reboot_required_introduced:false`; `reboot_required` truthfully retains ambient true. Ordinary acceptance record **schema 3** explicitly binds those fields and `native_prechecks_schema_version:2`. The reader rejects old record schemas or inconsistent values. Separate future recovery records use schema 2 and retain their distinct `rmm.apt.native-recovery` type. Noop observations remain effect-free and report their actual current reboot flag. Fresh planning adds the required public bool `host_reboot_required`; known ambient true is shown in the fixed WebUI plan reason. Historical grant `33775478-15b0-46ec-b059-44f500dbb0b6` had **no host-before sample**. It must never acquire retroactive success or an acceptance record. Fixed mode `verify-configured-recovery` receives the same eight original binding fields as `verify-partial`. Only its signed schema-4 configure-only job, old provider `5ff260…`, old schema-1 prechecks, original partial grant `31ef5e5e…` / proof `dc3bf387…`, preserved recovery once marker, exact Configure hook, APT exit 0 and private-worker false are eligible. It checks complete stable installed 1.0 state, clean audit, actual payload, unchanged boot, idle locks and current host marker contents twice, rechecking all thirteen immutable witnesses. Output is `known_failed` / `APT_RECOVERY_CONFIGURED_ACCEPTANCE_REBOOT_FLAG_VERIFIED`. Its 24-field proof contains the original eight bindings, type/schema, original evidence digest, partial proof hash, original baseline and current snapshot hashes/fingerprint, payload hash, full snapshot, check time, `effect_complete:true`, `partial_effect:false`, `postconditions_passed:false`, `reboot_required:true`, `host_reboot_required:true` and `host_reboot_marker_sha256`. No ctime-based inference becomes a before measurement. It writes nothing and runs no package mutation. Rust independently verifies the saved signature/old unknown code, appends a separate immutable proof, and leaves consumption locked until normal signed RootSync. Native classification and future 1.1 acceptance remain pending until actually executed; **81 local Python tests passed**, including both actual APT argument regressions under the readonly unprivileged offline container. ## Configure-only partial recovery (schema 4, local implementation) This is a **new, separately WebUI-approved** dev-test native action. Schema 4 requires `native_recovery = {schema_version:1, previous_grant_id, previous_attempt_id, partial_proof_sha256}` and forbids `native_retry`. Resolved transaction schema 2 adds `operation:"configure_only"`; only the existing `rmm-apt-fixture-install-1.0` recipe/version 1, pinned fixture archive, and old/new version `1.0` are eligible. Schema 1 retains its exact encoding. The helper first requires the original saved signed request, immutable SQLite partial proof, definitive `APT_PARTIAL_UNCONFIGURED_VERIFIED` outcome, and closed consumed row. `recovery-planning` receives exactly `{native_recovery, proof}`; Python rechecks the original still-active witnesses and complete current partial snapshot. It seals only the content-addressed baseline and returns the normal planning projection plus `native_recovery`. Ordinary planning continues to reject unconfigured packages. This passive projection creates no job or authorization. For execution the helper archives the definitive old active directory, stages the exact proof as `active/partial-proof.json`, and binds its hash in the new signed manifest. Python independently checks history, original target, full partial baseline and installed fixture bytes. APT receives only `install -- rmm-mvp-test=1.0`; the actual v3 hook must contain exactly one equal-version `**CONFIGURE**` action. Unpack, removal, foreign packages and pending configuration remain forbidden. The same native sandbox, grant deadlines, locked-store handoff and complete postcondition/audit checks apply. Create-once markers are `recovery-attempt-.json`, `pending-recovery-.json`, and `recovery-.json`. Original/retry markers, signed histories and the original unknown proof remain intact. Recovery produces `native_recovery:true`, `recovery_record_sha256` and `partial_proof_sha256`; it creates no fresh-install acceptance record or `native_record_sha256`. A later separately approved native 1.1 upgrade must provide the ordinary acceptance evidence for the changed provider/runtime. Local actual APT 2.6.2, with a vetoing collector and independently guarded fake dpkg, emitted only the exact configure action/target; real and copied package status stayed unchanged. This is **local regression evidence**, not Cloud-VM recovery acceptance. Native deployment, UI approval and execution remain the parent's next acceptance step. ## Explicit one-attempt recovery (schema 3, 2026-11-13) Schema 2 keeps its exact old encoding (the optional field is omitted). Schema 3 requires `native_retry` and is valid only for dev-test `apt-native-acceptance`: ``` native_retry: { schema_version: 1, previous_grant_id: UUID, previous_attempt_id: UUID, bootstrap_marker_sha256: SHA256(original exact marker bytes) } ``` This reference belongs to a **new separately UI-approved signed job**, never an unsigned IPC override. Under the existing device lock, before consuming the new grant and again before staging, the helper verifies the original saved Ed25519 request historically, identical target/generation/assignment/transaction, distinct job/attempt/authorization/plan, same-ledger terminal `failed` result `HOOK_NOT_HANDED_OFF`, matching recorded outcome, original context/launch/ sandbox-100 evidence and absent hook/acceptance/retry markers. Historical signature verification never grants a current start. Unknown or partial history fails closed. Original active state may only move through the existing terminal history rule; original tombstone never changes. Provider independently checks original marker hash and immutable history, identical full baseline and current normal baseline gates. It exclusively writes `bootstrap-retry-.json` binding the new attempt, signed reference and hashes of historical evidence. Worker, hook and completion recheck it. This is one recovery attempt per fixed fixture recipe, not general automatic retries. Test/native outcomes are recorded in `docs/implementation-status.md`. **Dedicated-runner update:** the current deployment and readiness protocol is defined in [`../../deploy/linux/apt-helper-README.md`](../../deploy/linux/apt-helper-README.md). The actual additive domain schema-2 types and AptNativeAcceptance variant have since landed and are exercised by a local exact-signature/helper roundtrip test. Agent routing and nonce/root-peer/identity/profile/stack-bound readiness are implemented. Older descriptions below of absent domain fields or missing runner describe the earlier increment, not a remaining implementation gate. Real VM profile/probe/installation acceptance remains unmeasured, not passed. ## Current integration status / exact outstanding domain change The helper now contains a real provider bridge in `crates/privileged-helper/src/apt.rs`, called by its existing peer-credential authenticated IPC handler, **not** by a script wrapper. The domain job source was leased to the backend worker during this dispatch; it was not edited. Legacy package jobs cannot supply the required manifest and remain gated. No package capability was added to the agent. No native package/service/reboot operation, VM action, helper installation or acceptance record occurred here. Required additive domain/backend contract, before capability advertisement: 1. Define typed `AptExecutionManifest` **schema 2**, `ResolvedAptTransaction` schema 1 and `PackageArchive` in domain (same exact fields/serde shape as the helper types below; do not make domain depend on the helper crate). All deny unknown/duplicate fields. No `serde_json::Value` opaque action authorization. 2. Existing `Action::EnsurePackage` and `Action::ApplyUpdates` gain a field `apt_manifest: Option`, default None for legacy reads. Execution/validation requires Some for APT. Serialization MUST preserve the complete object; ignoring unknown fields is explicitly detected and denied by `APT_DOMAIN_MANIFEST_NOT_CONFIGURED`. No unsigned IPC manifest field exists. 3. Add a dedicated Action variant with this exact JSON shape: ```json { "action": "apt_native_acceptance", "recipe_id": "rmm-apt-fixture-install-1.0", "recipe_version": "1", "apt_manifest": {"": ""} } ``` `Action::name()` and permit.action are `apt_native_acceptance`. Root-only, explicit dev-test, specific target, fixed UI-authorized job/attempt. The upgrade recipe is `rmm-apt-fixture-update-1.1` and needs another job. This is NOT an alias of run_script/diagnostic arbitrary execution. Backend plan/UI allowlisting must show full transaction, exact hashes, origin, no-reboot, execution identity and test-acceptance nature before approval. 4. For fixture ensure_package the outer recipe_id/version must match the nested transaction exactly as strings. For apply_updates, outer provider=`apt`, packages=`["rmm-mvp-test"]`, reboot_policy=`never`, nested upgrade recipe only. Other original action parameters are retained and compared against the domain's typed serialization, never accepted through parameter aliases. 5. Backend validation/planning/signing must validate both manifest transaction representations, generate JobPayload once and sign its exact payload hash in the existing Ed25519 permit. Keep all existing target/tenant/generation, authorization/plan/job/attempt/identity/time bindings. Planning needs the inspected root runtime/config hashes and immutable baseline/fingerprint. 6. Agent forwarding/capability negotiation must be separately integrated after the domain contract and native prerequisites are complete. This dispatch did not change agent/protocol/server files. No optimistic capability claim. Current clear gates include `APT_PROVIDER_NOT_CONFIGURED`, `APT_MANIFEST_NOT_CONFIGURED`, `APT_DOMAIN_MANIFEST_NOT_CONFIGURED`; an older domain may reject the action even earlier as INVALID_JOB/unknown field. That earlier rejection is not a fallback or authorization shortcut. ## Public Rust API Current additive passive/no-change contract is documented in `deploy/linux/runtime-README.md` ("Passive APT planning and declarative no-change"). `readiness::PlanningResult` is returned only by authenticated `apt_planning_v1`; it creates no capability. `planning-status` can create only content-addressed root metadata seals. A normal exact already-desired fixture returns driver `verified_no_change` / `POSTCONDITION_ALREADY_MET`, never a fake `POSTCONDITIONS_VERIFIED` transaction/hook. Parent consumption and all signature, manifest/runtime/native-record/artifact/current-state gates remain required. ``` apt::ProviderConfig // serde deny_unknown_fields apt::AptExecutionManifest // schema 2 apt::ResolvedAptTransaction // schema 1 apt::PackageArchive apt::is_apt_action(&JobPayload) -> bool apt::policy_header(&JobPayload, &ProviderConfig) -> anyhow::Result<()> apt::prepare(&Binding, &Request, &ProviderConfig, DateTime) -> anyhow::Result PreparedApt::execute(self, &rusqlite::Connection) -> anyhow::Result apt::install_known_payloads() -> anyhow::Result<()> ``` PreparedApt has no public fields/unchecked constructor. `prepare` independently calls Binding::verify (exact Ed25519 request/grant and all existing bindings), checks policy, exact signed manifest/domain preservation/code/runtime bindings, installed trusted bytes and pre-grant prefetched artifacts. Parent consumes and save_start-persists the request before execute. Execute independently requires the corresponding consumed row (same agent/generation/job/attempt, result NULL) and the exact originally saved request/signature/permit/plan/authorization. Its stable effect_armed_ledger_id is `apt--`. ## Exact manifest schema 2 inside Action.apt_manifest ``` type: "rmm.apt.helper-action" schema_version: 2 action: "apt-native-acceptance" | "apt-execute" execution_profile: "dev-test" transaction_sha256: SHA256(transaction_bytes) resolved_apt_transaction: complete typed ResolvedAptTransaction object transaction_bytes: Vec / JSON array of integer bytes provider_sha256: SHA256(exact installed Python provider bytes) hook_sha256: SHA256(exact installed fixed hook bytes) apt_config_sha256: SHA256(print-config output bytes) runtime_sha256: SHA256(canonical inspect-runtime output object) test_result_id: ASCII identifier [A-Za-z0-9_.-], 1..128 bytes ``` The full object AND exact transaction bytes are required. Deserialize the bytes with the strict typed schema and require equality to the nested object. The provider writes those **same bytes**, not reformatted JSON, to expectation.json. It copies **the full original Request.job_bytes unchanged** to signed-action.json; job_payload_sha256 in context is SHA256 of those complete domain job bytes. The Python loader now requires that full JobPayload envelope and checks the nested action, job/attempt/root identity, inner bytes/hash/object and code pins. A detached old standalone schema-1 helper-action manifest is no longer accepted. ResolvedAptTransaction fields (all mandatory): schema_version=1, recipe_id, recipe_version="1", platform="ubuntu-24.04-amd64", resolver_config_version="rmm-apt-local-v1", no_reboot=true, status_fingerprint, baseline_sha256, packages. PackageArchive fields: name, architecture, old_version (null/string), new_version, origin, sha256, size, archive_path. Only the code-pinned single-package fixture install/upgrade is configured. Production and arbitrary catalogs remain denied; a test acceptance does not authorize another recipe/closure/profile. Exact fixture hashes are in README. ## Root configuration / trusted installation / prefetch Existing root-owned 0600 helper config gains optional `apt_provider` (absent = disabled). No new secret/environment variable or caller-supplied path: ```json { "schema_version": 1, "execution_profile": "dev-test", "allow_fixture_bootstrap": true, "allowed_recipes": ["rmm-apt-fixture-install-1.0", "rmm-apt-fixture-update-1.1"], "runtime_sha256": "", "apt_config_sha256": "" } ``` These are local policy limits, not approvals. Keep the existing binding, signing-key pin, agent UID/socket GID and parent ledger provisioning unchanged. No artifact URL/network fetch exists in the root provider. Planned administrator tool installation, **not executed**: ``` /usr/local/libexec/rmm-privileged-helper --install-apt-provider ``` Root-only, fixed paths, create-only: embeds Python/hook bytes at Rust compile time, writes root-owned `/usr/lib/rmm-apt-transaction/{apt_transaction.py,hook}` (0644/0755), `/var/lib/rmm-apt-transaction` and archives/baselines/history (0700), and `install-metadata.json` (0600, provider/hook hashes). Refuses existing files/ directories instead of replacing/chmodding them. Partial installation requires explicit operator reconciliation; no automatic deletion/repair. On each use, installed bytes and metadata must match the helper's compiled known payloads. The interpreter is fixed `/usr/bin/python3 -I`, root-owned resolved interpreter; all provider/store path components are root-owned, nonsymlink and not writable by group/others. This installation creates no acceptance or grant. Planned explicit pre-grant fixture preparation, **not executed**: ``` /usr/bin/python3 -I /usr/lib/rmm-apt-transaction/apt_transaction.py provision-fixture-store ``` Only the two pinned deterministic fixture archives can be created, never an arbitrary archive/URL. Archives and `prefetch-.json` receipts are fsynced, root-owned 0600, exclusive creation. Receipt fields: schema_version=1, sha256, size, sealed_at_ms. Helper requires receipt time <= permit.not_before, matching actual SHA256/size/single-link archive. Missing/writable/symlinked/unprefetched artifacts fail before consumption. All downloads/imports must finish before the final short grant, never during execution. Artifact mTLS fetch elsewhere must ultimately yield the same root-verified sealed-store contract, not an agent path. The same preparation stores complete canonical dpkg baseline at `baselines/.json` and emits baseline hash/status fingerprint for the approved immutable plan. It creates neither jobs nor authorization. For subsequent changed baselines, the root-only `prepare-baseline` mode samples current dpkg state and creates a new content-addressed canonical baseline before the new plan/final grant. An identical existing baseline is only read/verified, never rewritten; changed state creates another hash file, never resets archives, receipts or acceptance/attempt markers. It creates no job authority. Do not modify a sealed file or fake a fingerprint. Archive preparation is create-only. Root `inspect-runtime` / `print-config` provide the planning measurements; hash inspect-runtime's canonical JSON object **without its trailing newline**. Review the measured binary/OS/dpkg configuration rather than blindly trusting a hash. ## Handoff, outcomes, recovery and unit prerequisites Parent handler retains its existing device lock, consumes once, save_start persists exact signed request, and rechecks clock/grant before effects. Bridge creates active/0700 and expectation/signed-action/baseline/config/context files 0600 using exclusive nofollow writes and file/directory fsync. Context schema 2 contains the same grant/job/attempt/authorization/plan IDs and original UTC deadline translated to CLOCK_MONOTONIC, not a fresh 60-second grant. An old active directory can only move to history/ when the same parent ledger contains a definitive succeeded/failed result. Unknown/null, unrecognized/partial handoffs or existing history destination block execution. No tombstone/native bootstrap-attempt record is removed. Parent grant/attempt consumption survives any active-directory move. Python receives only fixed mode/path argv and two hash/ledger fields via stdin, with cleared environment; no shell, secret argv or script conversion. Structured stdout is bounded to 64 KiB (excess drained without unbounded allocation), raw stderr discarded. Never timeout-kill APT. Client timeout is unknown while the helper keeps running and eventually journals the real result. Exit 0 alone is never success. Strict JSON effect_state/code/evidence validation requires bound ledger, exact package versions, full snapshot hash, installed fixture payload hash, and bootstrap test flags/native-record/test-result binding. Malformed/nonzero/missing/wrong evidence -> unknown. known_failed with an armed marker -> unknown, not failed. Existing finish() leaves consumed.result NULL for unknown/awaiting_reboot and persists execution_evidence, retaining the device lock. **Existing helper systemd unit is not an APT-capability deployment.** Its ProtectSystem=strict/other hardening can prevent the required store/package writes and namespace setup. A separately reviewed native runner/unit profile must permit the narrowly agreed fixture writes and setup capabilities while preserving the provider's final sandbox. No unit sandbox was weakened here. Do not announce capability based solely on a successful helper build. Local verification commands/results are reported in the dispatch return. Native helper installation, IPC package execution, lock probe, fixture install/ update and VM approval/acceptance remain unrun. Tests using private temporary ledgers/mock children are not native acceptance evidence. Actually executed for this bridge increment: ``` /home/Kevin/.cargo/bin/cargo fmt -p rmm-privileged-helper -- --check /home/Kevin/.cargo/bin/cargo clippy -p rmm-privileged-helper --lib --bin rmm-privileged-helper --tests -- -D warnings /home/Kevin/.cargo/bin/cargo test -p rmm-privileged-helper --lib --bin rmm-privileged-helper PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests/apt_transaction -p 'test_*.py' -v ``` Final results: formatting and warning-denying Clippy passed; **16 library + 2 binary Rust tests passed**, **41 Python tests passed**, AST syntax checks passed for **6 Python files**. No full workspace suite was run. An initial Rust test fixture used legacy ApplyUpdates, which the current domain rejected as `INVALID_JOB`; cryptographic/parent-ledger tests were corrected to use an existing valid signed action without executing it or allowing it as an APT action. This is not evidence that the missing domain package contract landed.