docs: apply pin-point delta edits for correctness, consistency, and reviewer friction

Implementation plan improvements:
- Fix event name consistency: DOZE_FALLBACK → EVT_DOZE_FALLBACK_TAKEN in Test Matrix
- Lock receiver export policy as AC: only BootReceiver exported
- Handle unknown Content-Length: add streaming guard for -1 responses
- Ensure single joined error mirrors AC: validation failures return one joined message
- Add webDir echo and device idle hint to diagnostics: include webDir path and isDeviceIdleMode
- Make degradation visible in UI AC: matrix shows 'Degraded timing (Doze)' when fallback active
- Add Room migrations guard: no-op migration and fallbackToDestructiveMigration(false) test

Analysis doc improvements:
- Trim WAKE_LOCK guidance: not required unless explicitly acquiring/releasing wakelocks
- Add Boot receiver priority note: android:priority has no effect for BOOT_COMPLETED
- Fix application android:name accuracy: only set if custom Application class exists
- Mirror Cordova compat note in Build section: include only when using Cordova plugins
- Annotate Mermaid flow with canonical errors: show where canonical errors are produced
- Link Truth Table to test UI buttons: integrate with Open Channel/Exact Alarm Settings buttons

All changes maintain existing structure with surgical precision edits.
This commit is contained in:
Matthew Raymer
2025-10-24 10:56:49 +00:00
parent eb2ab62a58
commit 0bef820d0c
2 changed files with 32 additions and 6 deletions

View File

@@ -496,12 +496,26 @@ public class SecureNetworkClient {
connection.setConnectTimeout(TIMEOUT_SECONDS * 1000);
connection.setReadTimeout(TIMEOUT_SECONDS * 1000);
// Limit response size
// Limit response size (handle unknown Content-Length)
long contentLength = connection.getContentLengthLong();
if (contentLength > MAX_RESPONSE_SIZE) {
throw new NetworkException("E_RESPONSE_TOO_LARGE", "Response too large");
}
// Stream with size guard for unknown Content-Length
long read = 0;
try (InputStream in = connection.getInputStream()) {
byte[] buf = new byte[8192];
int n;
while ((n = in.read(buf)) != -1) {
read += n;
if (read > MAX_RESPONSE_SIZE) {
throw new NetworkException("E_RESPONSE_TOO_LARGE", "Response too large");
}
// process / buffer as needed
}
}
return readResponse(connection);
}
}
@@ -671,6 +685,7 @@ public class DatabaseMaintenance {
- **Index Optimization**: Maintain database performance
- **Data Retention**: Configurable retention policies
- **Performance Monitoring**: Track maintenance impact
- **Migration Safety**: Add a **no-op migration** for current schema version and a test that app boots with `fallbackToDestructiveMigration(false)`
## Documentation Updates
@@ -870,6 +885,7 @@ interface ScheduleResponse {
- [ ] Shows live channel state
- [ ] Provides actionable buttons for issues
- [ ] Exports diagnostics as JSON
- [ ] When fallback is active, matrix shows **"Degraded timing (Doze)"** and last event includes `EVT_DOZE_FALLBACK_TAKEN`
### Error Handling
- [ ] All @PluginMethod calls validate inputs
@@ -879,6 +895,7 @@ interface ScheduleResponse {
- [ ] Rejects unknown keys with single joined message
- [ ] Channel policy enforced: missing/disabled channel returns `E_CHANNEL_MISSING` or `E_CHANNEL_DISABLED` with "Open Channel Settings" CTA
- [ ] HTTPS-only; connect/read timeouts ≤ 30s; content-length hard cap ≤ 1 MB; oversize → `E_RESPONSE_TOO_LARGE`
- [ ] Validation failures return **one joined message** surfaced to UI
### Reliability
- [ ] Reboot scenarios reliably deliver notifications
@@ -886,6 +903,7 @@ interface ScheduleResponse {
- [ ] Clear logs explain system behavior
- [ ] User-visible reasoning for failures
- [ ] Rescheduler uses unique key `(requestCode|channelId|time)` and **UPSERT** semantics; log `EVT_BOOT_REHYDRATE_DONE(count=n)`
- [ ] Only `BootReceiver` is exported; all other receivers remain `exported="false"`
### Testing
- [ ] Test UI modularized into scenarios
@@ -936,7 +954,7 @@ By following this plan, the test app will become more maintainable, reliable, an
- @PluginMethod bodies ≤ 25 LOC, delegate to use-cases.
- "Copy Diagnostics (JSON)" button functional.
**Diagnostics MUST include:** appId, versionName/code, manufacturer/model, API level, timezone, `capacitor.config.json` plugin section echo, five status fields, last 50 event IDs.
**Diagnostics MUST include:** appId, versionName/code, manufacturer/model, API level, timezone, `capacitor.config.json` plugin section echo, five status fields, last 50 event IDs, `webDir` effective path echo, `isDeviceIdleMode` boolean.
- If exact alarm is denied/quota-limited, UI surfaces **"Degraded timing (Doze)"** and logs `EVT_DOZE_FALLBACK_TAKEN`.
### Phase 2 DoD
@@ -973,7 +991,7 @@ By following this plan, the test app will become more maintainable, reliable, an
|---|---|---|
| Immediate notify | scheduleDailyNotification | Channel ON, perms granted | Success + toast seen |
| Channel disabled path | isChannelEnabled/openChannelSettings | Disable channel | Canonical `E_CHANNEL_DISABLED` |
| Exact alarm denied path | openExactAlarmSettings | Revoke exact alarm | Fallback path taken; logged `DOZE_FALLBACK` |
| Exact alarm denied path | openExactAlarmSettings | Revoke exact alarm | Fallback path taken; logged `EVT_DOZE_FALLBACK_TAKEN` |
| Boot reschedule | BootReceiver | Reboot emulator | One (not duplicate) schedule restored |
| Doze idle window | scheduleDailyNotification | Device in idle | Fallback path taken; logged `EVT_DOZE_FALLBACK_TAKEN`; no crash |
| Bad schema rejects | bridge.ts + schema-validation.ts | Add unknown key / oversize title | Canonical `E_BAD_CONFIG` with single joined message |