AXP-Resurection/specs/003-lineage-23-vanilla-build/spec.md

Feature Specification: LineageOS 23.2 vanilla build for sunfish

Feature Branch: 003-lineage-23-vanilla-build

Created: 2026-08-09

Status: Active — implementation next (vanilla sync/build on rom-dev01)

Input: Produce the first vanilla LineageOS 23.2 / Android 16 build for sunfish, copy images to the laptop, flash, and verify boot plus basic hardware — with no microG, KernelSU, or hardening yet.

Context / non-goals

Prerequisites:

• 001-development-environment sufficiently complete to sync/build;
• 002-axp-reference-capture P1 complete (GOLDEN labeled; LAB stock rescue documented). Flash LAB only — never GOLDEN (docs/device-roles.md).

Out of scope for this feature:

• microG / Phonesky / signature spoofing;
• KernelSU / SUSFS / Magisk parity;
• call recording, FLAG_SECURE toggles, privacy extras;
• project signing / AVB / OTA implementation;
• Graphene/AXP/Divest patch ports.

Build target: userdebug with development/test-keys.

User Scenarios & Testing (mandatory)

User Story 1 - Reproducible vanilla sync & build (Priority: P1)

As the developer, I can sync LineageOS 23.2 for sunfish on rom-dev01 and complete a build that emits flashable images, with manifest/revisions recorded.

Why this priority: Establishes the real base ROM.

Independent Test: Build finishes; artifact paths listed; manifest revision document stored under /srv/rom with hashes.

Acceptance Scenarios:

1. Given android-build on rom-dev01, When I sync the LOS 23.2 sunfish source via repo, Then the tree matches a documented manifest revision.
2. Given the synced tree, When I build userdebug for sunfish with conservative parallelism, Then the build completes without requiring project patches beyond LOS-needed device/kernel trees.
3. Given a successful build, When I collect outputs, Then images/ zip needed to flash sunfish are in /srv/rom/artifacts (or documented path) with SHA-256 hashes and a compressed build log.

---

User Story 2 - Flash from laptop (Priority: P1)

As the developer, I rsync artifacts to the laptop and flash the Pixel 4a over USB using fastboot/adb, following the recovery notes from 002 if something fails.

Why this priority: Closes the loop on the thin-client workflow.

Independent Test: Device boots the new build; getprop shows LineageOS / expected fingerprints (not AXP).

Acceptance Scenarios:

1. Given artifacts on the laptop, When I flash per documented steps, Then the device boots into the vanilla LOS build.
2. Given a failed flash/boot on LAB, When I follow 002 LAB stock factory rescue docs, Then LAB returns to usable stock. GOLDEN is not touched.

---

User Story 3 - Basic hardware smoke test (Priority: P1)

As the developer, after first boot I verify essential radios and peripherals well enough to trust this build as the clean base for later features — and I know what was already broken on vanilla LOS before we add patches.

Why this priority: A boot-only “success” that breaks telephony/Wi-Fi is not a usable base. Later regressions must be attributable.

Independent Test: Checklist results stored for P1 and extended items on the vanilla build.

Acceptance Scenarios:

1. Given first boot completed, When I run the P1 smoke set, Then each item either works or is logged as a blocking defect with evidence:

   • encryption / PIN
   • SELinux mode (Enforcing expected)
   • Android security patch level
   • vendor security patch level / build baseline
   • SIM detection
   • mobile data
   • phone calls
   • SMS (send/receive as applicable)
   • Wi-Fi
   • Bluetooth
   • GPS
   • camera(s)
   • audio (speaker/mic)
   • NFC
   • sensors (basic)
   • fingerprint
   • USB data / ADB
   • charging

2. Given P1 smoke done, When I run the extended baseline set, Then each is recorded (need not all be P1 blockers, but must not be skipped silently):

   • airplane mode
   • flashlight
   • vibration
   • screen rotation
   • USB OTG (if hardware/cable available)
   • headphone jack
   • WebView implementation / basic page load
   • app sideload install smoke (non-Google)
   • Widevine / DRM security level
   • eSIM capability/state, if available
   • WireGuard kernel capability/baseline
   • bootloader version
   • baseband / modem version

3. Given smoke results, When deciding to proceed to 004, Then no unresolved P1 hardware blockers remain (or they are explicitly accepted with rationale).

---

Edge Cases

• Build disk/oom with 52 GB + swap: document job -j and failure recovery (out/ cleanup).
• Partial artifact set: do not flash until required partitions/images are present and hashed.
• Do not install Magisk/KernelSU “just to test” in this feature.

Requirements (mandatory)

Functional Requirements

• FR-001: Initialize from the documented official LineageOS 23.2 manifest/branch (repo init → sync) and capture a revision-locked resolved manifest (e.g. repo manifest -r) for every known-good build.
• FR-002: Build userdebug images with test-keys / default LOS signing for this stage.
• FR-003: Record manifest, revisions, build variant, config, hashes, and compressed log for the successful build.
• FR-004: Publish artifacts to /srv/rom/artifacts and document rsync + flash procedure.
• FR-005: Boot sunfish on the vanilla build and run the P1 + extended hardware/baseline checklist (record results even for non-blockers).
• FR-006: Keep tree free of microG/Phonesky/KernelSU/hardening patches intended for later features.
• FR-007: On LAB flash failure, follow 002 LAB stock factory rescue; never flash or wipe GOLDEN as part of recovery.

Key Entities

• Vanilla LOS build: clean base artifact set.
• Build metadata: manifest + hashes + log bundle.
• Smoke checklist: hardware/regression minimum for this stage.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: One successful sunfish userdebug build exists with recorded metadata and hashes.
• SC-002: Device boots that build after laptop-side flash.
• SC-003: P1 and extended hardware/baseline checklists are completed and stored (extended items may be non-blocking but must be recorded).
• SC-004: No dependency on LSPosed/Magisk modules for this stage’s success.
• SC-005: This build is tagged/kept as a known-good flashable baseline for regression when later features break the device.