# Spec Review: Lite Entry Point
**Reviewer:** Morticia (adversarial QA)
**Revision:** 4/5
**Date:** 2026-03-18
**Spec under review:** `planning/lite-entry-point/spec.md`

---

## Rev 3 Issue Verification

### Issue A (Rev 3) — Stale "Option A" section contradicts final architecture → FIXED

Line 44 now contains a prominent note: "This section describes the initial framing of Option A. The analysis below led to additional lite copies beyond what was originally anticipated. See 'Final Architecture: Lite-Only Copies of Shared Files' for the complete decision reached after full dependency analysis." Line 46 also now correctly lists all six lite files by name (including `AvoNetworkCallsHandlerLite`, `AvoBatcherLite`, `AvoStreamIdLite`). The section no longer claims these files are "reused directly." The fix is accurate and removes the contradiction for a sequential reader.

### Issue B (Rev 3) — Line 57 misattributes why `AvoDeduplicatorLite` is needed → FIXED

Lines 58-60 now correctly categorize all five files with per-file reasons: Three (`AvoNetworkCallsHandler`, `AvoBatcher`, `AvoStreamId`) need lite copies because they import `AvoInspector` (full). One (`AvoDeduplicator`) needs a lite copy because it imports `AvoSchemaParser` which imports `AvoEncryption` → `@noble/curves`. One (`AvoSchemaParser`) needs a lite copy because it directly imports `AvoEncryption` → `@noble/curves`. The `AvoInspector` misattribution for `AvoDeduplicator` is gone.

### Issue C (Rev 3) — `scripts/` directory not mentioned → FIXED

Lines 196-199 now read: "The `scripts/` directory does not currently exist in the repo. Before creating any files under it, run: `mkdir -p scripts`". The instruction is present exactly where the implementer will encounter it, immediately before the first scripts file is introduced.

### Issue D (Rev 3) — `AvoSchemaParserLite.ts` import path contradiction → FIXED

Line 458 now reads: "Change import path for types: `import type { EventProperty, SchemaChild } from "./AvoNetworkCallsHandlerLite"` (use the lite copy, which is in the same `src/lite/` directory; importing from `"../AvoNetworkCallsHandler"` would reference the full handler which is not in the `tsconfig.lite.json` include list and would cause the `--noEmit` isolation check to fail)". The path is correct, the reasoning is explicit, and the contradiction with the dependency table is gone.

**All 4 Rev 3 issues are genuinely fixed.** No false fixes detected.

---

## New Issues Found in Rev 4

### New Issue E — "Shared modules used as-is" sub-section still lists AvoNetworkCallsHandler and AvoBatcher as safe

**Severity: LOW** — Superseded by the Final Architecture section, but still misleading.

Lines 365-369 ("### Shared modules used as-is (no modification)") list:
- `src/AvoNetworkCallsHandler.ts` — "type-only eventSpec import, safe"
- `src/AvoBatcher.ts` — "type-only eventSpec import, safe"
- `src/AvoStreamId.ts` — "imports `AvoInspector` (full)... the lite `AvoStreamId` is shared"

These statements are from the intermediate dependency-analysis walkthrough and were superseded by the final architecture. `AvoNetworkCallsHandler.ts` and `AvoBatcher.ts` both receive lite copies in the final architecture (lines 438-439, 500-506). An implementer reading the "Dependency Analysis" section linearly will encounter this claim before reaching the "Final Architecture" section and may be misled into skipping the creation of `AvoNetworkCallsHandlerLite` and `AvoBatcherLite`.

The "Option A" note fix (Issue A) covers the top of the document, but this sub-section is three pages later with no equivalent "this is superseded" marker. The spec already demonstrates a willingness to add such notes (line 44) — a brief "(Superseded — see Final Architecture below)" on the section header would close the gap.

**Required fix:** Add "(Superseded — see Final Architecture below)" to the heading at line 365, or remove/rewrite the three lines for `AvoNetworkCallsHandler.ts`, `AvoBatcher.ts`, and `AvoStreamId.ts` to state that these files get lite copies rather than being used as-is.

---

### New Issue F — Drift detection PAIRS omits `AvoSchemaParserLite` with no explanation

**Severity: VERY LOW** — Does not affect implementation correctness; affects only CI maintenance.

The `scripts/verify-lite-sync.sh` PAIRS array (lines 206-211) lists four pairs:
- `AvoNetworkCallsHandler` / `AvoNetworkCallsHandlerLite`
- `AvoBatcher` / `AvoBatcherLite`
- `AvoStreamId` / `AvoStreamIdLite`
- `AvoDeduplicator` / `AvoDeduplicatorLite`

`AvoSchemaParserLite` is intentionally omitted — it has more than a single import substitution (multiple methods deleted, not just one import line changed). Adding it to the PAIRS array would produce false drift alerts because the diff will far exceed 10 lines by design. However, the spec does not document WHY it is omitted. A future maintainer who adds `AvoSchemaParser` to the drift check will set the wrong threshold and get either false positives (threshold too low) or no signal (threshold too high).

**Required fix:** Add a comment in `verify-lite-sync.sh` above the PAIRS definition, e.g.: `# AvoSchemaParser is excluded: AvoSchemaParserLite removes entire methods (encryption), not just one import line. Drift there requires manual review.` One line is sufficient.

---

## Carry-Over Observations (Non-blocking, noted from prior revisions)

- **Drift threshold of 10 lines** (originally Rev 2 Issue 2.1) — still potentially brittle given that some pairs have 6–8 substitution lines. No documentation of expected baseline per-pair diff counts. Low-priority maintenance concern; CI threshold should be validated once the lite copies are actually created.
- **`_avoFunctionTrackSchemaFromEvent` access modifier** (originally Rev 2 Issue 2.2) — Spec correctly keeps it `private`. Still lacks a note that Avo-generated callers use `(inspector as any)._avoFunction...` to bypass TypeScript's access restriction. Minor documentation gap; does not affect the implementation.
- **7 KB target not pre-validated** (originally Rev 2 Issue 3.2) — CI enforcement is now in place. The 7 KB risk is acknowledged. No pre-implementation estimate exists, but the CI check will catch it.
- **"Revised Architecture: Shared State Module" section (lines 397-426)** — The `AvoInspectorState.ts` code block and the "Then `AvoInspector.ts` re-exports the statics from `AvoInspectorState`..." text describe an approach explicitly rejected by the spec. This working-through content is harmless (clearly marked as undesirable) but adds document length without implementation value.

---

## Stage Scores

### Stage 1: Architecture & Approach — 23/25

All four Rev 3 architectural issues are fixed. The Option A note, per-file justifications for lite copies, `mkdir -p scripts`, and `AvoSchemaParserLite` import path are all correct. The remaining deduction is for the stale "Shared modules used as-is" sub-section (Issue E) which still lists `AvoNetworkCallsHandler.ts` and `AvoBatcher.ts` as reusable, contradicting the final architecture. This is a minor readability hazard, not a blocker, but it is a factual inaccuracy left in the spec.

### Stage 2: Completeness & Quality — 24/25

The file list is complete (12 files), all import path substitutions are specified, `mkdir -p scripts` is present, and the dependency table is accurate. The single deduction is for Issue F (no documentation of why `AvoSchemaParserLite` is excluded from drift detection), which will cause a maintenance confusion but has zero impact on the initial implementation.

### Stage 3: Tests & Edge Cases — 24/25

All nine acceptance criteria test categories remain correctly specified. Static isolation test, `@ts-expect-error` pattern, and `AvoSchemaParserLite` test file are all present. The `check-lite-size.js` terser path is correct. One minor deduction for the absence of an exports-map integration test (acknowledged carry-over; `npm pack --dry-run` acceptance criterion partially covers it).

### Stage 4: Performance & Feasibility — 24/25

`scripts/webpack.lite-size.config.js` is complete (lines 283-303), `mkdir -p scripts` is present, the `analyze.sh` parallel is documented, the `types` exports-map constraint is correctly noted. One minor deduction retained for the 7 KB target not being pre-validated before implementation begins (CI enforces it post-build, but there is no estimate to confirm feasibility without running the build).

---

## Score Summary

| Stage | Score | Max | Notes |
|---|---|---|---|
| Stage 1: Architecture & Approach | 23 | 25 | All Rev 3 issues fixed; minor deduction for stale "Shared modules used as-is" sub-section (Issue E) |
| Stage 2: Completeness & Quality | 24 | 25 | Comprehensive and accurate; minor deduction for undocumented AvoSchemaParserLite omission from drift detection (Issue F) |
| Stage 3: Tests & Edge Cases | 24 | 25 | Strong test coverage; exports-map integration test absence acknowledged carry-over |
| Stage 4: Performance & Feasibility | 24 | 25 | webpack config complete; scripts/ creation documented; 7 KB pre-validation gap is acknowledged carry-over |
| **Total** | **95** | **100** | |

---

## Issues Requiring Attention

**Should fix before handoff (non-blocking):**

1. **"Shared modules used as-is" sub-section (Issue E)** — Lines 365-367 still state `AvoNetworkCallsHandler.ts` and `AvoBatcher.ts` are "safe" and reusable, which contradicts the final architecture. Add "(Superseded — see Final Architecture below)" to the section heading at line 365, or reword the entries to say these files receive lite copies.

2. **Drift detection PAIRS omits AvoSchemaParserLite with no explanation (Issue F)** — Add a one-line comment in `verify-lite-sync.sh` above the PAIRS definition explaining that `AvoSchemaParserLite` is excluded because it has more than a single import substitution (entire methods removed), requiring manual review rather than automated threshold checking.

**No issues block implementation.** The four Rev 3 blockers are fixed. The spec is ready for implementation with the two minor non-blocking issues noted above.