Mirror architecture

Mirror projects guest-provided scene state into a host rendering and review surface. Its control loop is asymmetric by design: native guest input drives; QMP and capture tools observe. Guest-provided state is the only input permitted to mutate the Mirror model.

flowchart LR U["Native input on guest"] --> APP["Target classic application"] APP --> EXT["Optional resident observation"] EXT --> G["NOW guest validates scene"] G --> H["Host Mirror model"] G -->|"mirror.invalidate hint"| C["Coalesced refresh"] C --> S["GuestWorkScheduler"] S --> G H --> R["Render and review"] Q["QMP / harness"] -.->|"observe only"| APP R -.->|"proposal, never synthetic truth"| U

Text equivalent: a person acts through native guest input. The resident component may observe the target; the NOW guest validates that state and sends it to the host; the host renders it for review. Invalidation hints coalesce a refresh admitted through the session scheduler. QMP observes the machine but does not become the product input path.

Admission, refresh, and publication

The session scheduler selects queued human work before queued ambient reads at the next safe boundary. It cannot interrupt guest work already executing, so the observable timing brackets distinguish admission wait, guest execution, settlement, and publication instead of collapsing them into one number.

mirror.invalidate is an additive, symmetric hint. It carries the session, overall and per-domain generations, source, loss count, and a quality of sampled, gap, or unknown. Hints coalesce rather than creating one read per event. Gaps and unknown quality force repair, and cadence polling remains the fallback when hints are absent. The host publishes only a coherent, current generation set and refuses stale enrichment.

Any measurement must prove the content plane armed in the stored artifact. An invocation log or an empty capture is not evidence that observation occurred.

Cross-machine file ownership

File dragging is a host-owned native drag around the semantic scene; it does not travel through ADB or the resident item-drag path. A guest item crossing the Mirror or Continuity display edge becomes an NSFilePromiseProvider, using its original Mirror icon when the asset atlas has one. The promise redeems only after a host Finder or application drop. A host URL released over the Mirror, or carried through the configured Continuity edge, is resolved at that exact guest coordinate before bytes are offered.

CrossMachineFileTargeting converts scene hits to closed identities: desktop, an exact Finder HFS path, a live process serial number, or an application creator. MirrorFileTransferModel maps those identities onto optional mirrorSource and mirrorDrop fields on the existing symmetric file.get and file.offer family. The PPC guest independently resolves the source or destination before accepting, stages application drops in Downloads, and uses kAEOpenDocuments only after the checked receive has settled. A refused application retains the copied file and reports that outcome explicitly.

The first contract is copy-only, file-only, no-overwrite, and PowerPC-only. Mirror installs AppKit ownership directly on LiveMirrorView. Continuity installs a two-point transparent AppKit destination along the configured shared edge: native host drags retain their pasteboard while relative movement drives the guest target, and a held guest file crossing back releases the guest button before AppKit assumes the drag. Both modes converge on the same MirrorFileTransferModel; Continuity's ordinary non-file pointer gestures are unchanged when the mouse-down did not resolve an exact guest file.

Visual truth and profiles

Mirror remains a semantic renderer; an emulator framebuffer is the visual oracle, not an alternative model. mirror-render exposes the production RenderShot path for evidence tooling, and tools/mirror-oracle compares that output with SheepShaver or QEMU pixels by named regions. It never promotes a whole-screen similarity score into a fidelity claim.

Asset acquisition is one domain with three adapters: stopped-volume resource fork extraction, future read-only extraction from the connected guest, and bounded visual-oracle derivation. They converge on the same external, versioned pack/manifest/provenance contract; MirrorKit only consumes that contract. The connected adapter therefore extends the existing pack domain and shared parsers rather than becoming a new renderer or pixel protocol. Its implementation remains tracked by plans 017 and 021. No adapter sends framebuffer pixels through NOW's semantic wire.

For file-owned Finder art, the common adapter payload is deliberately small: exact classic path, FinderInfo bytes, and resource-fork bytes. The current stopped-volume adapter and future connected adapter both end at the same bytes-only decoder and version-0.3.0 manifest contract. Live session choice, permission, and pull receipts stay above that boundary; asset interpretation stays below it.

Derived chrome can join those domains through explicit proof rather than image copying. For the 8.6 Finder alias transform, the visual-profile adapter composes each independently extracted file icon over the proved desktop tile and accepts only the opaque residual whose target RGB agrees across every declared proof. MirrorKit then draws that private, versioned overlay locally.

Visual versioning is explicit at the tooling boundary. The initial platinum.macos-8.6.default profile records system, theme, screen/depth, calibration source, and asset policy. It does not claim that Mac OS 8.6 and 9.1 are identical. A later 9.1, localized, alternate-theme, or 68K profile must name its own evidence-backed deltas. The host already knows the connected guest's system version; profile selection can move into runtime policy after the first corpus establishes which deltas actually matter.

The first measured procedure is the Mac OS 8.6 Finder menu bar. Its 20-row bezel, asymmetric cap pixels, lower bevel, application divider and title baseline live in PlatinumMenuBar; Apple and Finder-owned bitmap marks stay in the external versioned asset pack. A profile-declared derivation copies those crops from an attributed native framebuffer without adding guest pixels to the semantic wire protocol or repository. With the OS 8.6 font/icon pack and those two chrome crops, the current comparison differs in 35 of 13,500 unmasked menu pixels, all within Charcoal “View”. The remaining bearing delta is kept visible: a trial use of FOND fractional family widths worsened other already-exact titles and was rejected. The extractor preserves that table as data, but the renderer does not globally enable an unproven spacing mode.

The same profile now declares its Mac OS Default desktop tile explicitly. Pack derivation promotes that declaration only after every RGB pixel in the profile's unobscured proof regions equals the origin-zero tiled asset; a one-pixel mismatch refuses the derived pack. The current color-correct native capture proves 69,160 of 69,160 background pixels. Mirror resolves a guest naming that pattern through the manifest to the sanitized desktop.png asset and records machine provenance. The resting Finder-desktop case now also has a state-proven target, deterministic replay on a second sealed clone, and a semantic scene containing its eight visible items. Control Strip remains a separately scored, unmodeled system-chrome region rather than pixels smuggled into the semantic scene.

The scheduler, invalidation, and generation behavior is tested locally. The 2,000 ms ambient-wait target on the PowerBook 1400c is not metal-verified.