diff --git a/.github/workflows/native-publish.yml b/.github/workflows/native-publish.yml index 60077e09..63476bc0 100644 --- a/.github/workflows/native-publish.yml +++ b/.github/workflows/native-publish.yml @@ -16,9 +16,15 @@ jobs: - os: ubuntu-latest target: x86_64-unknown-linux-gnu archive: tar.gz - - os: macos-14 + - os: ubuntu-24.04-arm + target: aarch64-unknown-linux-gnu + archive: tar.gz + - os: macos-15 target: aarch64-apple-darwin archive: tar.gz + - os: macos-15-intel + target: x86_64-apple-darwin + archive: tar.gz - os: windows-latest target: x86_64-pc-windows-msvc archive: zip diff --git a/decisions/decisions/adr-125-pilot-local-app-distribution.md b/decisions/decisions/adr-125-pilot-local-app-distribution.md new file mode 100644 index 00000000..96c4ad64 --- /dev/null +++ b/decisions/decisions/adr-125-pilot-local-app-distribution.md @@ -0,0 +1,122 @@ +--- +schema_version: 1 +id: RAC-01K8P7A3M5QZ +type: decision +--- +# ADR-125: Distribute AsDecided as a Local Pilot App + +## Context + +Pilot Protocol has two materially different discovery surfaces. Service agents +are always-on HTTP services reached across Pilot's encrypted overlay; App Store +apps are signed local adapters installed and supervised on the user's own node. +AsDecided reads repository-local engineering knowledge and deliberately avoids a +hosted corpus, so presenting it as a service agent would introduce tenancy, +authentication, storage, and trust decisions that the product has not made. + +Pilot's App Store now supports generated CLI adapters, `proc.exec` consent, and +per-platform native assets. A valid native submission must cover macOS and Linux +on both amd64 and arm64. AsDecided's current GitHub Release matrix omits macOS +amd64 and Linux arm64, which makes distribution incomplete before the adapter is +even considered. + +## Decision + +AsDecided will target Pilot's local App Store as `io.pilot.asdecided`, not the +Pilot service-agent directory. + +- The adapter is generated from Pilot's official `pilot-app` template and + invokes a release-pinned native `decided` binary delivered as a signed app + asset. +- The public method surface is curated and read-only. It exposes deterministic + retrieval, validation, relationship inspection, and help; it does not expose + arbitrary CLI passthrough, mutation, migration, scaffolding, or sharing. +- Repository access is explicit in each call and declared in the app's install + grants. Submission must not imply that a corpus is uploaded to Pilot or + AsDecided. +- Native releases cover `darwin/{amd64,arm64}` and + `linux/{amd64,arm64}`. Windows remains a supported AsDecided release target + but is not part of Pilot's required native asset set. +- Catalogue submission happens only after the four assets exist for one + immutable AsDecided release, their hashes are pinned, the generated bundle + verifies locally, and a real Pilot node proves install, help, and one retrieval + call against a fixture repository. + +## Consequences + +### Positive + +- Pilot users install AsDecided without creating a remote copy of their corpus. +- The Pilot surface inherits the Rust engine's deterministic behavior instead + of creating another implementation. +- Four-target native releases improve direct GitHub distribution independently + of Pilot. + +### Negative + +- The Pilot adapter is a second executable layer and must track its upstream IPC + and manifest contracts. +- Native release CI adds two runners and therefore more release time. +- Pilot's declared `proc.exec` and filesystem grants require higher scrutiny + than a remote HTTP adapter. + +### Risks + +- Source support for `proc.exec` may precede deployment on every Pilot host. + Mitigation: the catalogue submission is gated on a real-node install test. +- A broad filesystem grant could overstate required authority. Mitigation: no + arbitrary passthrough, explicit repository input, and review of the generated + manifest before signing or submission. + +## Status + +Accepted + +## Category + +Architecture + +## Alternatives Considered + +### Publish an always-on Pilot service agent + +Rejected. It would require hosting user knowledge and would change AsDecided's +local-first trust boundary rather than merely distribute the existing product. + +### Front a hosted HTTP shim + +Rejected for the same reason and because the local CLI adapter is now supported +by Pilot's current source. + +### Expose the whole CLI through passthrough + +Rejected. It would grant agents mutation and migration commands unrelated to +the read-only discovery use case and make meaningful permission review harder. + +## Code Constraints + +```yaml +version: 1 +eligibility: eligible +reason: "Pilot's required native target set has a stable release-workflow anchor." +rules: + - id: pilot-keeps-linux-arm64-release + kind: require_pattern + path_glob: ".github/workflows/native-publish.yml" + pattern: 'target: aarch64-unknown-linux-gnu' + message: "Pilot distribution requires a Linux arm64 native asset." + - id: pilot-keeps-macos-amd64-release + kind: require_pattern + path_glob: ".github/workflows/native-publish.yml" + pattern: 'target: x86_64-apple-darwin' + message: "Pilot distribution requires a macOS amd64 native asset." +``` + +## Related Decisions + +- adr-098 +- adr-121 + +## Related Requirements + +- asdecided-pilot-app-distribution diff --git a/decisions/designs/pilot-local-app-release.md b/decisions/designs/pilot-local-app-release.md new file mode 100644 index 00000000..897cc2e2 --- /dev/null +++ b/decisions/designs/pilot-local-app-release.md @@ -0,0 +1,92 @@ +--- +schema_version: 1 +id: RAC-01K8P7A3M7QZ +type: design +--- +# Pilot Local App Release + +## Context + +ADR-125 selects Pilot's signed local App Store. This design defines the release +prerequisite and the later catalogue handoff without adding a hosted AsDecided +service or maintaining a hand-written Pilot adapter. + +## User Need + +A Pilot user needs one discover-install-call flow that reads engineering +decisions from a repository already on their machine. They need clear authority +and integrity signals before allowing an adapter to execute a binary and read a +repository. + +## Design + +The Core release matrix builds `decided` and `decided-mcp` natively on GitHub's +hosted amd64 and arm64 runners for both Linux and macOS. Archive names continue +to use Rust target triples so Pilot submission automation can map them without +guessing host architecture. + +After that release exists, Pilot's official `pilot-app` generator receives a +CLI specification with four exact asset URLs and SHA-256 values. It generates +the IPC adapter, manifest, help method, bundle, and catalogue submission. The +app exposes a small surface: + +- `asdecided.help` — local method and parameter discovery; +- `asdecided.retrieve` — `decided retrieve --json`; +- `asdecided.validate` — `decided validate --json`; +- `asdecided.relationships` — relationship inspection over the repository. + +No passthrough method is included. The submission's product demo starts with a +retrieval against a repository path and explains that the path remains local. + +## Constraints + +- Pilot's generator and verifier are the authority for adapter shape; Core does + not vendor or fork the IPC implementation. +- Release archives must exist before their URLs and hashes can be committed to a + Pilot submission. +- The app may read only repositories available to the local Pilot node. +- A source-level `proc.exec` implementation is not sufficient evidence of + deployed compatibility; the release gate includes a real node. + +## Rationale + +Native hosted runners avoid cross-compilation and produce target-labelled +archives through the existing release workflow. Generating the thin Pilot layer +keeps ownership of its evolving IPC and manifest details with Pilot while +AsDecided owns only the curated command mapping and product claims. + +## Alternatives + +- **Cross-compile from one Linux runner:** rejected because macOS targets need + Apple tooling and native runners make the provenance easier to inspect. +- **Commit an app spec with placeholder hashes:** rejected because it cannot be + verified or submitted and creates configuration that appears shippable. +- **Hand-write a Rust Pilot IPC adapter:** rejected because it duplicates the + supported generator and creates a new protocol maintenance surface. + +## Accessibility + +The catalogue description and product demo use plain text, copyable commands, +and explicit parameter names. Success and errors must be represented in JSON, +not by colour or terminal formatting alone. + +## Style Guidance + +Lead with “engineering decisions on this machine,” not transport mechanics. +Use “local,” “read-only,” and “deterministic” precisely. Avoid “hosted,” “cloud +knowledge base,” and claims that Pilot itself enforces AsDecided decisions. + +## Open Questions + +- What is the narrowest Pilot filesystem grant that still permits a user-chosen + repository path? +- Which relationship command shape gives Pilot callers stable JSON without + exposing arbitrary CLI arguments? + +## Related Decisions + +- adr-125 + +## Related Requirements + +- asdecided-pilot-app-distribution diff --git a/decisions/requirements/asdecided-pilot-app-distribution.md b/decisions/requirements/asdecided-pilot-app-distribution.md new file mode 100644 index 00000000..d9e940ae --- /dev/null +++ b/decisions/requirements/asdecided-pilot-app-distribution.md @@ -0,0 +1,74 @@ +--- +schema_version: 1 +id: RAC-01K8P7A3M6QZ +type: requirement +--- +# REQ-AsDecided-Pilot-App-Distribution + +> The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY in this document are +> to be interpreted as described in BCP 14 (RFC 2119, RFC 8174) when, and only +> when, they appear in all capitals. + +## Status + +Accepted + +## Problem + +Pilot users cannot discover and install AsDecided through Pilot's local App +Store, while its service-agent model would require AsDecided to host private +repository knowledge. Distribution must preserve local execution and ship a +complete, verifiable native asset set. + +## Requirements + +- [REQ-001] AsDecided's Pilot identity MUST be `io.pilot.asdecided` and MUST be distributed as a local App Store app rather than an always-on service agent. +- [REQ-002] One immutable AsDecided release MUST provide native `decided` assets for macOS and Linux on both amd64 and arm64 before a catalogue submission is made. +- [REQ-003] Every submitted asset and generated adapter bundle MUST be pinned by SHA-256 and covered by Pilot's signed manifest and catalogue verification flow. +- [REQ-004] The Pilot method surface MUST be curated and read-only and MUST NOT provide arbitrary CLI passthrough, scaffolding, migration, rename, sharing, or other mutation commands. +- [REQ-005] Calls MUST identify the repository they read, and the generated manifest MUST declare the filesystem and `proc.exec` authority required to service those calls. +- [REQ-006] A release candidate MUST pass Pilot template validation, bundle verification, catalogue validation, and a real-node smoke test covering install, help, and deterministic retrieval. +- [REQ-007] Product copy MUST state that the app executes locally and MUST NOT imply that Pilot or AsDecided receives, hosts, or indexes the user's corpus. + +## Acceptance Criteria + +- A GitHub Release contains `asdecided-x86_64-unknown-linux-gnu.tar.gz`, + `asdecided-aarch64-unknown-linux-gnu.tar.gz`, + `asdecided-x86_64-apple-darwin.tar.gz`, and + `asdecided-aarch64-apple-darwin.tar.gz`, each containing `decided`. +- The generated app exposes only its documented help, retrieval, validation, + and relationship-inspection methods. +- `pilot-app validate` and bundle verification pass with exact release asset + hashes. +- A clean Pilot node installs the catalogue candidate and returns a valid + retrieval response from a local fixture corpus without a network corpus + dependency. + +## Success Metrics + +- `pilotctl appstore install io.pilot.asdecided` installs and starts on all four + supported Pilot OS/architecture combinations. +- Repeated retrieval against unchanged local input returns equal output through + the Pilot adapter and direct `decided` CLI. + +## Risks + +- Pilot's App Store is young and may change its manifest or IPC contracts. +- The generated adapter could broaden authority beyond the curated surface. + Manifest and generated-source review are mandatory before signing. + +## Assumptions + +- Pilot deploys its current `proc.exec` support to the nodes used for release + verification. +- Pilot's catalogue accepts publisher-provided Rust binaries as native assets + behind its generated CLI adapter. + +## Related Decisions + +- adr-125 +- adr-098 + +## Related Requirements + +- rac-release-versioning