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.