feat(Porthole): add on-device investigations and phone-to-PR workflow

[kyleve]

Posted by an AI agent on kyleve’s behalf.

Summary

• User-facing: Add Porthole to the activated developer menu in every Where build. A drift detail preserves its selected issue and day.
• User-facing: Add manual exploration, source navigation, linked evidence, action forms, focused context graphs, read observations, and a JavaScript console.
• User-facing: Add direct OpenAI and Anthropic investigations with diagnostic consent, Keychain credentials, durable conversations, and reviewed live actions.
• User-facing: Add a separate GitHub workspace for fixed-base edits, patch/test review, approved draft publication, and CI status from the phone.
• Internal: Share one execution boundary across the phone, Mac Catalyst client, CLI, and MCP. Inventory first-party source and generate supported calls.

Why

A screen provides the starting evidence for an investigation. Porthole connects that screen to its current state, source, services, and compiled APIs.
The flight/drift path exposes ordinary exploration and copied-input replay through production detectors.
It distinguishes current observations, reproduced results, and inference without claiming an unrecorded execution history.

This extends the remote debugging concepts in #131 into an independent on-device workflow.

Architecture

The application creates one runtime and attaches its existing services as scopes become available.
It never opens another live Where store. Scope generations invalidate handles and delayed results after replacement, logout, or disablement.

Every client uses the same approval policy. Classified reads run directly. Unknown effects and live mutations require approval for the exact call and arguments.
Durable receipts prevent automatic repetition of uncertain mutations. Cancellation requests native cancellation and does not imply rollback.

Generated adapters compile within adopting modules through the selected private-access route.
A paired check builds original source without private-access flags or binding bodies under matching compiler settings.
Source archives preserve exact content and hashes. Coverage separates callable, inspectable, unsupported, inactive, source-only, and excluded entries.
Synchronous metadata batches on the registry actor prevent repeated coroutine cleanup paths during compilation.
The app and extensions use one aggregate library product for their shared modules. Runtime activation remains at the existing composition roots.
Generated enum inspection reads the active case and payloads without application getters, encoders, or Mirror.

QuickJS-NG 0.16.2 is statically compiled without shell or operating-system modules.
Its serial executor enforces memory and interruption limits. The provider boundary uses swift-ai-sdk 0.3.0.
Porthole owns diagnostic consent, evidence, conversations, operation journals, and restoration.

Repository edits use a fetched fixed commit and a separate local workspace. Installed dirty-build changes remain separate evidence.
The phone shows source differences, the proposed patch, tests, description, and validation state.
Publication records uncertainty before network effects and reconciles the same proposal on retry.
Personal diagnostic evidence requires explicit selection. Swift changes take effect in a subsequent build.

Remote access requires separate activation, certificate-pinned TLS 1.3, mutual authentication, and a short-lived single-use enrollment invitation.
Revocation closes active sessions. Local and remote observations share bounded sampling and scope ownership.

Review focus

• Private bindings, actor ownership, complete coverage, and the original-source compiler guard.
• Shared approval, cancellation, stale-handle rejection, and uncertain-operation recovery.
• Fixed-base GitHub edits, publication identity, credential isolation, and diagnostic consent.
• Where composition, modal presentation, retained screen origin, and unchanged production detector behavior.

Compatibility and limits

The short-code pairing protocol is replaced. Clients must enroll again.
Existing DEBUG-only developer destinations keep their compilation gates.
Porthole's trusted control-plane modules retain source-only coverage. Credential machinery and third-party internals remain outside automatic invocation.
Unsupported signatures carry explicit reasons. Unknown receiver isolation, inferred property types, and unbound generics account for the largest rejected groups.
Inventory covers explicit declarations; function locals, synthesized macro members, and implicit memberwise initializers are outside it.
Collision preflight covers supported unconditional declarations across files. Conditional collisions and other semantic ambiguity remain compiler checks.
Arbitrary live-object cloning and historical recording remain outside this milestone.
All-build availability remains the product target. Compiler tests do not establish App Review acceptance.

Testing

Check	Recorded result
Generator	./test --porthole-generator --skip-architecture: 48 tests / 8 suites passed. Real Swift 5/6 fixtures cover optimization, DEBUG conditions, private calls, enum inspection, and rejected actor access.
Native runtime and clients	./test --porthole-host --skip-architecture: 274 tests / 71 suites passed, including default-request assertions for Astra. The certificate package passed 2 tests / 1 suite.
Full iOS units	2,472 tests / 439 suites passed across 27 bundle runs after aggregate packaging. Includes the three snapshot-report regressions; two existing string-inflection expectations remain known issues.
Selected snapshots	18 suites passed with recording disabled in 401.809 seconds; no missing references. Visual review covered 76 Porthole references, including 31 revised references. The documented full-menu AX5 native-track capture artifact remains.
Mac Catalyst	Release compilation passed in 55.292 seconds; retained app: 30,547,634 logical bytes. Static load/resource checks and a limited live smoke covered credits and malformed-invitation rejection.
Application compiler paths	Debug, Beta, and Release iPhoneOS original/instrumented compilation passed for all 19 adopting modules under matching settings. Baselines passed in all three configurations.
Python tooling and packaging	132 Python tests passed in 18.511 seconds. Release inspection and separate Beta/Debug app-and-pair checks passed for shared metadata, resources, and app-only App Intents.
Repository checks	Final attribution is current: Where 17 works, Porthole 10. Agent synchronization completed; both final Swift files passed formatting. Architecture, SF Symbols, and string catalogs passed at their recorded checkpoints.

The initial Debug pipeline exited 1 after successful compilation because its checker selected a Mac build-directory framework before the embedded copy.
The applied correction excludes only the verified sibling build runpath, requires an in-app fallback, and records the exclusion.
Corrected post-build checks passed; the initial failed result remains preserved. No Swift recompilation was needed.
Subsequent Swift edits only add native request assertions and correct a preference comment; production behavior is unchanged.

The final device-SDK bundles contain these regular-file logical bytes:

Configuration	Baseline	Porthole	Difference
Release	150,142,312	143,075,989	−7,066,323
Beta	150,129,553	143,075,487	−7,054,066
Debug	267,097,699	245,088,016	−22,009,683

These comparisons include shared-library packaging and preserve embedded source/coverage with zero redundant standalone catalogs.
Each comparison uses matching SDK, Xcode, architecture, optimization, and compilation mode. These are logical-byte differences between builds.
They do not measure download size, launch time, or application memory.
Static packaging checks do not execute extensions or shortcuts. Cross-build checks exclude opaque compiled-asset payload hashes and NLU internals.
App Intents comparison normalizes only accepted input-type ordering for the two year parameters; raw metadata remains preserved.

The retained Release inventory contains 28 module records, 16,505 entries, and 795 source files with matching archived hashes.
The 19 adopting modules contain 5,498 callable plans, 1,609 descriptive entries, and 6,435 unsupported entries.
Other records contain source-only or excluded entries. These plans are not active-handler counts or proven phone invocations.
Inactive conditional entries remain visible; runtime discovery separately classifies installed handlers.

External acceptance

Remaining simulator compiler pairs still need qualification.
The user deferred phone installation and all physical/live-phone checks until the phone is available again.
These checks include the installed-app walkthrough, optimized private calls, iPhone–Mac pairing, GitHub device authorization/publication, and launch/memory measurements.
OpenAI's planned live check uses gpt-6-astra after secure key entry on the phone. Anthropic also needs an API key.
Porthole Debugger is registered and installed for kyleve/Stuff only; live draft publication, retry reconciliation, and CI display remain unverified.
App Review acceptance remains an external requirement.

Native protocol tests, unsigned device-SDK compilation, source compatibility review, and synthetic snapshots do not establish these checks.