chimera-gfx-Public/ARCHITECTURE.md

Architecture

Scope and trust boundaries

libchimera-gfx is split so that host-testable policy and state validation do not depend on PS5 headers or undocumented ABI assumptions.

RetroArch adapter (Phase 3) ----+
                                +--> public C API --> validated core
SDL2 renderer (Phase 4) --------+                         |
                                                          +--> mock backend
                                                          +--> PS5 backend (refuses)

Phase-0 capability sample --> probe logic --> symbol resolver --> system loader
                                      ^              |
                                      |              +-- no resolved pointer escapes
                                      +-- generated read-only symbol table

The capability probe is intentionally separate from the normal context API. Discovering exports does not make the PS5 backend usable and cannot set a rendering capability flag.

Public API contract

The public API is C11 and uses opaque handles, explicit structure sizes, and an API version. This supports compatible growth without copying upstream or proprietary structures into the interface.

Phase-0 guarantees:

1. chimera_gfx_create() creates only the mock backend; the separately compiled PS5 backend always returns SAFETY_POLICY.
2. Any rendering-request flag fails with CHIMERA_GFX_STATUS_SAFETY_POLICY.
3. Mock capabilities claim only a host-memory lifecycle and present model, always together with NON_RENDERING and HOST_TEST_ONLY.
4. Context destruction accepts NULL and otherwise returns RESOURCE_BUSY until every child surface and texture is destroyed.
5. Unknown backend IDs, API versions, flags, or undersized structures fail before backend code is entered.

The contract includes opaque surface and texture handles, validated RGBA8 upload, a deterministic mock present serial, and cleanup status. It does not yet include buffers, queues, shaders, fences, swapchains, display ownership, hardware contexts, or hardware presentation.

Backend contract

Backends receive only validated inputs. A backend must populate capability flags from evidence, never from platform names or compile-time assumptions. Future mutating operations must include bounded lifetimes, timeout behavior, idempotent cleanup, and a safe fallback before entering the public API.

The mock backend is deterministic and advertises only:

• backend availability;
• non-rendering operation;
• host-test support;
• bounded surface and texture lifecycle;
• packed host-memory upload and non-graphical present-state tracking.

It allocates no display or GPU resource. A present validates ownership, dimensions, format, and upload state, then records a serial and FNV-1a content hash for test inspection.

PS5 discovery boundary

The PS5 probe has two layers:

• portable logic that iterates an immutable symbol-name table and records only resolved: true|false;
• a PS5 loader shim limited to dlopen, dlsym, and dlclose.

Resolved addresses are compared with NULL, then discarded. They are never logged, returned, cast to a function type, or invoked. The probe does not call even apparently read-only exports because their signatures and ABI remain unverified.

Phase-0.5 startup boundary

The stock SDK v0.41 crt1.o is outside the trusted runtime boundary: its reachable _start graph performs kernel credential and syscall-bound writes and initializes a module-capable rtld. A compiler trace proves that -nostartfiles -nodefaultlibs can omit that object, but the exact public loader caller needed to prove entry stack, argument ownership, safe return, cleanup, and crash behavior is absent from the pinned local evidence.

Accordingly, CHIMERA_GFX_BUILD_PS5_MINIMAL_STARTUP=ON always fails configuration. There is no candidate source or artifact. The design may be reopened only after the evidence listed in docs/runtime/minimal-crt-feasibility.md is available and reviewed.

Artifact execution policy is a separate, fail-closed boundary. Static eligibility requires execution_eligible=true and a SHA-256 absent from the permanent denylist. Passing that layer never grants execution authority.

Phase-0.6 controlled runtime boundary

Phase 0.6 identified the exact installed Payload Manager v0.3.1 and ps5-payload-dev/elfldr v0.23. The normal SDK CRT is acceptable for design only when every temporary effect is documented and bounded; __patch_init alone is no longer an automatic blocker.

The exact chain is not bounded: ptrace single-step loops and detached payload runtime have no deadline, cleanup and credential failure paths are unresolved, Payload Manager launch is not SHA-256-bound, and manager upload writes persistent storage. The historical Phase-0.6 profile therefore remained execution_eligible=false and no Phase-0.6 lifecycle artifact exists.

Future consumers must validate the artifact manifest, permanent denylist, controlled runtime profile, exact device firmware, exact local bytes, and budgets together. The static gate always returns execution_authorized=false. See ADR-0010.

Phase-0.7 hardened deployment boundary

Phase 0.7 preserves the Phase-0.6 record and creates new private hardened runtime artifacts. elfldr now bounds ptrace and child lifetime, restores and checks all credential fields, centralizes cleanup, reaps every controlled child, and rehashes received payload bytes. The controlled Payload Manager hashes and streams one no-follow file descriptor and is compiled for one exact firmware/artifact identity.

The lifecycle payload uses normal SDK v0.41 startup, sends one notification, and calls _exit. It contains no GNM, VideoOut, SDL, payload-network, retry, or autoload path. Complete source/map/disassembly callgraphs remain part of the audit because static linkage means imports alone are insufficient evidence.

The current architecture state is READY_FOR_HARDENED_RUNTIME_DEPLOYMENT offline only. It permits packaging and review; it does not permit connection, installation, transfer, or execution. See ADR-0011.

The candidate runtime module name libSceGnmDriver.sprx is an inference from the public stub filename and the SDK's documented dynamic-loading convention; it is not treated as proven on any firmware.

Phase-0.9A anti-brick design boundary

Phase 0.9A adds only an offline transaction contract and a virtual host simulator. It does not add an installer, PS5 path, device transport, target artifact or production runtime code. The simulator holds logical objects, mounts, hashes and writes in memory and marks every result as non-hardware evidence.

Hardened elfldr and controlled Payload Manager have independent transactions, backups, target mappings, approvals, switches and rollbacks. No combined action or component order is inferred. The lifecycle probe is excluded. In-place overwrite and a two-rename interval with a missing live name are forbidden. All fourteen PS5 power-loss boundaries and all filesystem atomicity and durability properties remain UNPROVEN; any one blocks installation. See docs/runtime/phase-0.9-installation-transaction-design.md.

Phase-0.9B bounded observer boundary

Phase 0.9B stops before target implementation. The normal SDK v0.41 _start graph reaches __patch_init() before main and therefore violates this phase's kernelwrite-free requirement. -nostartfiles -nodefaultlibs can omit that graph, but the bare-entry return/exit, crash and loader-cleanup contract is still unproven.

The hardened controlled route also passes stdio=-1 to the payload. The controlled manager provides connect, send and close operations but no receive operation; the loader's fixed exit response carries no payload data. Therefore there is no proven non-persistent observer output channel. No observer source, target, ELF, map or artifact package exists. Host-only mocks validate the result contract and fail-closed BLOCKED record, not PS5 behavior. See docs/runtime/phase-0.9b-bounded-observer-design.md.

Phase-0.9C observer execution-feasibility boundary

Phase 0.9C closes the offline design question with BLOCKED_MULTIPLE_FOUNDATIONAL_CONTRACTS. The loader sets RIP, RDI, and a synthetic return address, but it does not prove entry stack alignment or a safe post-return continuation. Normal SDK startup reaches __patch_init; omitting that runtime also removes the only reviewed syscall, import, time, heap, and libc initialization path. No safe normal/error/deadline exit and joint cleanup contract remains.

The host-only D1 model defines a fixed 4096-byte caller-owned record with nonce/request binding, two firmware fields, capability bitmaps, checksums, deadline, cleanup status, and a final completion marker. Hardened elfldr does not own such a buffer: its current payloadout lives in the child mapping. The controlled manager connects, sends, and closes without receiving; the loader discards wait status. The protocol is therefore a future contract, not a target implementation or output channel. No observer source, target, artifact, map, package, device operation, or authorization exists.

Phase-0.9D existing-stack readback boundary

Phase 0.9D does not revisit target startup or create an observer. It audits the already present elfldr and Payload Manager request surfaces. Their file reads feed listing, metadata, hash-before-launch, or host-to-elfldr transmission; no route frames and returns an arbitrary file to the host. The result is BLOCKED_NO_READBACK_PATH.

The host backup state machine therefore remains a contract only: two separate exclusive local files, exact byte counts, close/reopen/hash, and full size/hash/byte comparison. Matching copies could establish OFF_DEVICE_BACKUP_VALID, never RECOVERY_PROVEN. Current live component paths, external exploit repeatability, durable restoration, and power-loss recovery remain unproven. See docs/runtime/phase-0.9d-readback-feasibility.md.

Phase-0.9E external bootstrap boundary

The architecture before hardened elfldr is not locally source-bound. The bounded inventory found an exact Y2JB-named ZIP and byte-exact opaque SIECAF member, but no acceptable parser, exact-used deployment evidence, port-9020 listener source/binary, or exact sender implementation. The port-9020 material in the elfldr README describes only a host stream into a pre-existing rudimentary loader; it is not that loader's protocol or implementation.

Consequently host-to-memory, filesystem staging, entrypoint selection, duplex output, crash cleanup, post-reboot restart, and independence from elfldr and Payload Manager remain UNPROVEN. Phase 0.9E adds no parser, emulator, target code, client, rescue payload, or artifact. Its fail-closed classification is BOOTSTRAP_IMPLEMENTATION_MISSING.

Phase-0.9E-R official-release correlation boundary

The local outer Y2JB ZIP is not byte-identical to any current official Gezine/Y2JB release asset: all official sizes and GitHub SHA-256 digests differ. Official tag source establishes a dynamic Remote JS Loader that seeks port 50000 and evaluates bounded JavaScript, while 9020 appears only in sender examples. The embedded port-9021 elfldr has no source or generator in release 1.6. These source facts do not bind the local opaque SIECAF backup or prove deployed behavior. Classification remains LOCAL_BACKUP_NOT_CORRELATED; no Phase-0.9F design gate opens.

Phase-0.9E-R2 inner-correlation boundary

The local MediaFire URL and object page are now metadata-bound, but their maker/source is not. A read-only host parser, bound to the public fixed-width SIECAF header layout, fingerprints header, metadata, and hash tables without decrypting or extracting content. The local inner differs from both the mandatory official Y2JB 1.6 4.03 inner and one date/size-motivated community autoloader inner in complete bytes and normalized structure. Classification is LOCAL_BACKUP_UNCORRELATED; the parser and fingerprints create no bootstrap, target, recovery, deployment, or runtime evidence.

Adapter boundaries

RetroArch

Phase 1.0A is implemented in a separate private chimera-retroarch fork. It links the real RetroArch frontend/runloop, a PS5 platform frontend and a deterministic static software smoke core. The headless profile uses null drivers; the second profile links RGUI and RetroArch's SDL2 video, input and audio drivers to the public PS5 SDL fork. Neither profile uses libchimera-gfx, GNM, a hardware-rendered libretro context or dynamic cores. Target artifacts remain ignored local outputs with execution eligibility disabled. Later hardware-rendered cores still require proven context, synchronization, memory-ownership and shader contracts.

Phase 1.0E adds a narrowly scoped result path to the Phase-1.0D diagnostic profile. Hardened elfldr's legacy raw-ELF route duplicates the accepted socket to payload stdout, so the payload can emit fixed 64-byte checksummed D-stage frames without creating a target-side socket or connection. The host performs one send and a write-half-close, then bounded receive on that same connection. This contract does not apply to the controlled route (stdio=-1), grants no device authority, and leaves the SDK CRT, SDL/VideoOut path and GNM boundary unchanged.

Phase 1.0I adds no runtime component. It binds the consumed H trace to the existing RetroArch/SDL source, linker map and disassembly. The architecture boundary remains at the failed first VideoOut submit: the exact call tuple is known, while errno, argument semantics, visible presentation and cleanup are not. The write-firewall status contains more state than the transmitted D12 frame, so future observability must expose the exact operation before another artifact can be reviewed.

Phase 1.0P similarly adds no runtime component. It binds the consumed O result to the exact M source, map, dynamic relocations and disassembly. The submit failure site and D12-before-D04 source order are proven, while VideoOut argument/layout semantics and the root cause remain unresolved. A future protocol needs a distinct post-D04 terminal; accepting the earlier D12 would confuse a shutdown request with lifecycle completion.

Phase 1.0Q adds only public-source provenance. The PS5 submit declarations, opaque records and constants all trace to one SDL commit lineage; the SDK has export names only and the relevant official ports consume that same SDL fork. PS4's similar API is retained as analogue evidence, never promoted to a PS5 contract. The architecture therefore remains blocked before any argument or ownership-state experiment.

Phase 1.0R adds no runtime path. It proves that the pinned PS5 SDL2main does not create an application or display context: its only pre-entry action is splash hiding and its exit action occurs after SDL_main returns. SDL's video backend already performs the splash action before VideoOut open in the tested artifact. Direct and Payload Manager transfers converge on the same hardened elfldr spawn routine. PacBrew is packaging metadata, and the distinct hbldr/shsrv launcher implementation remains unbound; it cannot be promoted to a target fix.

Phase 1.0S binds that official implementation and proves an architectural difference: hbldr substitutes an ELF into a SystemService-launched BigApp, whereas raw elfldr substitutes it into SceSpZeroConf. It does not prove that the BigApp supplies usable VideoOut ownership on firmware 9.60. The available hbldr path is also outside the Chimera execution model because it requires a device file and includes BigApp termination, runtime kernel/ptrace mutation, unbounded waits and, in current releases, possible persistent fake-app setup under /system_ex. It remains research evidence, never a runtime dependency.

Phase 1.0T adds only an offline sanitization and classification boundary for text that an operator might supply later. It has no socket implementation. The model drops serial, model, temperature, frequency, raw transcript and unknown paths; it fingerprints help command names and labels sum as a non-cryptographic 16-bit checksum. Its output schema hard-codes exact_identity=false. Any future collector remains a separately reviewed, inactive design problem because merely connecting already spawns shsrv's shell and emits sensitive greeting data.

Phase 1.0U adds no runtime component. It records a bounded local artifact inventory and distinguishes official source, a host telnet wrapper and an unpinned package recipe from a deployed target binary. No candidate was found inside the declared scope. That negative result cannot be generalized to the whole host or device and cannot satisfy the launch-context identity gate.

Phase 1.0V adds a host-only byte-stream model, not a transport. An incremental Telnet filter feeds the existing Phase-1.0T sanitizer under fixed byte/chunk limits and a one-shot state machine. The CLI exposes only an explicit offline stdin mode and literal metadata paths. Logical buffer clearing limits retained application state but does not prove physical memory erasure. No network or device boundary is crossed.

Phase 1.0W hardens the collector's Telnet, chunk, path and metadata edges and places an immutable policy object above it. The policy consumes two synthetic matching records and produces a frozen session-plan value. A test-only fake transport models one open/command/receive/close sequence. Neither component contains a live transport, persistence path or executable CLI, so the network boundary remains a separately blocked implementation concern.

Phase 1.0X places exclusive host evidence and one-shot orchestration around that immutable plan. The adapter and monotonic clock are dependency-injected; the repository provides only fakes. Receipt creation precedes adapter open, and sanitized output follows collector completion. Both files use exclusive leaf creation, file flush, close and reopen verification. There is deliberately no command-byte layer or live prompt boundary: those contracts remain blocked until exact source framing is established. File flush does not prove containing directory durability, and pre/post deadline checks cannot preempt a blocking adapter implementation.

Phase 1.0Y separates protocol evidence into legacy raw and current libtelnet/NVT source families. The framing model is deliberately independent of X orchestration: it transforms only supplied synthetic bytes and reports prompt candidates without creating boundaries for a live adapter. This avoids silently binding current-source CRLF and negotiation behavior to an unknown deployed version. A later passive contract can use plain LF, which both audited families accept, while treating all received negotiation and incomplete output as bounded failure.

Phase 1.0Z implements that later layer as a pure data contract. An immutable, target-free object contains one ASCII/LF batch and its exact completion policy. The receive accumulator consumes supplied chunks, rejects IAC and delegates sanitization to V, but it cannot seal on prompt or EOF. An externally injected synthetic hard-deadline event is the only sealing boundary. This separation keeps byte formatting and completeness checks independently testable without quietly introducing a network adapter, clock or live completion claim.

Phase 1.0AA composes X evidence and Z framing behind a closed fake boundary. Unlike X's abstract injected adapter, AA accepts only exact built-in fake types; there is no protocol a live implementation can satisfy. A synthetic event advances an explicit fake clock, while receipt, one-batch send, deadline seal, close and sanitized output form a testable order. This proves model composition only, not socket preemption, deployment identity or firmware behavior.

Phase 1.0AB separates OS feasibility from implementation. It binds the local Python _socket, select, socket.py, selectors.py and monotonic-clock identities, then validates only synthetic syscall ordering. The required future architecture is one nonblocking descriptor, readiness before every I/O call, an explicit partial-send offset, a single absolute deadline and finally-based local cleanup. Runtime source makes that sequence feasible but cannot turn selector timeouts into a hard scheduling guarantee or attest remote cleanup.

Phase 1.0AC realizes that ordering behind a dormant, target-free component. Only the exact built-in fake facade and fake clock are accepted, so no live implementation can satisfy an injected protocol. The adapter composes the Z batch/result contract with synthetic create, readiness, partial progress, deadline and close outcomes. This is integration-test infrastructure only: it adds no socket factory, address model, activation path or firmware evidence.

Phase 1.0AU closes the subsequent result-channel source-feasibility question. The official SDK exposes every primitive signature needed by the AT ownership model, but official shsrv composes none of them into a bounded channel. Its worker closes inherited descriptors and its service restarts automatically. The architecture therefore permits only a target-free canary contract next; live channel code, a target build and every device action remain outside the boundary.

Phase 1.0AV turns the unresolved launch-context claim into a causal offline contract. It holds payload and protocol identity constant while varying only the launcher identity, and requires independent one-shot approvals. Results are comparable only after submit, D04 and a distinct cleanup terminal. The contract deliberately cannot interpret a zero submit return as presentation; it contains no target implementation or activation surface.

Phase 1.0AW maps that contract onto exact historical source. A future single ELF needs a new magic and a D14 terminal guarded by completed RetroArch teardown, an empty initialized mask, valid cleanup order and an independent cleanup-error counter. Official v0.7 can duplicate raw stdout into its BigApp, but that source candidate does not make its unbounded and mutating launcher admissible.

Phase 1.0AX freezes the proposed wire and cleanup semantics independently of target code. D14 reuses the 64-byte frame's raw/result/auxiliary fields to bind initialized, cleaned, cleanup-error and rarch_main state. Only canonical D14 after D07 and D04 is terminal. This host reference cannot establish that a future RetroArch build or firmware implements the same behavior.

Phase 1.0AY fixes repository lineage as another trust boundary. The selected N tip is an exact descendant of M with unchanged diagnostic target sources and an inactive runner. Future source work must occur in a separate worktree so the historical loader checkout and consumed-run records are not rewritten.

SDL2

The future SDL2 integration will be a renderer backend that can satisfy SDL_RENDERER_ACCELERATED; it will not replace the existing PS5 window, VideoOut, audio, input, IME, or filesystem backends. This separation avoids forking unrelated platform support. The compiled scaffold reports acceleration unavailable and requires the existing software fallback.

Offline Phase-1 boundary

The VideoOut candidate is a separate CMake option that is off by default and valid only under the PS5 toolchain. Project code calls public SDL2 APIs; a staged Zlib-licensed overlay removes upstream keyboard/IME initialization. SDL retains ownership of its public-source VideoOut declarations and layouts. The target does not link SDL2main, so the firmware gate runs before SDL or system-service initialization. See ADR-0006 and docs/phase1/.

Failure model

All unknown firmware, missing exports, version mismatches, partial initialization, or unsupported requests fail closed. Later hardware phases must add bounded waits, watchdog-visible progress, crash logs without secrets or addresses, and cleanup that can be audited independently of the success path.