Slice 5a: rust-core architecture docs + validation reports

docs/architecture/adapter-contracts.md

@@ -0,0 +1,82 @@
+# Adapter Contracts: Native Shell Boundaries
+
+## Purpose
+Define the interface boundary between the shared Rust core and platform-native shells.
+This contract keeps policy and orchestration deterministic while allowing each OS shell
+to implement its own UI, permissions, and device capabilities.
+
+## Adapter Surfaces
+
+### 1. Auth Adapter
+- Acquire and refresh authenticated user session from platform shell credentials.
+- Required fields:
+  - `workos_user_id`
+  - `session_token`
+  - `expires_at`
+- Failure must be explicit and recoverable by host UI.
+
+### 2. Entitlement Adapter
+- Fetch entitlement snapshot from worker API and map to `EntitlementState`.
+- Required fields:
+  - entitlement status (`none`, `trial`, `active`, `canceled`, `expired`)
+  - period boundaries
+  - cap metadata
+
+### 3. Capture Adapter
+- Capture current screen context for active turn.
+- Contract output:
+  - `display_id`
+  - image bytes + encoding metadata
+  - capture timestamp
+- Capability gating:
+  - if unavailable, shell must surface a permission/status message before turn start.
+
+### 4. Hotkey Adapter
+- Listen for global push-to-talk start/end signals.
+- Contract events:
+  - `hotkey_pressed`
+  - `hotkey_released`
+
+### 5. Overlay Adapter
+- Render pointer and guidance affordances for `[POINT:x,y:label:screen]` directives.
+- Contract methods:
+  - show pointer
+  - animate to coordinate
+  - hide pointer
+
+### 6. Audio Adapter
+- Stream input audio chunks to realtime transport and play output audio deltas.
+- Contract events:
+  - microphone stream started/stopped
+  - playback started/stopped
+
+### 7. Permission Adapter
+- Expose OS permission status used by shell readiness checks.
+- Minimum statuses:
+  - screen capture permission
+  - accessibility/hotkey permission
+  - microphone permission
+
+## Core-to-Shell Handshake
+1. Shell acquires auth session.
+2. Shell fetches entitlement snapshot.
+3. Shell asks Rust policy if turn can start.
+4. If allowed, shell starts capture/hotkey/audio and emits realtime events.
+5. Rust realtime state machine governs turn lifecycle transitions.
+
+## Bootstrap Scope (Phase 4)
+- Current shell bootstrap crates use mocked host adapters to validate:
+  - auth session acquisition
+  - entitlement-driven turn permission
+  - turn-start lifecycle via `core/realtime` replay
+
+## Development Status
+- Windows shell now routes through explicit adapter modules for:
+  - capture
+  - hotkey
+  - overlay
+  - audio input/output
+  - permissions
+- Linux shell now routes through explicit adapter modules for the same surfaces.
+- Capability-aware gating is enforced before turn start; critical adapter blockers abort flow with explicit reasons.
+- Final-phase work focuses on runtime validation on real platform environments.

docs/architecture/adr-001-rust-core-native-shells.md

@@ -0,0 +1,36 @@
+# ADR-001: Adopt Rust Core + Native Platform Shells
+
+## Status
+Accepted
+
+## Date
+2026-04-16
+
+## Decision
+Adopt a shared Rust core for deterministic logic (policy, skills, orchestration) while keeping native UI/capability shells per platform.
+
+## Drivers
+1. Reduce logic duplication across future desktop/mobile clients.
+2. Preserve platform-specific performance and capability integrations.
+3. Minimize release risk by incrementally migrating from existing macOS host.
+
+## Alternatives Considered
+1. Full cross-platform UI rewrite first.
+- Rejected because it introduces high migration risk and delays policy/orchestration reuse.
+
+2. Keep all logic inside each platform shell.
+- Rejected because policy/orchestration drift and maintenance cost increase over time.
+
+3. Backend-only policy with thin clients.
+- Rejected because core turn orchestration and offline-ish local behavior still require deterministic client logic.
+
+## Consequences
+1. FFI/versioning contracts become a first-class maintenance concern.
+2. Platform shell teams remain responsible for native capture/hotkey/overlay behavior.
+3. Migration can proceed in phases with fallback paths to keep shipping continuity.
+
+## Follow-ups
+1. Keep ABI mapping docs in sync between Rust and Swift.
+2. Expand fixture-driven parity tests as new modules move to Rust.
+3. Define Linux desktop environment support scope before adapter phase.
+

docs/architecture/capability-matrix.md

@@ -0,0 +1,25 @@
+# Capability Matrix
+
+Status key:
+- `ready`: implemented in current host
+- `planned`: defined in migration plan, not yet implemented
+- `unknown`: requires discovery spike
+
+| Capability | macOS (current Swift host) | Windows shell target | Linux shell target | Rust core role |
+| --- | --- | --- | --- | --- |
+| Auth session lifecycle | ready | planned | planned | shared contracts + validation |
+| Entitlement checks | ready | planned | planned | deterministic policy engine |
+| Trial/cap accounting | ready | planned | planned | deterministic transitions |
+| Admin allowlist policy | ready | planned | planned | stable WorkOS-user-id decision path |
+| Realtime orchestration | ready | planned | planned | shared state machine |
+| Prompt composition | ready | planned | planned | shared skill/prompt module |
+| Screen capture | ready | planned | planned | capability flag + result normalization |
+| Global push-to-talk hotkey | ready | planned | planned | capability flag + event contracts |
+| Overlay pointing UI | ready | planned | planned | event contracts only |
+| App update channel | ready | planned | planned | release metadata conventions |
+
+## Notes
+- Capture, hotkey, and overlay stay native because they depend on OS-specific primitives.
+- Rust core should only define contracts, state transitions, and deterministic behavior.
+- Platform adapters should report capability availability so UX can degrade gracefully.
+

docs/architecture/core-boundaries.md

@@ -0,0 +1,40 @@
+# Core Boundaries
+
+This document defines migration boundaries between the existing Swift host and the new shared Rust core.
+
+## Goal
+- Keep shipping the macOS host while extracting deterministic, reusable logic to Rust.
+- Preserve native platform capability integrations in host shells.
+
+## Ownership Split
+
+### Remains in Native Shells (Platform-specific)
+- Screen capture API integration
+- Global hotkey registration/listening
+- Overlay/window composition and animation
+- Permission prompts and OS dialogs
+- Device-level audio session details
+
+### Moves to Rust Core (Platform-agnostic)
+- Entitlement/trial/cap decision logic
+- Admin policy behavior
+- Skill prompt composition and budget logic
+- Realtime lifecycle orchestration state machine
+- Shared telemetry event schema and aggregations
+
+## Contract Model
+- Native shell gathers runtime inputs (user ID, entitlement status, usage counters, current capabilities).
+- Rust core returns deterministic decisions/events.
+- Native shell executes side effects.
+
+## Migration Sequence
+1. Policy extraction
+2. Skills/prompt extraction
+3. Realtime state extraction
+4. New platform shell onboarding
+
+## Non-goals for Initial Migration
+- Replacing macOS UI layer
+- Replacing platform capture/hotkey/overlay with cross-platform abstractions in one step
+- Forcing Linux/Windows full visual parity before core parity
+

docs/architecture/final-phase-validation-report.md

@@ -0,0 +1,53 @@
+# Final Phase Validation Report
+
+Date: 2026-04-18
+Branch: `feature/skills-bridge-swift`
+
+## Scope
+Final-phase validation of Rust core migration artifacts with adapter-backed shell binaries.
+
+Validated areas:
+1. Workspace formatting/check/test integrity.
+2. FFI build output.
+3. Linux and Windows shell baseline turn flow.
+4. Release-script static guard.
+5. Adapter capability mapping unit tests.
+
+## Commands Executed
+```bash
+cargo fmt --all -- --check
+cargo check --workspace
+cargo test --workspace
+cargo build -p skilly-core-ffi
+cargo run -p skilly-linux-shell -- --smoke
+cargo run -p skilly-windows-shell -- --smoke
+bash -n scripts/release.sh
+```
+
+## Results
+- `cargo fmt --all -- --check`: pass
+- `cargo check --workspace`: pass
+- `cargo test --workspace`: pass
+  - includes shell adapter unit tests:
+    - windows: 3 tests passed
+    - linux: 4 tests passed
+- `cargo build -p skilly-core-ffi`: pass
+- `cargo run -p skilly-linux-shell -- --smoke`: pass
+  - completed phase with capability snapshot reported
+- `cargo run -p skilly-windows-shell -- --smoke`: pass
+  - completed phase with capability snapshot reported
+- `bash -n scripts/release.sh`: pass
+
+## Key Outcomes
+1. Adapter-backed shells now validate capability gating logic in tests and smoke execution.
+2. Rust policy/skills/realtime/ffi modules pass full workspace validation.
+3. CI workflow now includes all required gate categories:
+   - rust core check
+   - rust core test
+   - ffi smoke
+   - shell smoke
+   - mac release guard
+
+## Remaining Manual/Platform Work
+1. Xcode runtime validation for Swift bridge behavior (policy/skills/realtime) in live app.
+2. Native host-app runtime verification on real Windows/Linux desktop environments beyond CLI shell binaries.

docs/architecture/realtime-production-like-traces-report.md

@@ -0,0 +1,29 @@
+# Realtime Production-Like Traces Expansion Report
+
+Date: 2026-04-18
+Branch: `feature/skills-bridge-swift`
+
+## Scope
+Expanded deterministic replay fixtures to improve production-like lifecycle coverage for `core/realtime`.
+
+## Changes
+- Updated `core/realtime/fixtures/replay_traces.json`.
+- Trace corpus expanded from 3 traces to 20 traces.
+- Added mixed-path coverage including:
+  - sequential multi-turn completion
+  - audio playback transition paths
+  - error and recovery loops
+  - reset-heavy flows
+  - late error after completed phase
+  - turn restart before commit
+
+## Verification
+```bash
+cargo test -p skilly-core-realtime
+cargo test --workspace
+```
+
+Both commands passed with the expanded fixture corpus.
+
+## Remaining Work
+1. Continue appending fixtures from newly observed production telemetry patterns over time.

docs/architecture/runtime-validation-report-2026-04-18.md

@@ -0,0 +1,83 @@
+# Runtime Validation Report
+
+Generated (UTC): 2026-04-18
+Branch: `feature/skills-bridge-swift`
+Commit: `9b47766`
+
+Source template: `docs/architecture/runtime-validation-signoff-template.md`
+
+## Signoff Metadata
+- Owner:
+- Reviewer:
+- Validation date:
+- Branch:
+- Commit SHA:
+- Build identifiers (if applicable):
+
+## Decision
+- Overall status: `approved` | `blocked`
+- Blocking notes:
+- Follow-up ticket(s):
+
+## Required Runtime Lanes
+| Lane | Status (`pass`/`fail`/`n-a`) | Evidence link (video/log/screenshot) | Notes |
+| --- | --- | --- | --- |
+| macOS host app (Rust lane via `SKILLY_RUST_CORE_DYLIB_PATH`) |  |  |  |
+| macOS host app (Swift fallback lane; Rust dylib disabled) |  |  |  |
+| macOS host app (packaged Rust FFI artifact consumed) |  |  |  |
+| Windows native host app runtime (real desktop environment) |  |  |  |
+| Linux native host app runtime (real desktop environment) |  |  |  |
+| iOS host app simulator runtime (generated SDK integration) |  |  |  |
+| Android host app emulator runtime (generated SDK integration) |  |  |  |
+
+## Policy Scenario Parity (Rust lane vs Swift lane)
+| Scenario | Rust lane result | Swift lane result | Match (`yes`/`no`) | Notes |
+| --- | --- | --- | --- | --- |
+| Trial under cap -> allowed |  |  |  |  |
+| Trial exhausted -> blocked (`trialExhausted`) |  |  |  |  |
+| Active under cap -> allowed |  |  |  |  |
+| Active over cap -> blocked (`capReached`) |  |  |  |  |
+| Admin over cap/expired -> allowed |  |  |  |  |
+| Canceled valid access under cap -> allowed |  |  |  |  |
+| Canceled valid access over cap -> blocked (`capReached`) |  |  |  |  |
+
+## Skill Prompt Parity (Rust lane vs Swift lane)
+| Scenario | Rust lane result | Swift lane result | Match (`yes`/`no`) | Notes |
+| --- | --- | --- | --- | --- |
+| Full vocabulary budget |  |  |  |  |
+| Vocabulary trimming applied |  |  |  |  |
+| Completed-stage history included |  |  |  |  |
+| Missing-current-stage fallback |  |  |  |  |
+| Pointing mode variants (`always`, `when-relevant`, `minimal`) |  |  |  |  |
+
+## Realtime Lifecycle Parity (Rust lane vs Swift lane)
+| Scenario | Rust lane result | Swift lane result | Match (`yes`/`no`) | Notes |
+| --- | --- | --- | --- | --- |
+| `turn_started -> audio_capture_committed -> audio_playback_started -> response_completed` |  |  |  |  |
+| `turn_started -> audio_capture_committed -> session_error` |  |  |  |  |
+| `completed -> session_reset` |  |  |  |  |
+| Invalid ordering rejection (`turn_started -> response_completed`) |  |  |  |  |
+
+## Windows/Linux Host-App Runtime Checklist
+- Windows auth + entitlement + turn-start flow validated in native host app:
+- Windows capture/hotkey/overlay/audio/permissions behavior validated:
+- Linux auth + entitlement + turn-start flow validated in native host app:
+- Linux capture/hotkey/overlay/audio/permissions behavior validated:
+- Known platform-specific degradations documented:
+
+## iOS/Android Host-App Runtime Checklist
+- iOS host app compiles with generated Swift SDK:
+- iOS runtime exercise of policy and realtime API completed:
+- Android host app compiles with generated Kotlin SDK:
+- Android runtime exercise of policy and realtime API completed:
+- ABI/library loading behavior documented for both platforms:
+
+## Packaged Artifact Consumption Checklist
+- `dist/rust-ffi/*.tar.gz` unpack + load test executed:
+- `dist/mobile-sdk/*.tar.gz` unpack + sample integration test executed:
+- Checksum verification completed:
+
+## Evidence Attachments
+- Command transcript links:
+- Screen recordings:
+- Crash logs / diagnostics: