Trusted local provisioning protocol for adopted-principal assistants, MCPs, and skills

# A0 — Trusted local provisioning protocol for adopted-principal assistants, MCPs, and skills

## Parent and authority

- Program epic: `sparkfn/pc-client#1082`
- Team-definition capability: `iOfficeAI/AionCore#798`
- This body is the complete protocol/implementation contract. Historical comments and old downstream baselines are non-authoritative.

## Current verified baseline — 2026-08-08

- AionCore public `main`: `560ffb47b1a058413f60941d0cc559738226eb5a`.
- AionUi public `main`: `31ec26a902edf7bdda90026b1f9d6f4d0507b706`.
- Installed `/Applications/AionUi.app`: `2.1.52`.
- pc-tools production currently integrates an unversioned internal HTTP surface by spawning a closed-app `aioncore --local`; sparkfn/pc-tools#643 is removing the unsafe inference that this can represent an adopted/AionPro principal.
- Public AionCore exposes user-owned assistant, MCP, skill, and adoption behavior, but still does not expose a stable conversation-independent, least-privilege external provisioning protocol with attestation, managed provenance, conditional whole-resource reconcile, and exact readback.

## Objective

Provide one vendor-supported local provisioning protocol that pc-tools can use for an exact adopted AionUi principal without port discovery, browser/session credential extraction, conversation authority, direct database access, or `system_default_user` fallback.

## Required capability model

Advertise separately scoped, revocable capabilities for:

1. assistant definition/rule/default/placement management;
2. MCP registration/configuration management;
3. skill registration/activation management.

Possession of one scope must not authorize another. A1 Team-definition authority remains separate.

## Required scope

1. Stable local discovery/IPC to the correct running or closed installation/profile without caller-provided port.
2. Conversation-independent short-lived authorization and attestation of installation, profile, subject/issuer claims, capability version, AionCore version, and AionUi version.
3. Vendor-native managed provenance that survives restart and compatible upgrade.
4. Conditional/transactional assistant reconcile covering rule, model, permission, thought level, skills, MCPs, and placement as one coherent revision.
5. Conditional MCP and skill reconcile with exact readback and preservation of foreign/user resources.
6. Structured bounded error/reason vocabulary and explicit account-switch, expiry, revocation, restart, running-app, and closed-app behavior.
7. Assistant readback that reports exact Team adjacency or explicit unknown so a Team-referenced assistant cannot be deleted as unreferenced.

## Constraints

- Caller cannot select installation/profile/subject/native IDs as authority.
- Account switch exposes a distinct subject and invalidates/blocks old authority; no automatic rebinding.
- Conditional conflict cannot overwrite a concurrent UI edit.
- Failed operations leave the prior coherent resource or an authoritative journal that can safely resume/revert.
- No machine token is sent to AionCore and no vendor credential is placed in AionUi-readable configuration.
- No port scanning, cookies, CSRF, conversation/runtime tokens, direct SQLite/filesystem mutation, or `--local` fallback.
- Assistant-only authority cannot mutate Teams; Team adjacency must still be readable enough to block unsafe deletion.

## Deliverables

1. Versioned protocol and capability specification with schemas, limits, lifecycle, and stable errors.
2. Discovery/IPC, authorization, attestation, managed provenance, conditional reconcile, and exact readback implementation.
3. Unit/integration/concurrency/failure/revocation/account-switch tests.
4. Black-box qualification runner/checklist for downstream pc-tools.
5. Exact minimum supported AionCore/AionUi versions.

## Acceptance criteria

- [ ] **A0-AC1:** A non-conversation process reaches the correct installation/profile without caller-provided port or browser/session state.
- [ ] **A0-AC2:** It obtains least-privilege scope and reads exact attested installation/profile/subject before any write.
- [ ] **A0-AC3:** On an adopted AionPro principal, create a disabled managed assistant, write rule and all five axes, verify UI visibility/readback, update, disable, and delete.
- [ ] **A0-AC4:** Concurrent UI edit yields deterministic conflict/transaction outcome and no silent overwrite.
- [ ] **A0-AC5:** Managed provenance survives backend restart and compatible app upgrade.
- [ ] **A0-AC6:** Account switch blocks old subject and exposes a distinct new identity with no rebinding.
- [ ] **A0-AC7:** Expired/revoked/wrong-profile authority returns stable codes and performs zero mutation.
- [ ] **A0-AC8:** Full black-box assistant lifecycle passes on real ordinary-user macOS and Windows second-release upgrade paths.
- [ ] **A0-AC9:** Running-app and closed-app behavior is explicit and never implicitly targets local-default identity.
- [ ] **A0-AC10:** Scoped adopted-principal MCP and skill create/update/read/remove passes; foreign/user state remains unchanged and assistant-only scope cannot invoke it.
- [ ] **A0-AC11:** Assistant readback exposes exact Team references/unknown adjacency and delete refuses a Team-referenced assistant until safe Team removal.

## Mandatory negative cases

- [ ] Wrong installation/profile/subject fails before write.
- [ ] Missing/expired/revoked credentials are not anonymous authority.
- [ ] No port scan, cookie/CSRF/runtime-token reuse, direct DB/filesystem write, machine-token forwarding, or `system_default_user` fallback exists.
- [ ] Partial/failed assistant transaction cannot leave a newly enabled hybrid resource or false success.
- [ ] Dependency removal cannot delete foreign/user resources or a still-referenced managed dependency.
- [ ] Team adjacency cannot be silently omitted or guessed absent.

## Dependencies and blocked-work rule

Downstream pc-tools may land dark interfaces/fakes/contracts before A0 closes, but adopted-principal mutation stays off until all A0 acceptance items have native evidence. If work is blocked, keep the issue open and name the exact unmet acceptance ID, completed evidence, dependency, and next executable step; do not propose an unsafe workaround.

## Release boundary

Completion authorizes merge consideration only. It does not authorize a release, deployment, promotion, fleet gate, or secret mutation.

The issue names no source files or test paths. Start with the AionCore public main baseline and the versioned protocol/capability specification deliverable, then review the discovery/IPC and authorization entry points; use the required unit, integration, concurrency, failure, revocation, account-switch tests and black-box qualification runner to verify the acceptance and negative cases. Done means native evidence for A0-AC1 through A0-AC11 without unsafe fallbacks.

Written by the indexing model from the issue text.