iOS embedded kcp — plan

Status: 2026-10-30. Lead: atirc-ios-client-dev.

Canonical cross-repo plan: socialweb-computer-kcp docs/plans/0038-ios-embedded-kcp.yaml (plan owner linux-kcp). This file is the app-side milestone plan; 0038 is the system view. Item mapping: M1/M2 = I1-BOOT + I2-RUNTIME (done), M2 = I3-PERSIST, M5 = I5-OAUTH, M3 = I4-SOCIALWEB-IOS (linux-kcp) + I6-POLICY-SANDBOX (linux-kcp) + I7-AGENTS, M4 = I8-ASK-OWNER, device e2e = I9 (linux-kcp).

Goal: run the real kcp control plane and the socialweb requester inside the AT-IRC iOS app so the app can launch and manage agents through the same market request flow the web page uses.

Architecture (locked decisions)

• One Go runtime per process. A combined AtircGo.xcframework (package github.com/kcp-dev/kcp/contrib/wasm/ios/atircgo, built with gomobile) contains both the app's IRC helpers and the kcp bridge. Linking a second gomobile framework (e.g. a separate KCPGo) crashes at launch: duplicate Go runtimes. Never add another Go framework; extend atircgo.
• No sockets. contrib/wasm/real boots kcp over an in-process net.Pipe listener/dialer with memory:// storage. The apiserver never binds a port.
• Storage. The patched apiserver memory backend (KCP_PATCH_MODE=native, k8s.io/apiserver replaced with the patched copy) plus contrib/wasm/storage snapshot/restore. kcp root lives in Application Support/kcp; the service-account key is ECDSA P-256.
• Memory. KCP_MEMORY_STORAGE=main, KCP_LOW_MEMORY=1 (watch cache off, short watch history), debug.SetGCPercent(25) after ready, and a debug.SetMemoryLimit(1 GiB) soft limit. iOS jetsam is the limit, not wasm's tab heap; measure on a device and raise the limit if the requester needs it.
• Bridge API (Swift): AtircgoKCPStart(root, snapshot), AtircgoKCPRequest(method, path, headersJSON, body), AtircgoKCPSnapshot(), AtircgoKCPReady(), AtircgoKCPStatus(), AtircgoKCPStop().
• Build. Regenerate the native patched modfile, then gomobile bind -target=ios,iossimulator -ldflags="-s -w" into GoLib/AtircGo.xcframework. The app links AtircGo and -lresolv (Go's BIND resolver symbols). Build artifacts are large; keep the release dirs pruned.

Milestones

1. M1 — boots (done). kcp boots in-process on darwin and iOS; /version and /apis return 200; combined framework builds; app compiles and shows a kcp status bar.
2. M2 — simulator e2e (done). Launch in simulator, kcp reaches ready, status bar shows kcp state. Snapshot persistence implemented: save after ready and on scenePhase background to Application Support/kcp/snapshot.b64 (1.3 MB after a cold boot), restore on launch, fail-closed drop of an unreadable snapshot. Verified across terminate/relaunch; kcp ready again.
3. M3 — socialweb + agents (I4 integrated). The Agents tab starts kcp lazily (8.7 s in the simulator), then the embedded socialweb requester against the same kcp (ready ~2.7 s later), and shows "socialweb requester ready". The Agents API creates the session EphemeralInfra and applies ComputeContract entries with spec.agent; Release/revoke remain for I7. Launching is still unavailable/denied until (a) linux-kcp's I6 policy sandbox runs the requester's tangled-vouch, and (b) pkg/embedded exposes the page's PutContractSecrets (the ATIRC_TOKEN bundle written before the contract). Both requested.
4. M4 — ask-owner UI (done, runtime pending deploy). Pending list, answer sheet, availability toggle, decided/ADR rows, local notification when mode is available. Uses the account-level minted atirc token per path (a). Live calls 401 until atirc-dev deploys the server change that adds the five ask NSIDs to the minted token scope.
5. M5 — OAuth scopes (done in simulator). iOS metadata and authorize request carry 28 scopes = exact requester-scope.txt (27, r131) plus rpc:chat.atirc.revoke?aud=did:web:irc.fedfork.com%23atirc; dedupe when socialweb rc133 generates revoke itself. Scripted alice sign-in in the simulator succeeded end to end (OAuth -> loopback -> DPoP -> mint, 28/28 granted). Device signing/TestFlight pending.

Workstreams and owners

• kcp core, framework build, app integration: atirc-ios-client-dev (lead).
• ask-owner iOS UI + notification: subagent ask-owner (scope now iOS-only; server/CLI owned by atirc-dev/atirc-ask).
• OAuth full scopes + Agents nav: subagent scopes-agents.
• Server XRPC (ask/answer/decide/questions/owner_mode), token scopes: atirc-dev / atirc-ask.
• Wasm reference flow (page) and native-overlay guidance: wasm; source tree /Users/johnandersen777/src/linux-kcp/kcp-wasm-mac is read-only.

Risks / open decisions

• Memory: watch cache off + GOGC 25; measure with a VM lifecycle. Watch jetsam.
• Snapshot size/write cost: write on a debounce (page uses >=15 s gap + 3 s trailing), never on every mutation.
• Background: iOS suspends the app; kcp and the requester stall. A release asked before suspension finishes on the next launch from persisted state; ask iOS for background time to finish it first (0038 agents decision).
• Policy: the requester runs requester-tangled-vouch; iOS has no deno, so it fails closed until linux-kcp's iOS policy sandbox provider (I6) sets PolicyEngine spec.sandbox with a Prober/Fenced condition. No contract is created while the policy cannot run.
• Credentials: ~/.aliceoa_bsky_social_source is sourced only inside the sign-in command; values never printed/logged/copied; sign-in URLs never posted.
• App repo is not a git checkout; keep edits local and coordinate files between the lead and subagents.

Verification

• Host smoke: go build -modfile=.go.memory.mod ./contrib/wasm/ios/cmd/kcpsmoke then run; expect real: ready, /version 200, /apis APIGroupList.
• Framework: gomobile bind ... atircgo; headers expose AtircgoKCP*.
• App: xcodebuild -project AT-IRC.xcodeproj -scheme AT-IRC -destination 'generic/platform=iOS Simulator' build; install/launch in the booted simulator; screenshot status bar shows kcp: ready · <gitVersion>.