Skip to content

facts.md

Latest commit

 

History

History
958 lines (852 loc) · 64.1 KB

facts.md

File metadata and controls

958 lines (852 loc) · 64.1 KB
Raw

TFTMAC Facts

CURRENT DEV AUTHORITY — 2026-09-11 America/Chicago. The DEV optimization/versioning records in project.md and CHANGELOG.md supersede older mutable DEV build, campaign, performance, and readiness claims below. Historical measurements retain their original dates and remain evidence for their recorded configuration only.

Authority date: 2026-09-11 America/Chicago Current DEV evidence through: 2026-09-11 terminal four-hour evidence-grounded incremental sweep; no candidate was promoted and latest performance winner remains DEV-B8-WIN-01 Purpose: preserve current facts and hard boundaries that future TFTMAC work must not casually reinterpret.

Mandatory current-authority reading and record-book rule

Before planning, running, changing, interpreting, or resuming any TFTMAC DEV optimization test, read the current versions of all three of these records:

  1. facts.md — hard project facts, safety boundaries, current authority pointers, and mandatory process rules.
  2. project.md — living project wiki: what TFTMAC/DEV is, current working winner, current runtime/client identity, current test series, and current optimization state.
  3. CHANGELOG.md — append-only DEV test/version ledger: exact tests already attempted, outcomes, metrics, integration YES/NO, reasoning, rollback state, and DEV-B8-WIN-## progression.

For the active results-first pass, also obey .clara/plans/ff2f318b-245d-418a-b86f-e07d55b19826/RECOVERY_CONSTRAINTS_2026-09-10.md.

LOCKED RECORD-BOOK POLICY: every completed DEV optimization test must update the current record books in the same work cycle. A test result is not considered fully recorded until CHANGELOG.md contains the exact result and integration decision and project.md reflects any change to current winner/state/version progression. Update facts.md whenever the result changes a current fact, hard boundary, mandatory rule, runtime/client identity, or authoritative current configuration. Do not copy transient measurements into facts.md merely because a test ran; facts stays concise and authoritative, while CHANGELOG.md retains the detailed test history.

LOCKED PROMOTION POLICY: continuous useful 60 FPS is the cumulative destination, not a per-candidate minimum. There is no fixed positive-gain percentage floor for retaining an optimization. VERIFIED, REPEATABLE NET IMPROVEMENT -> integrate it, assign/promote the next working DEV-B8-WIN-## identity, update project.md and CHANGELOG.md, and use that winner as the baseline for the next test. NOT VERIFIED / INCONCLUSIVE / REGRESSION -> log the exact result and reason in CHANGELOG.md, do not integrate it, keep/restore the latest verified winner in project.md, and move to the next candidate. A small regression in one secondary metric may be accepted when the overall measured system/gameplay result is better and no correctness, stability, compatibility, or severe-tail regression outweighs the gain. Small verified gains are intentionally retained so they can compound toward the 60-FPS target.

LOCKED LKG SEPARATION: the frozen LKG remains separate and immutable. The evolving DEV working winner is never allowed to silently rewrite the historical LKG/control evidence.

LOCKED AUTHORITY PRECEDENCE: facts.md is the first project-specific authority. project.md is the current living wiki and must agree with it. CHANGELOG.md is the detailed test/version ledger. Other plans, handoffs, SSOT/reference files, tests, captures, source comments, or historical documents do not silently override these records. If newer machine/runtime evidence conflicts with facts.md or project.md, treat that as an authority-staleness signal: validate the newer evidence first, update facts.md and project.md to the newly proven truth, then continue. Never choose a conflicting lower-level document over facts.md without first reconciling the authority records.

LOCKED PLAN/CHANGE FINALIZATION GATE: before finalizing any implementation plan, change scope, promotion decision, or completion claim, re-read the current facts.md and project.md, reconcile them against any newer evidence discovered during the work, and update them first if they are stale. A plan is not final while an unresolved factual conflict exists.

LOCKED CLEAN-WORKSPACE COMPLETION RULE: active implementation work may be dirty while it is in progress, but no selected managed change may be declared finalized or complete with accidental dirty state. Intended source/docs must be checkpointed/published; generated or transient artifacts must be restored, ignored, or removed from the worktree without destroying authoritative external evidence; final Git status for the selected change must be clean. Unrelated managed work must be preserved rather than destroyed to manufacture cleanliness.

LOCKED OVERNIGHTLAB EVIDENCE POLICY: OvernightLab is retained as a telemetry/provenance tool and must follow the current facts.md + project.md authority. Historical data is not discarded merely because CPU, RAM, or another secondary configuration value differs from the current winner; preserve requested/effective values and label such evidence non-comparable/data-only unless a valid matched comparison admits it. A wrong official-client identity or wrong selected game RHI/core pipeline for the intended test is a promotion disqualifier, but its already-recorded raw evidence remains forensic data. Resolved negative candidates stay logged and are not automatically rerun. The automatic OvernightLab baseline is the latest verified DEV winner, currently DEV-B8-WIN-01, never the frozen LKG unless an explicit historical comparator is requested.

This file separates durable product facts from mutable observations and historical results. A statement becomes a project fact only when it has direct machine, runtime, source, SQL, or user-acceptance evidence. Requested settings are not effective settings; presentation cadence is not Unreal FPS; a hypothesis is not a result.

Exact benchmark formulas, automatic full-run analysis, AI-readable output shape, and current findings live in benchmark.md.

Evidence vocabulary

Label Meaning
LOCKED Product or safety contract. Change only through an explicit, evidence-backed project decision.
VERIFIED CURRENT Directly observed on the current Mac, installed app, source tree, or live runtime. Mutable software/version facts must retain an observation date.
VERIFIED HISTORICAL Direct result from an earlier capture or campaign. Useful evidence, but not automatically transferable to the current M4/native runtime.
USER ACCEPTED/REJECTED Direct usability evidence supplied by the person playing TFT. It is decisive for playability but does not by itself identify a software boundary.
INFERRED Evidence-supported explanation that has not been observed at the claimed internal boundary.
UNKNOWN Not measured or not validly attributable. Never silently promote this to fact.

1. Host machine

Fact State Evidence
Computer VERIFIED CURRENT: Mac mini, model identifier Mac16,10, model number MU9D3LL/A system_profiler SPHardwareDataType, 2026-08-30
SoC VERIFIED CURRENT: Apple M4 system_profiler
CPU topology VERIFIED CURRENT: 10 physical/logical cores: 4 performance and 6 efficiency system_profiler; sysctl hw.physicalcpu, hw.perflevel*
GPU VERIFIED CURRENT: integrated Apple M4 GPU, 10 cores, Metal supported system_profiler SPDisplaysDataType
Unified memory VERIFIED CURRENT: 16 GB; exact hw.memsize is 17,179,869,184 bytes system_profiler; sysctl hw.memsize
CPU/GPU clock VERIFIED CURRENT BOUNDARY: this Mac does not expose a fixed project-controlled CPU or GPU MHz value through the audited system_profiler/sysctl fields. Frequency is not a TFTMAC emulator knob. Do not invent an 800 MHz or 1600 MHz virtual-GPU fact. Live host audit
Power VERIFIED CURRENT at audit: AC power pmset -g batt
Thermal/power warnings VERIFIED CURRENT at audit: no thermal, performance, or CPU-power warning had been recorded pmset -g therm
macOS VERIFIED CURRENT: macOS 26.6.2, build 25G83; Darwin 25.6.0 sw_vers; system_profiler
Architecture VERIFIED CURRENT: arm64 Xcode/Swift target and stack lock
Xcode VERIFIED CURRENT: Xcode 26.6, build 17F113, authoritative path /Applications/Xcode-26.6.0.app/Contents/Developer xcodebuild -version; ssot/STACK.lock.yaml
Swift VERIFIED CURRENT: Apple Swift 6.3.3, arm64 macOS target swift --version

The current Mac is not the same host as the older M1 Max performance campaign. Historical M1 Max results remain valid for their recorded environment, but they must never be presented as measurements of this M4 Mac mini.

2. Product identity and user experience

  • LOCKED: TFTMAC is its own native macOS application. It is not a Clara app, does not ship through Node, and does not depend on a Clara service to play.
  • LOCKED: the application uses AppKit window behavior, a native Metal-backed display, normal macOS menus and window controls, and native macOS fullscreen.
  • LOCKED: the Android Emulator's Qt window stays hidden in normal operation.
  • LOCKED: the complete Android display is shown aspect-correctly. The normal guest/output target is 1920×1080; a 16:9 fullscreen content region is filled.
  • LOCKED: no scrcpy or encoded-video path is the production display path.
  • VERIFIED CURRENT: bundle identifier com.flashls1.tftmac.
  • VERIFIED CURRENT: installed release /Applications/TFTMAC.app, version 2.3.0, build 8, arm64. Capture 2026-08-31T21-39-18.396Z-fe34e3a1-fb91-44eb-804f-4ca8519dfc31 directly proves authorized ADB, official TFT PID observation, exact GameActivity SurfaceView selection, automatic graphics-run admission, COMPLETE stack receipts, and frame-to-run/hash/window/receipt linkage.
  • VERIFIED CURRENT: /Users/flash/Desktop/TFTMAC.app points to the signed /Applications/TFTMAC Control Launcher.app, which launches the unchanged /Applications/TFTMAC.app and may unlock only emulator-5582. Direct launch of /Applications/TFTMAC.app remains the rollback.
  • VERIFIED CURRENT: LSSupportsGameMode=true is present in the installed bundle. This establishes Game Mode eligibility, not proof that macOS activated it during a particular match.
  • VERIFIED CURRENT: the official full-bleed penguin-samurai icon is embedded. The source, 1024-pixel output, and ICNS hashes are frozen in ssot/runtime-authority.json.
  • VERIFIED HISTORICAL RELEASE ACCEPTANCE: Build 8 was signed with the local TFTMAC Local Code Signing identity and passed deep/strict verification when the release receipt was created. It is not notarized for public distribution.
  • VERIFIED TIMESTAMPED HOST AUDIT (2026-08-31T23:13:30Z): the installed TFTMAC executable and emulator-host hashes still match that Build 8 receipt, but the login keychain now exposes zero valid code-signing identities and codesign --verify --deep --strict fails with CSSMERR_TP_NOT_TRUSTED. Current-host installed-runtime verification was therefore blocked until the local identity was repaired. The later 2026-09-02 recheck records two valid identities and deep/strict verification PASS for both installed apps. Neither observation rewrites the historical release acceptance result.

2.1 Development / release-promotion doctrine

  • LOCKED USER POLICY: /Applications/TFTMAC.app is the protected stable Control launcher/runtime. Normal engineering work must not rebuild, patch, overwrite, replace, or install development artifacts over this app.
  • LOCKED USER POLICY: active feature development targets the isolated DEV / advanced_diagnostics product at /Applications/TFTMAC DEV.app, bundle com.flashls1.tftmac.dev, with its separate AVD, ports, state, captures, and launcher.
  • LOCKED USER POLICY: Control exists as the always-available known-good rollback/playable launcher while DEV changes are being developed and validated.
  • LOCKED USER POLICY: moving accepted DEV functionality into a full production release is a separate, explicit release-promotion operation. Until Flash explicitly authorizes that promotion and its acceptance gates pass, DEV work must not mutate the installed Control artifact.
  • LOCKED: build/install scripts and agent workflows must fail closed if a DEV operation would overwrite or drift the protected Control executable, emulator-host identity, AVD, ports, or launcher.
  • OPERATIONAL NOTE: because Control and DEV use an exclusive runtime lease, one may need to be cleanly closed before the other launches; this does not authorize changing the Control artifact or configuration.

3. Launch and ADB architecture

  • LOCKED: launch the emulator through the packaged TFTMAC Emulator Host.app in the logged-in user's macOS session:

    /usr/bin/open -n -W --env ... --args ...

  • LOCKED: do not replace that host chain with direct Node/Clara spawn(). The discarded direct-service path changed the ADB execution/session identity and produced an unauthorized guest.

  • LOCKED: ADB server port 5038; emulator console port 5582; serial emulator-5582.

  • LOCKED: do not inject ADB_VENDOR_KEYS. The launcher uses the logged-in user's established ADB identity. Build 8 passes empty ADB_SERVER_SOCKET and ANDROID_ADB_SERVER_ADDRESS values through /usr/bin/open; its packaged RuntimeHost/main.c does not yet remove those variables before execv.

  • VERIFIED HISTORICAL ROOT CAUSE: the incorrect direct path used 5040, 5592, and emulator-5592, leading to unauthorized and eventually Timed out waiting for emulator ADB device. The Android runtime, AVD, GPU, RAM, CPU, and proven host launcher were not the cause of that failure.

  • LOCKED: authenticated EmulatorController is loopback-only, discovered from the launched emulator's PID-bound registration, and authenticated with a token held only in memory.

  • VERIFIED CURRENT: controller port request 8554; emulator option -grpc-use-token; raw controller frame limit raised to 16 MiB because a 1920×1080 RGBA frame is 8,294,400 bytes and exceeds gRPC's former 4 MiB default.

4. Android runtime and official package

Current DEV optimization runtime — VERIFIED CURRENT (2026-09-10)

Item Current DEV authority
Application /Applications/TFTMAC DEV.app, bundle com.flashls1.tftmac.dev, version 2.3.0 build 8
Runtime root /Volumes/MAC MINI M4/TFTMAC/Diagnostics/GraphicsRuntimeV1/StockShadow
SDK root /Volumes/MAC MINI M4/TFTMAC/Diagnostics/GraphicsRuntimeV1/StockShadow/SDK
Emulator Android Emulator 37.1.11.0, build 15917651
AVD TFTMAC_Diagnostic_StockShadow_R1
Ports / serial ADB 5041, console 5586, controller 8556, serial emulator-5586
Guest display 1920×1080, 320 dpi, 60 Hz
Effective guest CPU 8 vCPU; recent verified QEMU launches contain -cores 8. These are virtual CPUs scheduled on the 10-core M4 host, not eight dedicated physical host cores.
Effective guest RAM 6144 MiB (6 GiB); recent verified QEMU launches contain -memory 6144.
GPU / audio host GPU / CoreAudio
Current game RHI OpenGL ES through ANGLE (OPENGL_ES_ANGLE)
ANGLE revision 1166eec4c0b125e9e945196acfc549983ef72b18
Official TFT package com.riotgames.league.teamfighttactics
Current verified TFT build 18.1-5423749, version code 8423749
Working cache winner DEV-B8-WIN-01: multifile cache enabled; preferSubmitAtFBOBoundary disabled; syncMonolithicPipelinesToBlobCache removed

The sealed StockShadow AVD file itself remains a restoration baseline and currently contains hw.cpu.ncore=6 and hw.ramSize=5120. The installed runtime-modes.json locked profile records 6 vCPU / 6144 MiB, while current RuntimeModeAuthority.swift defaults advanced_diagnostics effective vCPU to 8 and retains 6144 MiB RAM. The decisive effective-runtime evidence is the launched QEMU command plus runtime receipt: current DEV test launches use 8 vCPU / 6144 MiB and restore the sealed AVD baseline afterward. Do not edit the stored AVD merely to make its static values look like the transient effective launch.

Protected Control / historical runtime reference

Item Protected Control / last-observed authority
Runtime root /Volumes/MAC MINI M4/TFTMAC/Runtime
SDK root /Volumes/MAC MINI M4/TFTMAC/Runtime/SDK
Emulator Android Emulator 37.1.11.0, build 15917651
AVD TFT_Ultra_Tablet
Guest Official Google Play ARM64 system image, API 36, image revision 7
Platform tools 37.0.1
WebView provider com.google.android.webview
WebView version observed 151.0.7922.199
TFT package com.riotgames.league.teamfighttactics
TFT version historically observed on protected Control 18.1-5402721, version code 8402721; do not use this as the current DEV client identity
Installer authority com.android.vending / Google Play
Unreal activity com.epicgames.unreal.GameActivity
Riot login activity com.riotgames.platformui.mobilefre.MobileFREWebViewActivity
  • LOCKED USER FACT: current TFT uses Unreal Engine. Engineering work must reason about the current Unreal-based client, not the retired legacy engine.
  • LOCKED USER PREMISE: the former native Mac path no longer supplies the current playable client after the engine transition; TFTMAC exists to present the official Android Unreal client as a native Mac experience.
  • LOCKED: Google Play owns install/update delivery; Riot owns authentication, game content, and the signed TFT package.
  • LOCKED: do not mirror, modify, patch, inject into, re-sign, or privately distribute Riot's APK or signed assets.
  • LOCKED SECRET BOUNDARY: never expose Riot/Google credentials, tokens, CAPTCHA/MFA material, or consent data in Git, docs, telemetry, command output, or chat.
  • VERIFIED CURRENT DEV LOGIN: DEV has an approved local saved-sign-in mechanism using the protected local riot-login.json credential file (0600) and code path identified as DEV_LocalCredentialFile. Its contents are never project evidence and must never be printed. CAPTCHA, MFA, consent, or other interactive challenges remain manual when required by the official UI.
  • MUTABLE: package and WebView versions can change through their official stores. Every session must record what was actually installed.
  • UNKNOWN: the TFT signer digest has been observed in Android package output, but has not yet been promoted as a durable project-authority digest.

5. Current DEV graphics and audio pipeline

TFT Unreal OpenGL ES workload
  -> Android system ANGLE (`libGLESv2_angle.so`)
  -> ANGLE Vulkan backend / ranchu
  -> gfxstream over virtio-gpu ASG
  -> host Vulkan / MoltenVK-to-Metal translation
  -> Apple Metal / M4 GPU
  -> Android SurfaceFlinger actual presentation
  -> authenticated raw RGBA frame stream
  -> TFTMAC Metal presenter
  -> native macOS fullscreen window

Boundary rules:

  • Unreal owns game simulation, effects, render-thread/RHI workload, and the game's actual frame production.
  • VERIFIED CURRENT DEV PATH: dedicated current-client engine-log evidence selects OPENGL_ES_ANGLE. Recent runtime receipts also show /system/lib64/libGLESv2_angle.so on the active RHI path. A generic lower-stack classifier may still emit UNREAL_ENGINE_VULKAN because Vulkan is used beneath ANGLE; that raw generic classifier is not authoritative for the game's selected RHI. Direct Unreal Vulkan was separately tested and rejected for this fast-pass after Metal vertex-descriptor/missing-attribute failures.
  • ANGLE owns GLES-to-Vulkan translation only when a game selects GLES/EGL and Android selects ANGLE for that package. Its ES 3.2 exposure is a compatibility route, not general conformance proof.
  • gfxstream/ASG owns guest-to-host graphics command transport. Configured ring, buffer, and flush values do not prove per-frame transport latency.
  • MoltenVK owns host Vulkan-to-Metal translation. Environment values are requested values unless effective behavior is directly measured.
  • TFTMAC owns host launch/session control, the final completed-frame copy, orientation/scaling, native input mapping, output cadence, and local evidence.
  • Two different components use Metal: MoltenVK for emulated Vulkan work and TFTMAC for final image presentation. A fast final presenter does not prove the upstream game/transport pipeline is fast.

6. Current DEV working profile and protected Control reference

Current DEV working winner — DEV-B8-WIN-01

Variable Current DEV working authority
App TFTMAC DEV 2.3.0 build 8 / com.flashls1.tftmac.dev
Runtime mode advanced_diagnostics / StockShadow
Guest display 1920×1080
Density / refresh 320 dpi / 60 Hz
Effective vCPU 8
Effective guest RAM 6144 MiB (6 GiB)
GPU / audio host / CoreAudio
ADB / console / controller 5041 / 5586 / 8556
AVD / serial TFTMAC_Diagnostic_StockShadow_R1 / emulator-5586
Graphics route OpenGL ES → ANGLE → Vulkan/gfxstream → MoltenVK/Metal
ASG 1 MiB write buffer / 16 KiB write step / 32 KiB ring / 800 µs flush
ANGLE enabled exposeNonConformant*:exposeES32ForTesting
ANGLE disabled preferSubmitAtFBOBoundary
Cache multifile enabled; global monolithic pipeline sync removed (DEV-B8-WIN-01)
TFT build 18.1-5423749 / 8423749

These are effective DEV test values proven by live QEMU/runtime receipts. The stored StockShadow AVD baseline intentionally remains 6/5120 for restoration; the runtime transaction/authority applies the effective DEV values and restores baseline on shutdown.

Protected Control historical baseline

The protected normal-play Control configuration below remains valid as Control/history and rollback context. It is not the current DEV optimization baseline. Change one declared DEV test factor at a time; do not silently mix these profiles.

Variable Control
Profile tftmac_5gb_native_v1
Guest display 1920×1080
Density 320 dpi
Refresh target 60 Hz
vCPU 6
Guest RAM 5120 MiB
GPU host
Audio CoreAudio
Transport virtio-gpu-asg
ASG write buffer 1,048,576 bytes / 1 MiB
ASG write step 16,384 bytes / 16 KiB
ASG data ring 32,768 bytes / 32 KiB
ASG draw flush 800 microseconds
Emulator features GLESDynamicVersion,Vulkan,GuestAngle,-GLPipeChecksum,VulkanBatchedDescriptorSetUpdate,AsyncComposeSupport,VirtioGpuFenceContexts
ANGLE enabled exposeNonConformantExtensionsAndVersions:exposeES32ForTesting
ANGLE disabled preferSubmitAtFBOBoundary
MoltenVK synchronous submits 0 / disabled
MoltenVK max active command buffers 64
MoltenVK fast math 1 / enabled
TFT graphics High
TFT FPS cap 60
Riot Performance Mode Beta OFF

The protected Control/native settings UI historically exposes only:

  • vCPU: 4, 6, 8;
  • guest RAM: 4096, 5120, 6144 MiB;
  • refresh target: 30 or 60 Hz;
  • ASG draw flush: 400 or 800 microseconds;
  • named experiment: Control or Combat Latency A.

The existence of a UI choice does not mean it is faster. All restart-bound values require a clean, logged relaunch.

7. Native input, login, power, and audio

  • VERIFIED CURRENT: Mac primary-button down/drag/up maps to Android EmulatorController TouchEvent, identifier 0, non-zero contact pressure, and explicit zero-pressure release. Desktop mouse events are not the primary touch path.
  • VERIFIED CURRENT: keyboard input uses EmulatorController sendKey. SQLite stores character count and special-key name only, never typed text.
  • VERIFIED HISTORICAL: the Riot login form expects the private Riot account username, not an email address and not the public Name#Tag Riot ID.
  • VERIFIED CURRENT RISK: Riot's WebView can ANR on input dispatch. The narrow proven recovery keeps TFTMAC and the emulator alive, restores show_ime_with_hard_keyboard=0, restarts only Riot's failed process, and reopens the official activity. This is recovery evidence, not proof that the mutable WebView/IME defect can never recur.
  • LOCKED: secure Android PIN unlock stays manual. TFTMAC may record that unlock is required, but never the PIN or typed content.
  • VERIFIED CURRENT: Build 7 establishes virtual AC power, Android stay-awake state, and mWakefulness=Awake before unlock/gameplay. It logs GUEST_GAMEPLAY_POWER_READY or fails clearly.
  • VERIFIED CURRENT: emulator requests -audio coreaudio; prior live evidence observed active 48 kHz stereo output and no partial/empty underruns.
  • UNKNOWN/USER ACCEPTANCE: software audio health does not prove the user can hear sound at their selected speakers/headphones.

8. Frame-rate truth

The on-screen overlay labels two host-facing rates:

SRC <distinct source-image rate> · OUT <native Metal presentation rate>
  • SRC is distinct authenticated gRPC images received per second.
  • OUT is TFTMAC Metal presentation cadence.
  • Neither is automatically Unreal gameplay FPS.
  • A repeated/static image can be presented at 60 OUT while TFT produces fewer useful frames.
  • dumpsys gfxinfo is not authoritative for TFT's native Unreal/Vulkan SurfaceView.
  • Player-visible game-frame authority is the exact TFT SurfaceFlinger layer's actual-present timestamps, summarized into one-second windows.
  • p95, p99, maximum interval, 1% low, jank, severe stalls, repeated images, and visible-stutter markers matter more than a flattering average.

9. Logging and SQL authority

Every app launch creates a private mode-0700 capture directory:

~/Library/Application Support/TFTMAC/Captures/<session-id>/
  TFTMAC_NATIVE_RUNTIME.sqlite
  native-events.jsonl
  emulator.stdout.log
  emulator.stderr.log
  logcat.raw.txt
  bounded diagnostic artifacts

Persistent normalized comparison authority:

~/Library/Application Support/TFTMAC/TFTMAC_LAB.sqlite

The implemented “SQL logging system” is local SQLite. It is not a MySQL server and does not require a network database service.

The session database is raw query authority. The persistent lab links raw captures by session/configuration/artifact identity rather than duplicating credential-bearing or full raw data.

SQL table Fact represented Normal cadence
sessions session start/end/status/profile boundary
runtime_receipts requested/effective launch, package, ports, renderer, profile startup and receipts
events lifecycle, ADB, package, markers, failures, process/layer changes event-driven
frame_samples bounded image/hash/dimension/sequence checkpoints boundary/checkpoint
frame_interval_windows source ingress intervals/drops 1 second
presentation_samples labeled SRC/OUT/mailbox behavior about 1 second
game_frame_intervals exact TFT actual-present intervals and flags each observed guest frame
game_frame_windows FPS, 1% low, p50/p95/p99/max, jank/severe/misses 1 second
stream_freshness_windows changed/repeated frames and transport loss 1 second
host_presentation_windows final Metal submissions/completions/GPU time/errors 1 second
resource_samples QEMU CPU/RSS, TFT PID/activity 5 seconds
guest_memory_samples guest memory and swap 5 seconds
host_resource_samples host memory pressure, thermal, power source 5 seconds
clock_sync_samples host/guest midpoint and round-trip error 30 seconds
surfaceflinger_samples render rate and cumulative miss counters boundaries and 30 seconds
audio_samples audio output/rate/stereo/tracks/underruns boundaries and 30 seconds
logcat_aggregates ANR/fatal/LMK/renderer/audio counts 5 seconds
pipeline_log_aggregates gfxstream/ASG/Vulkan/MoltenVK/shader/fence counts 5 seconds
graphics_pipeline_snapshots effective layer and graphics identities 30 seconds
graphics_runs automatic TFT process/layer lifetime, configuration SHA, target FPS, start/end reason process/layer lifecycle
graphics_pipeline_incidents automatic exact-layer degradation and conservative causal unknowns bounded incident
diagnostic_artifacts trace path/hash/processor/normalization status event-driven
combat_benchmarks complete benchmark configuration, coverage, validity, metrics benchmark end
combat_incidents trigger metrics, trace link, first divergent boundary/unknowns incident
combat_comparisons control/candidate deltas and decision comparison
game_process_sessions TFT PID lifetime process transition
input_samples touch metadata and keyboard counts only each input event
  • VERIFIED CURRENT: base graphics logging opens automatically from the observed TFT process/layer and seals only at process/app close. It is independent of match markers, Combat Benchmark controls, and battle classification.
  • VERIFIED CURRENT: stack receipts, SHA-256, graphics_run_id, and exact interval/window joins are written continuously. They prove scope and receipt integrity, not internal causal ownership.
  • LOCKED: the final native Mac presenter remains a hidden correctness receipt. It is not displayed, ranked, or selected as a graphics root cause.
  • UNKNOWN / PLANNED: no shared work ID or source-site span currently crosses guest submit, ASG/gfxstream, host Vulkan, MoltenVK, and Metal. The current logger cannot identify an internal root; advanced causal instrumentation is planned in an isolated diagnostic runtime.

Privacy facts:

  • Raw logcat and raw traces are sensitive local sidecars and are not pasted or published without deliberate sanitization.
  • No screenshot, raw frame payload, username, password, email, token, cookie, PIN, CAPTCHA, MFA value, or typed content belongs in SQL or project history.
  • No remote telemetry service is required.

10. Benchmark contract

  • LOCKED: complete automatic TFT process/layer runs are preferred product-performance evidence. Every logged frame and resource/pipeline sample inside the lifecycle participates; match/combat markers and classifiers are optional annotations only.

  • LOCKED: the current UI/source-named Combat Benchmark remains a faster 5–8 minute bounded A/B screen; it does not gate base graphics logging or replace a full-run promotion check.

  • LOCKED: graphics optimization decisions use graphics cadence and boundary evidence. CPU/RAM/audio observations remain health/correctness context only; this effort does not optimize them.

  • LOCKED: the product target is useful-frame cadence of at least 60 FPS throughout the complete run, not a flattering average or selected scene.

  • LOCKED: benchmark.md is the formula and reporting authority. Historical docs/benchmarks.md results retain their original M1 Max/userdebug scope.

  • Start the bounded A/B during representative continuous gameplay; no semantic phase marker is required.

  • Minimum valid combat duration: 300 seconds.

  • Automatic close: 480 seconds.

  • Exact TFT layer/timestamp availability: at least 95%.

  • Clock coverage: at least 95%.

  • p95 clock RTT at or below 2 ms permits precise cross-boundary attribution; 2–10 ms permits coarse ordering; above 10 ms means cross-host cause UNKNOWN.

  • Start trace: one bounded 20-second, 32-MiB Perfetto trace.

  • Incident traces: at most two 15-second, 32-MiB traces.

  • Automatic incident trigger: two adjacent one-second windows with 1% low below 30 FPS, p99 at least 50 ms, or severe stalls.

  • Trace cooldown: 120 seconds; no concurrent traces.

  • If trace-active versus trace-inactive windows differ by more than 5%, retain performance data but mark trace causality OBSERVER_OVERHEAD_INVALID.

  • Valid traces are SHA-256 sealed and normalized by pinned trace_processor_shell v58.2. Pinned SHA-256: d29864d1ba3b36855527bb1b0ca3aa7f703cdce338b9680bb922c5c151b358fa.

Decision rules:

  • HOME_RUN: a standout broad win: 1% low +20% or more, jank and severe rates each -30% or more relative, and either weighted FPS +10% or p95 interval -15%, without a material veto.
  • PROMISING: any valid directional improvement in weighted FPS, 1% low, both p95/p99 tails, or smoothness/jank/missed-vsync behavior, provided no material regression or correctness/usability veto outweighs it. There is no +5% FPS floor.
  • REJECT: correctness/usability failure or material regression, including weighted FPS about 5% worse, 1% low about 10% worse, p95/p99 at least 10% worse, or any boot, render, input, audio, login, memory, cleanup, or usability regression.
  • INCONCLUSIVE: invalid workload/coverage/synchronization, incompatible configuration identity, or valid evidence with no directional improvement or decisive regression.
  • A PROMISING incremental candidate requires the existing cold confirmation before becoming the next DEV working winner; a later full-run check may still veto it if compounding exposes a material regression.
  • LOCKED: HOME_RUN/PROMISING are relative candidate decisions, not proof that the product target is met. The separate full-run status remains TARGET_NOT_MET until useful-frame cadence holds at least 60 FPS throughout.

11. Verified results and decisions

Current native/runtime evidence

  • VERIFIED CURRENT: automatic capture 2026-08-31T22-30-26.086Z-8df607d7-a34a-4e2a-b00d-739aa3143200 recorded an uninterrupted 42m27s TFT graphics run (PID 2774) with 144,364 exact SurfaceFlinger intervals, 99.629% exact-layer coverage, and 189 degradation incidents. Weighted FPS was 56.98, 1% low 21.49 FPS, p95 21.510 ms, p99 33.434 ms, and 53.72% of intervals missed the 60-FPS budget.
  • VERIFIED CURRENT BOUNDARY: final native presentation remained near 60 Hz during this run, so it is retained only as hidden correctness context. The first internal graphics boundary remains UNKNOWN; present evidence localizes lateness upstream of or at the exact TFT SurfaceFlinger layer.

2026-09-02 live severe-slowdown capture

  • VERIFIED CURRENT CAPTURE: 2026-09-02T05-26-14.078Z-0fb7a877-23f7-4933-bc9f-5525ed8c6d3d is retained as the user's severe-slowdown run. The sealed SQLite authority is 18,583,552 bytes with SHA-256 2246edff4f433cd5a6d8d995a612274930d2ad979fa649f9249b690fe6f3ed8b.
  • VERIFIED PERFORMANCE: the final 300-second tail contains 213 exact-layer windows. Mean effective FPS was 15.884, the worst window was 0.684 FPS, mean 1% low was 10.081 FPS, and the windows accumulated 13,494 missed-vsync equivalents. This is direct evidence of unacceptable sustained frame loss.
  • VERIFIED PIPELINE CONTEXT: stream delivery averaged approximately 15 FPS with no sequence loss while the final Mac presenter continued its established near-60-Hz correctness cadence. The useful-frame deficit therefore existed before the final presenter; the final presenter is not a selectable root-cause candidate.
  • VERIFIED CPU ASSIGNMENT: guest CPUs 0-5 were online and present and the guest reported six processors. The slowdown was not caused by TFTMAC assigning only two guest vCPUs.
  • VERIFIED TRACE SIGNAL: in the second bounded Perfetto trace, Unreal's RHIThread was scheduled running for 13.38 seconds of an approximately 14.7-second trace (91.3%) and runnable-but-not-running for only 1.6%. SwappyThread3, GameThread, and RenderThread were scheduled running for approximately 40.2%, 24.6%, and 11.4% of the trace. This is the strongest current signal of serialized pressure in the guest Unreal RHI/Vulkan path; it does not by itself prove which owned gfxstream/MoltenVK boundary must be changed.
  • VERIFIED GUEST WARNINGS: the run logged VIRTGPU_PARAM_CREATE_FENCE_PASSING unavailable 26 times, nine DRM_IOCTL_VIRTGPU_GET_CAPS invalid-argument failures, and nine DRM_IOCTL_VIRTGPU_CONTEXT_INIT file-exists fallbacks. These remain causal suspects, not proven owners.
  • VERIFIED HOST CHURN: emulator.stdout.log contains 307 internal emulator helper ADB failures with cannot start server on remote host, while TFTMAC's primary ADB server remained authorized on 5038. Empty inherited ADB endpoint variables are a source-level defect to repair, but this background churn is not yet proven to explain the frame collapse.
  • VERIFIED ARTIFACTS: two bounded traces and their normalized JSON/CSV receipts are retained under the capture's perfetto/ directory. They are private diagnostic evidence and must not enter Git.
  • USER ACCEPTANCE: this run was reported as too slow for enjoyable play. It is a retained regression/problem record, not a promotable configuration.

2026-09-02 restored play authority

  • VERIFIED HISTORICAL LAUNCH: capture 2026-09-02T05-54-33.919Z-e13fd9b8-1091-4516-bd6e-66f8b50a912d passed the exclusive-runtime preflight, launched through the packaged Mac host, authorized ADB on 5038 / emulator-5582, and produced a 1920x1080 first native frame.
  • VERIFIED HISTORICAL SETTINGS: protected Control preset control, six vCPU, 5120 MiB RAM, 1920x1080 at 320 dpi and 60 Hz. This is the normal-play authority restored for the user's game; do not restart or replace it during live play.
  • VERIFIED CONTROL RESULT: graphics run 3ebd80ab-5f0f-489e-97ae-d9e0d780831a retained 14,348 exact TFT frame intervals across 353.5 seconds: 47.384 weighted FPS, 7.870 FPS 1% low, 16.868/34.002/50.492 ms p50/p95/p99, 19.090% jank, 1.429% severe stalls, and 3,820 missed-vsync equivalents.
  • VERIFIED REJECTION: the preceding severe run retained 35,424 intervals across 1,355.8 seconds: 26.446 weighted FPS, 2.770 FPS 1% low, 16.975/117.088/218.054 ms p50/p95/p99, 34.714% jank, 21.037% severe stalls, and 44,922 missed-vsync equivalents. Control was decisively more usable, so combat_latency_a is rejected for normal play. The workloads were not a formal matched A/B pair, so the QoS request alone is not claimed as the cause.

2026-09-02 Control and DEV launcher separation

  • LOCKED CONTROL: /Applications/TFTMAC.app remains the protected normal-play app with bundle ID com.flashls1.tftmac. Its executable SHA-256 remains d3bf7c249a3e5f11b81f778b063e1a8cfe2e7fdeec0537ee6bd8447b1c2268d2, and its packaged emulator-host SHA-256 remains ea028ec1d74cc025638c2a0e5f8c783748803c1b0ba9012962c038251fb3eb63. The protected app remains directly launchable as rollback. The Desktop icon points to the separate signed Control unlock wrapper and retains the official Control artwork.

  • VERIFIED DEV INSTALL: /Applications/TFTMAC DEV.app is a separately signed native app with bundle ID com.flashls1.tftmac.dev and a distinct generated DEV icon. /Users/flash/Desktop/TFTMAC DEV.app points to it.

  • LOCKED ISOLATION: DEV selects advanced_diagnostics, uses state namespace advanced_diagnostics, ADB/console/controller ports 5041/5586/8556, serial emulator-5586, and AVD TFTMAC_Diagnostic_StockShadow_R1. Control continues to use its original application-support root, ports 5038/5582/8554, serial emulator-5582, and AVD TFT_Ultra_Tablet. The global runtime lease forbids either launcher from starting while the other owns the runtime.

  • VERIFIED CURRENT SIGNING: both installed app bundles pass strict deep codesign verification with the local TFTMAC Local Code Signing identity. The current keychain exposes that identity and the Apple Development identity; scripts/verify-installed-runtime.command also passes for Control.

  • VERIFIED CURRENT: the stock-shadow DEV runtime physically clones Emulator 37.1.11 and the API 36 Control AVD into the diagnostic root. Its sealed receipt state is STOCK_SHADOW_RUNTIME_IDENTITY_PASS; the Control AVD tree hash remained unchanged before and after cloning.

  • VERIFIED CURRENT: three consecutive stock-shadow DEV launches reached ADB device, awake/unlocked Android, authenticated controller, exact native first frame, official TFT package/layer, input/audio receipts, and clean shutdown: 2026-09-02T12-16-42.125Z-c46f..., 2026-09-02T12-18-11.819Z-1300..., and 2026-09-02T12-19-13.294Z-3d6d....

  • BOUNDARY: Control is the dependable playable launcher. DEV stock shadow is launch/play compatible for isolated diagnostics but can never replace Control.

  • VERIFIED CURRENT: Build 7 live capture 2026-08-31T02-54-28.329Z-14000b50-bf29-44c6-a963-9203d5313494 reached authenticated ADB, a 1920×1080 RGBA first frame, awake/stay-on guest power, logger health, official TFT package receipt, and TFT_READY_FOR_USER under combat_latency_a.

  • VERIFIED CURRENT: configuration SHA-256 05039d1fd0987f46fc7da8de5f483d8c7ffaf8f39bd1eaecdd1aee11603bbb07.

  • VERIFIED CURRENT: host pre-exec QoS request returned 0 and read back user_interactive, relative priority 0.

  • UNKNOWN: this does not prove every QEMU worker inherited that scheduling class or that combat performance improved.

  • VERIFIED CURRENT: the same live session recorded Riot WebView/input ANR aggregates and a narrow Riot-only recovery. Do not misclassify that as a graphics improvement or as a whole-emulator crash.

  • VERIFIED CURRENT: the user marked one complete Build 7 match in that same session from event 1442 at 2026-08-31T03:19:25Z through event 3065 at 2026-08-31T03:51:00Z, a 1,895.054-second / 31m35.054s range.

  • VERIFIED CURRENT: the marked run contains 93,724 exact TFT actual-present intervals: weighted FPS 49.449, 1% low 16.300 FPS, p95 33.822 ms, p99 48.746 ms, maximum 1,254.162 ms, 19.110% jank, and 0.610% severe intervals. Exact-layer measured coverage was 100%, with one stable layer and no history truncation.

  • VERIFIED CURRENT: 58,925 intervals (62.871%) exceeded the 60 FPS frame budget; total budget overrun was 357,921.976 ms; the longest consecutive budget-miss run was 325 intervals; and 1,599 of 1,693 complete one-second windows (94.448%) were below 60 FPS.

  • VERIFIED CURRENT: final TFTMAC Metal output averaged 59.968 FPS with zero drawable/command errors and maximum recorded final-presenter GPU time 3.267 ms, while 23,231 presentations reused a source frame. This makes the final pass a poor explanation for the missing useful frames in this match; it does not identify which upstream component was first late.

  • UNKNOWN: this full run is not a candidate-vs-Control decision. It has no matched Control/formal benchmark row, and p95 clock RTT was 86.757 ms, so cross-host ownership is invalid. benchmark.md preserves the complete result.

Rejected Home Run A / Riot Performance Mode Beta

  • USER REJECTED: worst gameplay/graphics experience; do not select again.
  • VERIFIED HISTORICAL: 480.646 seconds; weighted FPS 56.665; 1% low 17.698; p95 21.760 ms; p99 34.335 ms; maximum frame 517.488 ms; jank rate 4.554%; severe rate 0.290%.
  • VERIFIED HISTORICAL: incident 1% lows 1.932 and 4.629 FPS; one incident included a 517.488 ms p99/max interval.
  • INVALID FOR CAUSAL ATTRIBUTION: p95 clock RTT 87.318 ms and observer overhead invalidated cross-boundary ownership claims.
  • LOCKED DECISION: home_run_a remains only as a historical migration/raw receipt enum. It is not selectable. Riot Performance Mode Beta stays OFF.

Earlier fixed-stage graphics campaign

These are VERIFIED HISTORICAL results from a different M1 Max/userdebug campaign, useful for candidate selection but not current M4 runtime performance:

  • ASG versus pipe at exact stage 1-1: 40.1 FPS / 34.85 ms p95 versus 29.6 FPS / 49.75 ms p95. ASG selected.
  • Three controls at Trial 1-2/1-5/1-8: 40.60 / 36.03 / 27.83 FPS.
  • Confirmed 67% effects/LOD profile: 45.20 / 38.50 / 33.80 FPS; stage-1-8 p95 35.07–35.95 ms.
  • 16 KiB ASG write step beat paired 4 KiB control and was retained.
  • 2560×1440 versus 1600×900 changed a controlled stage-1-5 result only from 30.5 to 31.3 FPS despite 2.56× source pixels, indicating that scene was not primarily pixel-fill bound.
  • The historical selected stack did not achieve the 57 FPS heavy-scene goal and did not reproduce the user's worst approximately 15 FPS gameplay period.

Graphics council and ZoeMC simulation

  • VERIFIED HISTORICAL: specialist research covered Unreal, ANGLE, gfxstream/ ASG, MoltenVK, Metal, and transferable Fortnite/Unreal measurement categories.
  • VERIFIED HISTORICAL: the 10,000-world ZoeMC v0.2 run used declared subjective priors. It is hypothesis-ordering evidence, not empirical proof.
  • RESOLVED BRANCH: the simulation's decisive next test—authenticated native frame delivery—was completed. Raw authenticated gRPC is viable for correct 1920×1080 native presentation and input.
  • NOT PROMOTED: direct MMAP zero-copy without producer fencing, direct MoltenVK texture sharing without a supported contract, encoded video/scrcpy, and external emulator-window presentation.
  • Fortnite/Unreal research can suggest counters, trace categories, pipeline-cache ideas, and workload hypotheses. It does not prove TFT-specific capabilities or justify altering Riot's signed shaders.

Settings that must not be recycled without new causal evidence

  • Pipe transport.
  • MoltenVK 128/256 command buffers.
  • Synchronous MoltenVK queue submission.
  • Guest submit thread and broad shader prewarm.
  • Native GLES and direct Vulkan routes.
  • VirtioGpuNativeSync, VirtioGpuNext, disabled Vulkan descriptor batching.
  • ASG 8/32 KiB write steps, 64/128 KiB rings, 512 KiB write buffer, and 2/4 ms flush screens.
  • Active-consumer host patch.
  • More guest RAM or an eighth vCPU as an assumed optimization.
  • Audio disabled.
  • MSAA2, material quality 1, r.OneFrameThreadLag=0, forced half-rate skeletal animation, extreme effects/LOD, blind 50% scale, and blind PSO prewarm.
  • Riot Performance Mode Beta and the combined Home Run A host flags.

12. Retired experiment: Combat Latency A

  • LOCKED TEST SHAPE: Control remains High/60/OFF and the complete proven emulator stack.
  • RETIRED CANDIDATE: changed only the packaged emulator host's requested pre-exec QoS to user_interactive; it is not selectable for current tests.
  • VERIFIED IMPLEMENTATION: candidate/configuration hashing, stale-preset migration, host QoS receipt parsing, guest power gate, correctness rollback, and stable semantic TFT-layer comparison have native tests.
  • VERIFIED LAUNCH: Build 7 established the requested QoS at the host pre-exec boundary and reached TFT ready with logging active.
  • VERIFIED REJECTION: the user rejected the gameplay and the measured run was materially worse than the restored Control. It remains historical only.

13. Causal graphics implementation state

  • VERIFIED CURRENT: R11 is FAILED_FIRST_NATIVE_FRAME historical evidence, not launch-ready authority. Emulator 35.6.3/API 37 cannot govern current DEV.
  • VERIFIED CURRENT: exactly three runtime modes remain: control, advanced_diagnostics, and fail-closed candidate. Current DEV uses the advanced_diagnostics stock-shadow runtime described above.
  • VERIFIED SOURCE: DevExperimentProfile seals the profile, one-factor feature override, effective configuration SHA-256, workload-manifest SHA-256, duration, warmup, and correctness requirements. The balanced campaign order is Control / queue-submit-inline / Control / virtual-queue-off / Control / fence-contexts-off / Control.
  • VERIFIED SOURCE: the owned ARM64 Vulkan probe has five deterministic one-minute workloads after a 30-second warmup and no network/Riot access.
  • VERIFIED SOURCE: the app schema contains all eight causal SQL structures. Swift and C++ define the same 96-byte PipelineEventV1; the C++ per-thread ring has a fixed capacity of 256 and strict owned-probe label parsing. Standalone ABI/parser verification passes.
  • BOUNDARY: runtime/source hooks below the app and the seven-run campaign are not yet accepted evidence. No internal component is named as root until the label, lineage, loss, observer-overhead, and replication gates pass.

The R9/R10/R11 entries below are retained as historical failure evidence. They do not override the current stock-shadow DEV authority.

  • VERIFIED HISTORICAL (2026-09-02T02:07:03Z): Wave B source integration was complete under the append-only Wave B v4 correction authority. The default mode remains control, and candidate remains blocked.
  • VERIFIED HISTORICAL (Wave B source checkpoint): runtime-mode registry SHA-256 was 136d1f8f9ac587f9ab0e839e7521b21d9c5e7a1d451d5a0bac44b44a8fe56479. Runtime identity, registry/configuration hashes, AVD identity, ADB/console/ controller ports, and serial are persisted in the exclusive lease contract.
  • VERIFIED HISTORICAL: scripts/verify-tftmac.command completed with exit code 0, produced an unsigned Release build, and passed all 49 native tests with zero failures. The post-verification process audit found no active TFTMAC, emulator, or qemu-system-aarch64 process; no runtime, AVD, installed app, or official TFT package was changed or launched by Wave B.
  • VERIFIED HISTORICAL (2026-09-02T02:20:37Z): diagnostic ADB 5041, console 5586, and controller 8556 passed listener and exclusive-bind checks with control stopped. A new R9 diagnostic forwarder was built from the proven native RuntimeHost/main.c chain, ad-hoc signed, deep/strict verified, and sealed under receipt SHA-256 3a0bfccbcc96466bbdb83a14a0530906ef7c37ec0e0e61b8f701b2e534e15c7f. The stale first-load host remains preserved but is not R9 launch authority.
  • VERIFIED HISTORICAL: the R9 advanced_diagnostics variant was selectable only through the explicit TFTMAC_RUNTIME_MODE=advanced_diagnostics environment request. Its R9 registry SHA-256 is 798bad7512da1079167b120575c5c446a1ae7a5bec3030c19fc1da817dbf206b; unsigned Release and all 49 native tests pass. Control remains the default.
  • VERIFIED HISTORICAL (R9 first-boot attempt 1): capture 2026-09-02T02-23-48.444Z-9a2df80c-263a-4e10-beaa-8980d095c365 failed before QEMU because the diagnostic registry incorrectly used the emulator-only R9 install directory as ANDROID_SDK_ROOT. The forwarder and isolated ADB server did launch, the emulator reported Broken AVD system path, no QEMU process loaded, and the R9 AVD configuration was restored to its accepted SHA-256 090fe426402562e227a3a1a6bd6eab9f9572cd48fbe3d467c276d419860caf90. The corrected registry restores the existing dedicated API 37 SDK and ADB at /Volumes/MAC MINI M4/TFTMAC-RUNTIME-DATA/SDK; source validation and all 49 native tests passed after the correction.
  • VERIFIED HISTORICAL (R9 first-boot attempt 2): capture 2026-09-02T02-31-04.642Z-c7f52368-7fd7-411d-bbf9-d6dee45eb765 failed before QEMU because Android Emulator 35.6.3 rejects the stock-control -crash-report-mode argument. The argument is now gated to Control; it is not sent to the diagnostic runtime.
  • VERIFIED HISTORICAL (R9 first-boot attempt 3): capture 2026-09-02T02-33-42.154Z-d39fac1f-393f-409f-b235-5200853db209 loaded the R9 QEMU/gfxstream runtime but crashed in protozero::MessageArena::DeleteLastMessageInternal through perfetto::TrackEvent::Initialize, gfxstream::host::InitializeTracing, and FrameBuffer::initialize. Exact symbols place the first R9 blocker in the custom gfxstream Perfetto initialization path, not in Riot, the AVD, MoltenVK, Metal, ADB authorization, CPU, RAM, or audio.
  • VERIFIED HISTORICAL (R10 first boot): capture 2026-09-02T03-00-38.256Z-b95cb5a2-59c6-4855-859e-846bc1deca8a proved the successor passed the R9 initialization crash, loaded API 37, MoltenVK, selected the Apple M4 Vulkan device, enabled VK_EXT_robustness2, and initialized the OpenGL ES Translator adapter. It then crashed in perfetto::protos::gen::TrackDescriptor::SerializeAsString from gfxstream::SyncThread::doSyncThreadCmd, SyncThread::initSyncEGLContext, and FrameBuffer::initialize. This proves default-disabling InitializeTracing was insufficient because unguarded gfxstream trace-name macros still entered Perfetto.
  • VERIFIED HISTORICAL (R10 minidump adjudication): the retained macOS 26.6.2 arm64 minidump reports uptime 3 seconds, EXC_BAD_ACCESS / KERN_INVALID_ADDRESS at address 0x8, and a crashed instruction in libandroid-emu-tracing.dylib + 0x749c. Its stack carries track_event, gfxstream.default, and libgfxstream_backend.dylib + 0x314278; its gfxstream Mach-O UUID is 4C4C4449-5555-3144-A1FC-F6DFE0021481, and its annotation reports 35.6.3-standalone-0. This is the already-classified R10 Perfetto track-registration null dereference, not an R11 crash and not evidence against TFT, Riot login, the API 37 image, MoltenVK, Metal, CPU, RAM, audio, or the stock 37.1.11 runtime.
  • VERIFIED HISTORICAL (R11 sealed successor): R11 kept tracing compiled but places the gfxstream event, instant, and name-track macros behind an explicit runtime opt-in. Sealed build manifest SHA-256 is 3fd3e18aab970728fcb94efded84952fbde0e84bce86d0ef3592184eaa1170fa; gfxstream SHA-256 is a770f67660c8d88f5a853b4705aefa0210ef37670a9a8df1b22b702b1f79584b; runtime-configuration SHA-256 is c910e13e1096da4d3ee162ed82d5658d32aee4b29d9c6af30d19447c03784560. The fresh stopped TFTMAC_Diagnostic_API37_R11 clone receipt SHA-256 is e7418f81a37ad3d8169a9c1818e904f1678722e3879fcf7ee610c3257b80d419.
  • VERIFIED HISTORICAL (R11 source/runtime gate): registry SHA-256 is b2a8080248900c27efdaac7fe3825ccb919188d43072af7a870bfc49c3e0e96f. Diagnostic preflight is READY on isolated ports 5041/5586/8556, and the official unsigned Release verifier passed all 49 native tests with zero failures. Control remains the default and candidate remains fail-closed.
  • VERIFIED HISTORICAL (R11 live attempt 1): capture 2026-09-02T03-18-30.572Z-f4a767a5-b385-4385-bcff-7873c9cffdf9 reached controller discovery and LOADED_RUNTIME_IDENTITY_PASS for exact R11 QEMU and gfxstream hashes. It did not crash. TFTMAC then performed an owned shutdown because runController still hard-coded the Control emulator version 37.1.11 and rejected the valid R11 status 35.6.3.0 (35.6.3-standalone-0). The check is now mode-aware and consumes the sealed expected_emulator_version_contains authority (35.6.3 for R11); the regression assertion is included in the existing 49-test suite.
  • VERIFIED HISTORICAL (R11 corrected live attempt): capture 2026-09-02T03-27-32.017Z-80c1dff8-30cf-4f3d-984f-2a3c37863de6 passed controller authentication and exact R11 loaded-runtime identity. The R9/R10 Perfetto crash did not recur. ADB changed from offline to unauthorized using the logged-in user's default key and no ADB_VENDOR_KEYS; no native first frame arrived before the bounded 120-second gate. The emulator explicitly reported that the API 37 guest requires a host supporting QemuCameraSensorOrientation and VulkanVirtualQueue. The owned shutdown restored the diagnostic AVD configuration.
  • VERIFIED HISTORICAL (R11 wake-control retry): capture 2026-09-02T03-33-05.318Z-d463ced7-5843-4a11-8c95-c9757c7ee032 repeated exact R11 identity/controller passes and sent Power immediately after authentication. It again produced no first frame and ADB remained unauthorized. This rejects a wake-command timing explanation; repeating the same R11 runtime is not an eligible next experiment.
  • VERIFIED HISTORICAL (R11 ADB provisioning and isolated DEV launch): the existing logged-in-user ADB identity was approved once inside the isolated DEV AVD; no ADB_VENDOR_KEYS injection or authorization bypass remains in the runtime profile. Final DEV capture 2026-09-02T07-46-40.998Z-8260f517-a8a4-4d5e-918f-723b81de32f4 passed ownership preflight, exact R11 loaded-runtime identity, and ADB state device. Automatic session/database logging started in the isolated DEV application-support namespace.
  • VERIFIED HISTORICAL (R11 first-frame failure after ADB repair): that same capture never emitted FIRST_NATIVE_FRAME and recorded RUNTIME_FAILED at 2026-09-02T07:48:46Z with Timed out waiting for Android to post its first native frame. The 120-second gate therefore proves the launcher and ADB authorization are no longer the blocking boundary; the custom R11/API 37 rendering path still fails before native frame delivery. DEV was shut down cleanly after preserving this evidence.
  • VERIFIED HISTORICAL (hybrid compatibility probe): substituting the R11 gfxstream backend into an isolated APFS clone of the stock 37.1.11 host failed to load because stock libemugl_common.dylib does not export the actively required g_emugl_dma_get_host_addr symbol. Substituting the paired R11 libemugl_common.dylib passed that loader boundary but the stock QEMU then terminated with SIGSEGV during gfxstream renderer initialization (minidump 21ab1231-eb10-42b6-a896-35f4e3c31511.dmp). A null-symbol shim would corrupt active DMA call sites. Further binary-library swapping is rejected.
  • VERIFIED SOURCE BOUNDARY: Google's published 37.1.11 stable release notes state that the release added Vulkan extensions required by API 37 system images. The public QEMU history exposes 37.1.8 as the last 37.1 canary version bump but does not expose a 37.1.11 bump commit or a 37.x release branch. Therefore an exact source identity for build 15917651 is currently UNKNOWN; no branch head or 37.1.8 revision may be represented as that exact source.
  • OPEN LIVE GATE: R11 proved crash removal and exact loaded identity, but it did not pass native first-frame or API 37 AVD acceptance. The next eligible runtime is one built from a coherent modern emu-main-dev manifest graph, not another 35.6.3 retry or hybrid library swap. Manual device PIN, Riot authentication, and gameplay remain user-operated and are not automated.

2026-09-02 clean-stop continuation facts

  • VERIFIED SOURCE: the modern manifest is pinned to 2692acc620f6563b21995540656674faeb536cdc on emu-main-dev; preparation and uninstrumented Release build scripts enforce four-job parallelism and refuse to run while Control or DEV is active.
  • VERIFIED FAILURE AND FIX: the first sync target was the case-insensitive external APFS volume and failed because Android requires distinct BUILD and build/ paths. scripts/prepare-causal-source-runtime.command now creates a 180-GiB sparse, case-sensitive APFS image and validates case sensitivity before syncing. The failed checkout is historical partial state and is not source authority.
  • PAUSED, NOT FAILED: the corrected case-sensitive sync was deliberately interrupted for this clean handoff. No source-lock receipt or uninstrumented causal-stock build receipt exists yet. The preparation script is resumable.
  • OPEN LOCAL SETUP: Keychain service com.flashls1.tftmac.android-unlock.v2, account android-user-0, was not populated before this stop. The PIN is never in source, arguments, logs, SQL, or this repository. scripts/setup-android-unlock.command is the only setup entry point.
  • NOT RUN: the seven-run owned Vulkan-probe campaign has no accepted result yet. No one-factor candidate is promoted and no source component has been named as root.

14. Explicit unknowns and open acceptance

  1. The causal magnitude of Combat Latency A's QoS request under a formally workload-matched A/B. It is already rejected for normal play because its observed severe run was decisively worse and provided no usable benefit.
  2. Whether QEMU decoder/render/submission workers actually receive beneficial scheduling after exec.
  3. The first divergent boundary in the run's worst sustained under-60 periods.
  4. RESOLVED CURRENT (2026-09-03): Exact ASG-versus-gfxstream-versus-MoltenVK ownership is verified and closed by causal-hook-timeline-20260903-r6 using the timeline-semaphore submit sideband (VK_KHR_timeline_semaphore). Across 99,480 recorded events and 10,796 fully correlated frames (0 losses, 0 overwrites, 100% SHA-256 integrity), total host graphics latency (Site 1001 ASG decode through Site 2005 Metal GPU completion) averages 0.792 ms (p50 0.692 ms, p95 1.489 ms, p99 2.033 ms). Gfxstream submit averages 0.014 ms, MoltenVK translation averages 0.106 ms, and Metal GPU execution averages 0.683 ms. The host graphics stack is proven non-bottleneck (<5% of 16.67 ms frame budget); lateness is upstream of the host decode boundary in guest
  5. RESOLVED CURRENT (2026-09-03): MoltenVK Global Persistent Pipeline Cache is implemented in MVKDevice.mm (getOrCreateDefaultPipelineCache()), hooked into createPipelines whenever pipelineCache == VK_NULL_HANDLE, and saves periodically and on shutdown to /Volumes/MAC MINI M4/TFTMAC/Diagnostics/GraphicsRuntimeV1/Cache/moltenvk_pso.cache. In live diagnostic run r6, moltenvk_pso.cache was successfully created, populated with 3,709 bytes, and verified with valid Apple vendor 0x106b Vulkan 1.4 header. In parallel, scripts/prewarm-tft-gameplay.command was created and verified, forcing guest ART Ahead-Of-Time (AOT) compilation to native ARM64 (status=speed), pre-faulting >2 GB of game APK and .pak assets into guest Linux RAM pagecache, and prioritizing Unreal Engine :psoprogramservice worker threads to eliminate guest compilation and disk stalls.
  6. Whether MMAP can reduce host copy/frame age without tearing or ownership corruption. Raw gRPC remains the working control.
  7. Whether current sound is audibly correct at the user's output device.
  8. Whether Riot WebView input ANR recurs after future TFT/WebView updates.
  9. Public distribution acceptance: Build 8 has a historical local-signing receipt, current-host trust is blocked, and no notarization is claimed.
  10. Whether any owned candidate can hold the complete automatic run at the 60 FPS target without correctness, audio, login, memory, or cleanup regression.
  11. RESOLVED CURRENT (2026-09-04): Full 32-minute live combat match (2026-09-04T17-50-10.043Z) established that planning/shopping locks at 58.6–59.8 FPS while 20–30 unit combat rounds surge CPU load to 380%–510%, dipping frame rates to 40–53 FPS. Definitive memory audit proved guest Android has 1.7 GB free RAM headroom (consumed 3.2 GB of 5.1 GB, 0 LMK kills) and is not memory-pressured. Host macOS (16 GB unified) has 2.9 GB free uncompressed RAM; increasing guest RAM to 8 GB causes unified memory page compression and disk swapping that starves Metal GPU presentation. Allocating 8 vCPUs for DEV mode in RuntimeModeAuthority.swift gives the guest horsepower to absorb 510% combat spikes, while p.ClothPhysics=0, r.DynamicRes.OperationMode=1, r.pso.PrecompileThreadPoolSize=2, and am force-stop clean snapshot exit lock the gameplay loop.

15. Authority and update rule

Use this precedence for current project truth:

  1. facts.md — first project-specific authority for current facts, boundaries, and mandatory rules;
  2. project.md — living current-state wiki, which must agree with facts.md;
  3. newly observed direct machine/runtime/source evidence only as a reconciliation trigger: validate it, then update facts.md/project.md before relying on the new fact in a final plan or change;
  4. CHANGELOG.md — detailed append-only test/version history and integration decisions;
  5. reconciled machine-readable authority (ssot/runtime-authority.json, ssot/STACK.lock.yaml), current native source/tests, and benchmark.md;
  6. docs/TFTMAC_NATIVE_RUNTIME_KNOWLEDGE_BASE.md, dev.md, and other current references after checking them against items 1–5;
  7. historical campaign docs/SQL, plans, simulations, and research as dated evidence or hypotheses only.

A conflicting lower-precedence document never wins merely because it is more detailed or newer-looking. If credible newer evidence disagrees with facts.md/project.md, stop the finalization step, validate the evidence, reconcile the authority records, and only then continue. TFTMAC.md, old launchers, old Node helpers, source-build plans, old profiles, and dated handoffs are never allowed to silently become current runtime authority.

Before completion of a selected managed change, verify intended work is committed/published as required and git status is clean. Dirty generated test output is not an acceptable finished state.